The VisualScript Cookbook

16/18 Page

Creating a Gantt Chart with VisualScript

A Gantt chart is one of the specialized diagrams you can create with VisualScript.

Gantt charts:

  • Require a specialized Document object that can only be used to generate a Gantt chart
  • There can only be one Gantt chart per visual
  • They cannot be mixed with other shapes, or appear in ShapeContainers, ShapeConnectors, Tables or other normal VisualScript layouts
  • They use a special case of Shape Data to manage and display tasks and can't allow other shape data
  • A Gantt chart is created using a special document class: VS.GanttDocument().

    Calling the AddTask() method of the VS.GanttDocument() class adds a task. Addtask() takes an array of column names and their values. These column names are predefined and fixed.

    {
    var myGanttDocument= new VS.GanttDocument();
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"},
                           {Name:VS.GanttChartColumnNames.Length,Value:"2"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Research"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Design"}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Using a column name in AddTask makes it appear in the Gantt chart, otherwise all but Task, Start, End and Length are hidden.

    {
    var myGanttDocument= new VS.GanttDocument();
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"},
                             {Name:VS.GanttChartColumnNames.Length,Value:"2"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Research"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Design"}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Setting Dates

    By default, tasks start "today" and have a length of 5 days. If the script was generated on 7/6/2018, the visual would show this without any further specification necessary.

    {
    var myGanttDocument= new VS.GanttDocument();
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"User Testing"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Implementation"}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Gantt chart

    You can set the start date for a task by assigning a value to "Start" using the YYYY-MM-DD format.

    {
    var myGanttDocument= new VS.GanttDocument();
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"User Testing"},{Name:VS.GanttChartColumnNames.Start,Value:"2018-08-11"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Implementation"}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Gantt chart - set start dates

    Note that the first task uses the default start value of today (we happened to run this script on July 6, 2018) and the second task has the assigned start date of Aug 11, 2018. Setting a new start date resets the default for subsequent tasks so task three has the same start date as task two.

    Another way of setting a start date is to use a numerical value instead of a date: {"Name":"Start", "Value":7}. This sets the start date to that number of days beyond the current default.

    {
    var myGanttDocument= new VS.GanttDocument();
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"User Testing"},{Name:VS.GanttChartColumnNames.Start,Value:"2018-08-11"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Implementation"},{Name:VS.GanttChartColumnNames.Start,Value:7}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Note, that the third task was set to start 7 days after the second and yet at first glance it appears that the task starts 11 days later (Aug 22 vs Aug 11). Why? It's because the number of days is assumed to be working days. By default weekend and US holidays are not counted as working days and there are two weekends (4 days) between 8/11 and 8/22.

    You can change the way working days are calculated using the SetOptions method:

    {
    myGanttDocument.SetOptions(AllWorkingDays,Holidays);
    }
    

    If you set AllWorkingDays to true then weekends are ignored and you can choose "USA", "UK", "Australia", "Canada" or "None" for Holidays.

    Making calendar days the same as working days we get this:

    {
    var myGanttDocument= new VS.GanttDocument();
    myGanttDocument.SetOptions(true,"None");
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"User Testing"},{Name:VS.GanttChartColumnNames.Start,Value:"2018-08-11"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Implementation"},{Name:VS.GanttChartColumnNames.Start,Value:7}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Gantt chart holidays

    The third task now starts exactly 7 days later.

    Setting Task Lengths

    Task lengths default to 5 working days, but may be set to another number of working days using the "Length" property:

    {
    var myGanttDocument= new VS.GanttDocument();
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"},{Name:VS.GanttChartColumnNames.Length,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"User Testing"},{Name:VS.GanttChartColumnNames.Start,Value:"2018-08-11"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Implementation"},{Name:VS.GanttChartColumnNames.Start,Value:7}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Setting task length

    The first task now has a length of 10 working days. Note, that by default working days are not calendar days as we explained above.

    The end date is automatically calculated from the start date plus the length. You can also set the end date explicitly:

    {Name:VS.GanttChartColumnNames.End, "Value":"2018-08-3"}
    

    Setting an end date is another way of setting length. The end date cannot be earlier than the start date. If you set a length and an end date, the length will be determined by the end date.

    Grouping Tasks

    It is common to subdivide a larger task into a set of smaller sub tasks. The larger task is described as the "parent" task of the child (or sub) tasks. You can do this in VisualScript by assigning a parent to a task. The ID's of tasks used by the "parent" are the index of the task in the array by default.

    {
    var myGanttDocument=new VS.GanttDocument();
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"},{Name:VS.GanttChartColumnNames.Length,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Research requirements"},{Name:VS.GanttChartColumnNames.Parent,Value:1},{Name:VS.GanttChartColumnNames.Length,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Create a prototype"},{Name:VS.GanttChartColumnNames.Parent,Value:1},{Name:VS.GanttChartColumnNames.Start,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"User Testing"},{Name:VS.GanttChartColumnNames.Start,Value:"2018-08-11"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Implementation"},{Name:VS.GanttChartColumnNames.Start,Value:7}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Grouping tasks

    Note that the first subtask (Research requirements) is set to take 10 days and the second task (Create a prototype) is set to start 10 days after the first. This is a common pattern where a task starts after another completes. Another way to implement this is by setting up a dependency.

    Creating Dependencies

    You make the start of a task dependent on the end of another using the "Master" column: {"Name":"Master","Value":2}.

    Assigning the "Master" of a task means that it will begin when the "Master" task ends. In the example below

    {
    var myGanttDocument=new VS.GanttDocument();
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"},{Name:VS.GanttChartColumnNames.Length,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Research requirements"},{Name:VS.GanttChartColumnNames.Parent,Value:1},{Name:VS.GanttChartColumnNames.Length,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Create a prototype"},{Name:VS.GanttChartColumnNames.Parent,Value:1},{Name:VS.GanttChartColumnNames.Master,Value:2}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"User Testing"},{Name:VS.GanttChartColumnNames.Start,Value:"2018-08-11"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Implementation"},{Name:VS.GanttChartColumnNames.Start,Value:7}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Gantt chart dependencies

    Adding Custom Columns

    Assigning values to any of the other columns will make them appear in the table:

    For example adding values for "Person" and "Department" adds these columns:

    {
    var myGanttDocument= new VS.GanttDocument();
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"},{Name:VS.GanttChartColumnNames.Length,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Research requirements"},{Name:VS.GanttChartColumnNames.Parent,Value:1},{Name:VS.GanttChartColumnNames.Length,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Create a prototype"},{Name:VS.GanttChartColumnNames.Parent,Value:1},{Name:VS.GanttChartColumnNames.Master,Value:2}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"User Testing"},{Name:VS.GanttChartColumnNames.Start,Value:"2018-08-11"},{Name:VS.GanttChartColumnNames.Person,Value:"Vera Brooks"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Implementation"},{Name:VS.GanttChartColumnNames.Start,Value:7},{Name:VS.GanttChartColumnNames.Department,Value:"DevTeam"}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    

    Add custom columns

    Setting Column Properties

    You can change the Title and the width of the Person, Department, Custom and Cost columns using the SetColumnSettings() method of the GanttDocument object.

    {
    var myGanttDocument= new VS.GanttDocument();
    myGanttDocument.SetColumnSettings(VS.GanttChartColumnNames.Department,"Customer",75);
    myGanttDocument.SetColumnSettings(VS.GanttChartColumnNames.Person,"Manager",150);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Planning"},{Name:VS.GanttChartColumnNames.Length,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Research requirements"},{Name:VS.GanttChartColumnNames.Parent,Value:1},{Name:VS.GanttChartColumnNames.Length,Value:10}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Create a prototype"},{Name:VS.GanttChartColumnNames.Parent,Value:1},{Name:VS.GanttChartColumnNames.Master,Value:2}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"User Testing"},{Name:VS.GanttChartColumnNames.Start,Value:"2018-08-11"},{Name:VS.GanttChartColumnNames.Person,Value:"Vera Brooks"}]);
    myGanttDocument.AddTask([{Name:VS.GanttChartColumnNames.Task,Value:"Implementation"},{Name:VS.GanttChartColumnNames.Start,Value:7},{Name:VS.GanttChartColumnNames.Department,Value:"DevTeam"}]);
    var vsJSON = myGanttDocument.toJSON();
    vsCompleteCallback(vsJSON);
    }
    
    Customized columns

    Note the new names for "Assigned To" and "Dept" and the new widths of these columns.

16/18 Page