Customizing Reports with Scripts

Dataplane 2.0 introduces the concept of Customizer Scripts. Customizer scripts are user-defined scripts that allow Dataplane reports to be modified in new and exciting ways.

Overview

Customizer Scripts allow users to customize the output of Dataplane's charts and tables. A customizer script can be used to adjust the colors of charts, to change the axis range and titles, to sort tables, to adjust the display of statistics, and more. Future versions of Dataplane will permit users to perform even more detailed customization of the report generation process. Customizer scripts are entirely optional, but they provide an additional level of control to power users.

To demonstrate a simple example of a customizer script: assume that a user creates a report showing the number of issues associated with various development projects, using a standard Current Issue Values report. The report is segmented by both issue type and priority. By default, Dataplane assigns colors to each segment in the chart automatically. Before doing any customization, the default chart looks like this:

The resulting chart is colorful, but to make trends easier to see, we want to change the colors so that Bugs and Feature Requests are easily distinguishable. The user flips back to the Configure tab on the report page, clicks the More Options link in the top right corner to enable the Customizer Script field, and then enters the following Customizer Script:

This script tells Dataplane to adjust the color of all segmentations for Bugs (with any priority) to be a shade of goldenrod (yellow) and all Feature Requests (with any priority) to be colored a shade of dark blue. After entering the customizer script and re-running the report, the output now looks like this:

This is much easier to understand. Now, suppose that P1 issues are very important, so we also want to visually distinguish P1 feature requests and bugs from the rest of the issues. The user can also apply this new coloring rule by making a slight change to the customizer script:

After applying this last change, we see that bugs and features are colored separately, but P1 issues of either type are rendered in a shade of red. All of this, and more, can be done with customizer scripts:

Customizer Script Basics

Customizer scripts are attached to individual Dataplane reports, and scripts can be modified when creating a new report or when editing an existing saved report. From either type of report, you access the Customizer Script by clicking the More Options link in the top right corner of the report configuration page:

After clicking More Options, the Customizer Script textbox is shown at the bottom of the report configuration page:

From this point, the user can enter a customizer script in order to adjust the appearance of the chart. (The Dataplane customizer script language is based on Groovy, which is a dynamic language for the Java Virtual Machine. However, you do not need to know Groovy to use customizer scripts, and customizer scripts need not be complex.)

A Dataplane customizer script generally looks like this:

customizeCOMPONENT {
    first customization command
    second customization command
    ...
}

Depending on what you are customizing, the first line could be "customizeChart" (to customize the series, the axes and more in the chart), "customizeTable" (to customize the results table), or any of the other options described below. This is called a customizer block.

If you wish to modify more than one aspect of the report output (such as performing adjustments to both the chart and the table) you can include multiple customizer blocks of different types in the script, or even multiple blocks of the same type.

If you wish to add comments inside your script so that you (or others) can better understand the content, you can write "//" at the beginning of a line, followed by as much text as you want on that same line. To write a comment that is longer than one line, you may also surround your comment with a pair comment markers ("/*" and "*/").

// This is a single line comment.

// This is another comment which has a "//" at the beginning of the line.
// Each comment in this form must start with a "//" on the same line.

/* This is a multi-line comment describing the script, which only has
   comment start and end markers at the very beginning and end of the comment.
 */

Using the Enhanced Script Editor

Through a new Dataplane Labs feature, users have the option of using an enhanced text editor to edit customizer scripts. The enhanced text editor is available to all users who are using a browser other than Internet Explorer.

The enhanced script editor includes the following features:

• syntax highlighting of customizer blocks, making it easier to understand your script and to see mistakes,
• line numbers, so that you can easily navigate your script,
• code folding, so that you can easily show and hide blocks within "{ }" braces, and
• a dynamically-resizable text area.

For example, depending on the quantity of customizations being performed, Customizer Scripts can sometimes get lengthy. If you ever make an error in a customizer script, the error will be reported based on the line number of the script that caused the error, so having a built-in line number reference can be very useful.

To use the enhanced script editor, simply enable the feature in Dataplane Labs. Users who are using Internet Explorer will always be shown the regular script editor, regardless of the configuration in Dataplane Labs.

Customizing Charts

The charts produced by Dataplane can be customized using "customizeChart" blocks in the customizer script. The customizeChart blocks can customize the series, axes, and more. A customizeChart block looks like this:

customizeChart {
    // one or more chart-customization commands go here
}

Customizing Series

A series in Dataplane corresponds to an individual line or bar segment in the output chart. To allow users to select a specific series, Dataplane first allows users to name the individual segments in the series, or to use wildcards to match each segment. After a series has been selected, the user can specify one or more customizations to be performed on that series.

Selecting a Series Directly

In general, the segments of a series consist of all of the Segment By options selected by the user in the report configuration page.

In the simplest case, in which a report is segmented by one specific field (such as Priority), series can be selected by specifying the priority name directly.

For example, if possible priorities for an issue were P1 and P2, the following customizer script would adjust the color of P1 to be red and the color of P2 to be green:

customizeChart {
    series "P1" color "red"
    series "P2" color "green"
}

As a more complicated example, suppose that the user runs a report which uses Segment By selections of both Priority and Issue Type. If the valid priorities were P1 and P2, and if the valid issue types were Bug and Feature Request, the possible set of generated series would be as shown in the table below. The combined series name ("Series Name" in the table below) is also what Dataplane displays on the report legend:

In order to select a specific series in this case, the customizer script should include the word series followed by a list of quoted segment names, each separated by commas and all enclosed in parenthesis

For example, the following customizer script would set all P1 Feature Requests to yellow, and all P2 Bugs to black.

customizeChart {
    series("P1", "Feature Request") color "yellow"
    series("P2", "Bug") color "black"
}

Selecting a Series using Wildcards with "ANY"

If you want to match all components in a specific series, use the word ANY (without quote marks) in place of an explicit segment in order to match any value.

Using the same scenario as in the previous section, in order to color all P1 series brown, regardless of whether they are Bugs or Feature Requests, use the following:

customizeChart {
    series("P1", ANY) color "brown"
}

Selecting a Series using Regular Expressions

In addition to matching series based on explicit names, advanced users can also use Java-style "regular expressions" in order to match more than one series. A regular expression is a special series of characters that allows the use of wildcards to match more than one type of series name. Oracle, the makers of Java, provide a standard reference for Java-style regular expressions.

To match a series using a regular expression, simply write seriesRegex instead of the plain series used in the examples above. For example, if a report were segmented only by Priority, the following would specify that priorities P1, P2 and P3 should be pink and P4 and P4 should be orange. In this example, the square brackets denote that any single letter or number inside the brackets will be matched, so "P[123]" will match "P1", "P2" or "P3".

customizeChart {
    seriesRegex "P[123]" color "pink"
    seriesRegex "P[45]" color "orange"
}

As another example, assume a chart were segmented by Issue Type, and possible issue types were "Bug", "Feature", and "Documentation Task", "Technical Task". If we want to select all of the Issue Types that end in the word "Task", we can use the ".*" sequence of characters to match any arbitrary sequence of characters:

customizeChart {
    seriesRegex ".*Task" color "blue"
    series "Bug" color "yellow"
    series "Feature Request" color "white"
}

The above example would apply the blue color to all technical tasks, while bugs would be yellow and feature requests would be white. Both series and seriesRegex can be mixed within the same customizeChart block. If multiple commands can be matched to the same series, Dataplane will apply the customization from the very last match.

Customizing the Series Name

Dataplane displays names for series in the report legend and in chart tooltips. The series name is automatically created by combining all of the series segments together with a "/" character. For example, a report segmented by Priority and Issue Type might have a series name such as "P1 / Bug".

If you wish to change the name of a series in the legend, use the series or seriesRegex commands from above to select the series, and then write the word name, followed by the new name of the series in quotes. For example, to rename P1 / Feature Requests to "Urgent Feature Requests", and "P5 / Bug" to "Throwaway Bugs", use the following:

customizeChart {
    series ("P1", "Feature Request") name "Urgent Feature Requests"
    series ("P5", "Bug") name "Throwaway Bugs"
}

Customizing the Series Color

Many of the above examples have shown how to customize the color of particular series segments. Dataplane allows the user to customize series segments using both color names and HTML color codes. In addition, Dataplane allows the user to suggest that multiple series segments be given similar colors.

The color command tells Dataplane to assign a single color to the selected series. After writing the word color, you can include either an HTML color code or a color name.

Dataplane supports all named colors in the lists of basic W3C colors and extended W3C colors. To use a color name from either of these lists, simply write the color name in quote marks after the color command. For example:

customizeChart {
    series "P1" color "cornflowerblue"
    series "P2" color "olive"
    series "P3" color "sienna"
    series "P4" color "yellowgreen"
    series "P5" color "palegreen"
}

If the specific color you want is not available in the color lists above, Dataplane also supports the use of explicit HTML color codes. An HTML color code is the symbol "#", followed by six hexadecimal digits that describe the red, green and blue components of the color. You can use any third-party tool, such as the HSL Picker website, to create a custom color code.

Once you know the HTML color code, simply write it inside a pair of double quotes, taking care to include the "#" symbol as well.

For example:

customizeChart {
    series "P1" color "#ed127c" // a reddish pink
    series "P2" color "#b6ed12" // a yellowish green
    series "P3" color "#5f4007" // dark brown
}

In addition, Dataplane allows you to automatically apply a range of similar colors to a set of related series. We can use the ANY wildcard from above to match multiple series, and we will then use the colorLike command (instead of color) to tell Dataplane to automatically assign random colors to the series that are similar to the named color.

Going back to our original example, in which we have a chart that is segmented by priority and issue type, suppose that we want all Bugs to be colored in blue and all Feature Requests in yellow:

customizeChart {
    series (ANY, "Bug") colorLike "blue"
    series (ANY, "Feature Request") colorLike "yellow"
}

Customizing Axes

Dataplane allows the user to customize both the domain (X) axis and range (Y) axis of reports.

The domain (X) axis can be customized with a custom title.

The range (Y) axis can be customized with a custom title, to set explicit minimum and maximum values, and to change the scale.

Customizing the Domain (X) Axis

The name of the domain axis can be customized like this:

customizeChart {
    axis "domain" title "Dates in Project Timeline"
}

Customizing the Range (Y) Axis

The range axis can have its title customized, and in addition, the range and scale of the axis can be configured. For example:

customizeChart {
    axis "range" title "Issues Handled"

    axis "range" min 100                  // set the minimum of the Y axis to 100
    axis "range" max 500                  // set the maximum of the Y axis to 500

    axis "range" range(100, 500)          // set both min and max at the same time

    axis "range" scale "log"              // use a logarithmic scale instead of linear
}

Customizing Data Tables

Dataplane now allows users to specify a custom default sort order within data tables. The sort order is automatically applied in the client report output, and it also dictates the standard sort used in PDF, Excel and CSV exports.

To customize the sort of the table, use the sort command followed by the name of the column to be sorted in quotation marks. You can specify multiple sorts to force secondary sorting after the first specified sort.

For example, to sort a report first by descending priority and then by ascending status, the following customizer script can be used:

customizeTable {
    sort "Priority" order "desc" // sorts by descending Priority
    sort "Status"                // sorts by the Status column in ascending order
}

Sorts can also be listed all on the same line for brevity. The following script is treated identically to the previous example:

customizeTable {
    sort "Priority" order "desc" sort "Status"
}

Please note that the column named in the sort command must already exist on the Data tab of the report output. For example, a report table that contains only the columns "Month" and "# of Issues" cannot be sorted by priority. To sort such a report by priority, go back to the report configuration page, add a Priority segmentation to the Segment By field, and then add a customizer script specifying the appropriate column.

Customizing Statistics

At the top of most reports, Dataplane displays a set of statistics based on the underlying data, such as shown in the following report:

Each of the individual statistics sections can be shown or hidden, renamed, and can have the statistic itself displayed in a custom format. The following statistics sections can be manipulated through the customizer script:

All statistics are customized in a customizeRender block, using the stat command followed by a stat name from the table above.

For example, to hide the "Total Issues" statistic from a report, use the following customizer script:

customizeRender {
    stat "total" show false
}

In addition to hiding the statistic, you can also change its name with the title command. For example:

customizeRender {
    stat "min" title "Smallest # of Issues"
}

You can also ask Dataplane to display the actual numeric statistic in a different format using the format command. The format command uses a Java-based format string to define how to display the statistic. Although many more complicated transformations can be performed, in general, the characters "%f" will be replaced with the value of the statistic.

For example, if a Sum Numeric Field report is used to sum a field that contains a quantity of US Dollars, you can use the format command to add a "USD" prefix to the statistic as follows:

customizeRender {
    stat "total" format "USD %f"
}

Certain characters in the format string, such as the $ sign, need to be escaped with a "\" character. For example, to display all statistics with dollar signs in front:

customizeRender {
    stat "total" format "\$%f"
    stat "min" format "\$%f"
    stat "max" format "\$%f"
    stat "ave" format "\$%f"
}

If we wanted to customize the statistic further so that numbers are displayed with the "," character to separate groups of thousands, we can use the following:

customizeRender {
    stat "total" format "\$%,.02f"
    stat "min" format "\$%,.02f"
    stat "max" format "\$%,.02f"
    stat "ave" format "\$%,.02f"
}

The display format string supports many other options for advanced users; see the Java String format documentation for more details.