Available only in PRO Edition

Formatters Extension

This functionality is available in the PRO edition only.

The gantt.ext.formatters extension provides two formatting methods:

Duration Formatter

The gantt.ext.formatters.durationFormatter(config) method returns a new instance of the DurationFormatter.

Configuration

durationFormatter (config): DurationFormatter - creates a Duration Formatter
- config? - (object) - optional, a configuration object which can include the following attributes:
  - enter? - (string) - specifies the default format for the parse method, which is used when an input value is entering without units. Default value: "day".
  - store? - (string) - specifies the format for the duration values storage in the gantt. This property affects the output value of the parse method. Default value: "hour".
  - format? - (string | Array <string>) - specifies the format for the output value. Supported values: "auto", "minute", "hour", "day", "week", "month", "year", "an array containing any of these values". The "auto" value means the formatter will try to select an appropriate unit depending on provided value (i.e. larger values will be formatted as days/months/years, smaller values will be formatted as minutes/hours).
  - short? - (boolean) - sets short labels (abbreviations) for time units. Default value: false
  - minutesPerHour? - (number) - defines how duration values will be converted from minutes to hours and vice-versa. Default value: 60
  - hoursPerDay? - (number) - defines how duration values will be converted from hours to days and vice-versa. Default value: 8
  - hoursPerWeek? - (number) - defines how duration values will be converted from hours to weeks and vice-versa. Default value: 40
  - daysPerMonth? - (number) - defines how duration values will be converted from days to months and vice-versa. Default value: 30
  - daysPerYear? - (number) - defines how duration values will be converted from days to years and vice-versa. Default: 365
  - labels? - (object) - defines text labels for different time units. These labels are used both for parsed and formatted values.
    - minute? - (object) - configuration for minutes
      - full? - (string) - full text label for minutes
      - plural? - (string) - plural text label for minutes
      - short? - (string) - short text label for minutes
    - hour? - (object) - configuration for hours
      - full? - (string) - full text label for hours
      - plural? - (string) - plural text label for hours
      - short? - (string) - short text label for hours
    - day? - (object) - configuration for days
      - full? - (string) - full text label for days
      - plural? - (string) - plural text label for days
      - short? - (string) - short text label for days
    - week? - (object) - configuration for weeks
      - full? - (string) - full text label for weeks
      - plural? - (string) - plural text label for weeks
      - short? - (string) - short text label for weeks
    - month? - (object) - configuration for months
      - full? - (string) - full text label for months
      - plural? - (string) - plural text label for months
      - short? - (string) - short text label for months
    - year? - (object) - configuration for years
      - full? - (string) - full text label for years
      - plural? - (string) - plural text label for years
      - short? - (string) - short text label for years

Examples:

Initialize Duration Formatter with the default settings:

const formatter = gantt.ext.formatters.durationFormatter();
// an instance of the formatter object is created using the factory method

enter:

formatter.parse("1"); // entered value: 1 day - if enter:"day" (default)
formatter.parse("1"); // entered value: 1 hour - if enter:"hour"

store:

formatter.parse("1 day"); // stored value: 8 - if store:"hour"
formatter.parse("1 day"); // stored value: 480 - store:"minute"

format

gantt.ext.formatters.durationFormatter({
    format: ["hour", "minute"],     store:"minute"
}).format(260); // 4 hours 20 minutes
 
gantt.ext.formatters.durationFormatter({
    format: "hour",     store:"minute"  
}).format(260);// 4.33 hours

short

gantt.ext.formatters.durationFormatter({
    format: ["week", "hour", "minute"],
    store:"minute",
    short: false   }).format(10021); //"4 weeks 7 hours 1 minute"
 
gantt.ext.formatters.durationFormatter({
    format: ["week", "hour", "minute"],
    store:"minute",
    short: true  }).format(10021); //"4wk 7h 1min"

Example of the full configuration:

const formatter = gantt.ext.formatters.durationFormatter({
    // default values
    enter: "day",
    store: "hour",
    format: "auto",
    short: false,
    minutesPerHour: 60,
    hoursPerDay: 8,
    hoursPerWeek: 40,
    daysPerMonth: 30,
    daysPerYear: 365,
    labels: {
        minute: {
            full: "minute",
            plural: "minutes",
            short: "min"
        },
        hour: {
            full: "hour",
            plural: "hours",
            short: "h"
        },
        day: {
            full: "day",
            plural: "days",
            short: "d"
        },
        week: {
            full: "week",
            plural: "weeks",
            short: "wk"
        },
        month: {
            full: "month",
            plural: "months",
            short: "mon"
        },
        year: {
            full: "year",
            plural: "years",
            short: "y"
        }
    }
});

API

The created instance of the DurationFormatter provides the following methods:

canParse (value): boolean - returns true if the provided string can be parsed into the duration value, otherwise - returns false
- value - (string) - the string that will be checked

const formatter = gantt.ext.formatters.durationFormatter();
console.log(formatter.canParse("1 day"));
// true
 
console.log(formatter.canParse("abc"));
// false

format (value): string - converts the provided duration value into the duration string
- value - (number) - the duration value that will be converted

const formatter = gantt.ext.formatters.durationFormatter();
console.log(formatter.format(24));
// 3 days

parse (value): number - parses the provided string into the duration value. If the value can’t be parsed, ‘null’ will be returned
- value - (string) - the string that will be converted

const formatter = gantt.ext.formatters.durationFormatter();
console.log(formatter.parse("1 day"));
// 8

Read details about the durationFormatter method in the Work Time Calculation article.

Link Formatter

The gantt.ext.formatters.linkFormatter(config) method returns a new instance of the LinkFormatter. It reuses some methods and the configuration of the Duration Formatter

Configuration

linkFormatter (config): LinkFormatter - create a Link Formatter
- config? - (object) - optional, a configuration object which can include the following attributes:
  - durationFormatter? - (DurationFormatter) - an instance of the DurationFormatter created by the gantt.ext.formatters.durationFormatter(). It affects how lag/lead values of links are parsed and formatted:
  - labels? - (object) - locale labels for different types of links
    - finish_to_start? - (string) - labels for the Finish to Start links
    - start_to_start? - (string) - labels for the Start to Start links
    - finish_to_finish? - (string) - labels for the Finish to Finish links
    - start_to_finish? - (string) - labels for the Start to Finish links

Examples:

Initialize Link Formatter with the default settings:

const formatter = gantt.ext.formatters.linkFormatter();
// an instance of the formatter object is created using the factory method

short:

gantt.ext.formatters.linkFormatter()
   .format({id:1, type:"1", source: 1, target: 2, lag: 5});
//"1SS+5 days"
 
var durationFormatter = gantt.ext.formatters.durationFormatter({
    short: true
});
gantt.ext.formatters.linkFormatter({durationFormatter: durationFormatter})
    .format({id:1, type:"2", source: 1, target: 2, lag: -1});
//"1FF-1d"

labels:

const formatter = gantt.ext.formatters.linkFormatter({
    //default values
    durationFormatter: gantt.ext.formatters.durationFormatter(),
    labels: {
        finish_to_start: "FS",
        start_to_start: "SS",
        finish_to_finish: "FF",
        start_to_finish: "SF"
    }
});

API

The created instance of the LinkFormatter provides the following methods:

canParse (value): boolean - returns true if the provided string can be parsed into the link object, otherwise - returns false
- value - (string) - the string that will be checked

const formatter = gantt.ext.formatters.linkFormatter();
console.log(formatter.canParse("1FS + 1 day"));
// true
 
console.log(formatter.canParse("abc"));
// false

format (link): string - converts the provided link value into the string
- value - (Link) - the link object that will be converted

const formatter = gantt.ext.formatters.linkFormatter();
 
formatter.format({id:1, type:"1", source: 1, target: 2, lag: 5});
//"1SS+5 days"

parse (value): object - parses the provided string into the link object. If the value can’t be parsed, ‘null’ will be returned. Note that the link.target of the given link will have "null" value
- value - (string) - the string that will be converted

const formatter = gantt.ext.formatters.linkFormatter();
 
formatter.parse("1SS+5 days");
// {id:1, type:"1", source: 1, target: null, lag: 5}

Format info

The LinkFormatter supports two formats of links:

${WBS} - short format
- ${WBS} - task WBS code

const formatter = gantt.ext.formatters.linkFormatter();
 
console.log(formatter.parse("1.1"));
// {id:1, type:"0", source: 2, target: 3, lag: 0}
 
console.log(formatter.format({id:2, type:"0", source: 1, target: 3, lag: 0}));
// 1.1

${WBS}${TYPE}${LAG} - complete format
- ${WBS} - task WBS code
- ${TYPE} - link type. Supported values: 'FF', 'FS', 'SS', 'SF', or as defined by the labels config of the LinkFormatter.
- ${LAG} - link lag. It's value can be either positive or negative - +1 day, -1 day. Supported format is defined by the durationFormatter parameter provided into the constructor method of the LinkFormatter.

const formatter = gantt.ext.formatters.linkFormatter();
 
console.log(formatter.parse("1.1SS + 1 day"));
// {id:1, type:"1", source: 2, target: null, lag: 1}
 
console.log(formatter.format({id:1, type:"1", source: 2, target: 3, lag: 1}));
// 1.1SS + 1 day

Finish-To-Start links with no lag/lead will be formatted using the short format, while the other links will be formatted using the complete format. Similarly, if only WBS code of a task is provided into the parse method, the formatter will assume Finish-to-Start type and zero lag time.

Read details about the linkFormatter method in the Inline Editing in Grid article.