Revision as of 18:28, 9 May 2017

360Works Charts User Guide

ChartPlugin is a Filemaker Plugin for generating various types of graphical charts. Currently supported are: pie charts, bar charts, line charts, and time series chart.

Before creating a chart, you must register the plugin using chartRegister

The charting API is split into sections corresponding to each type of chart. In general, you call a method to create a chart, then populate data points, set color options, and generate the graphic.

Example Usage

Here is an example for creating a pie chart containing five values. The let() function is used to do the setup for the chart, and then the pieChartShowGraphic is called at the end to set the actual value of the container to the chart image.

Set Variable [ $result = Let(
debug = pieChartCreate( "Quoted Hours Worked" ) and
    pieChartSetDataPoint( Name 1 ; Quoted 1 ) and
    pieChartSetDataPoint( Name 2 ; Quoted 2 ) and
    pieChartSetDataPoint( Name 3 ; Quoted 3 ) and
    pieChartSetDataPoint( Name 4 ; Quoted 4 ) and
    pieChartSetDataPoint( Name 5 ; Quoted 5 );
    pieChartShowGraphic( 360; 360 )
)

Custom parameters

The core charting API deals with the most common tasks. For additional flexibility, you can pass multiple extra parameters to the *ChartShowGraphic functions. The following is a list of all parameters:

legend</dt>

Set this to "false" to hide the legend at the bottom of the chart.</dd>

explodeSeries</dt>

causes one "slice" of a pie chart to appear offset from the center of the chart. The value can be a name or numeric index.</dd>

strokeWidth</dt>

The width of the stroke used to outline the parts of the chart.</dd>

backgroundColor</dt>

The background color of the chart. Pass in three numeric values, e.g. 64,128,255</dd>

plotBackgroundColor</dt>

The background color of the plot area (excluding the headers and legends). Pass in three numeric values, e.g. 64,128,255</dd>

noDataMessage</dt>

The message to display when there is no data to display in the chart</dd>

label</dt>

A template string which is used to generate chart labels. For pie charts, {0} is replace with the item name, {1} is the numeric amount, and {2} is the percent amount.</dd>

outline</dt>

1 or 0 to show/hide a single border around the chart, but within the legend.</dd>

outlines</dt>

1 or 0 to enable/disable outlines around individual chart elements (for pie charts only)</dd>

hideLabels</dt>

Whether to hide labels on the chart (for pie charts only)</dd>

valueAxis.min</dt>

The minimum range to use on the value axis (instead of auto-range)</dd>

valueAxis.max</dt>

The maximum range to use on the value axis (instead of auto-range)</dd>

valueAxis.showTickLabels</dt>

true/false to enable/disable the tick labels in the value axis</dd>

valueAxis.showTickMarks</dt>

true/false to enable/disable the tick marks in the value axi</dd>

To use this, simply pass any number of parameters as key/vaue pairs, for example:

Set Variable [$result = Let(
debug = pieChartCreate( "Quoted Hours Worked" ) and
    pieChartSetDataPoint( Name 1 ; Quoted 1 ) and
    pieChartSetDataPoint( Name 2 ; Quoted 2 ) and
    pieChartSetDataPoint( Name 3 ; Quoted 3 ) and
    pieChartSetDataPoint( Name 4 ; Quoted 4 ) and
    pieChartSetDataPoint( Name 5 ; Quoted 5 )
;
pieChartShowGraphic(
    360 ;
    360 ;
    "explodeSeries=" & Name 1 ; // explode the first series
    "backgroundColor=100,100,255") ; // light-blue background
    "outline=false" // don't show an outline
    "legend=false" // don't show the legend
)
)
]

360Works Plugin Setup Guides

See Plugins_101 for Error reporting, installation, registration, and more.

Function Summary

Function Detail

barChartCreate ( name ; categoryAxisLabel ; valueAxisLabel { ; isVertical ; use3d } )

Create a bar chart. A bar chart looks like this: <img src="images/barchart.png" alt="bar chart" border="1"/>

barChartSetDataPoint ( group; category ; value )

Set a data point in a bar chart. Categories are a way to break an item into smaller pieces. A group can have multiple categories.

barChartSetSeriesColor ( category ; red ; green ; blue ; alpha )

Set the color that a particular category is displayed in. You should call chartSetColor AFTER adding values to the chart.

barChartShowGraphic ( width ; height { ; additionalParams... } )

Generates the bar chart containing all previously set data points.

See the Custom Parameters section for a list of parameters which this function accepts.

chartLastError

Returns the last error which occurred, or "" if there was no error.

chartLicenseInfo

Returns information about the license used.

chartParam ( key ; value )

chartRegister ( key ; registeredTo )

Registers the Plugin.

chartSetErrorCapture ( errorCapture )

Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call chartSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.

chartVersion

Returns the version of the plugin.

lineChartCreate ( name ; categoryAxisLabel ; valueAxisLabel { ; isVertical ; use3d } )

Create a line chart.

lineChartSetDataPoint ( seriesName ; category ; value )

Set a data point or a return separated list of points in a line chart. Categories are a way to break an item into smaller pieces. A group can have multiple categories. The line will be drawn from left to right in the order items are added.

lineChartSetSeriesColor ( category ; red ; green ; blue ; alpha )

Set the color that a particular category is displayed in. You should call chartSetColor AFTER adding values to the chart.

lineChartShowGraphic ( width ; height { ; additionalParams... } )

Generates the line chart containing all previously set data points.

The additionalParams are optional parameters which can be used to customize the chart display.

See the Custom Parameters section for a list of parameters which this function accepts.

pieChartCreate ( name { ; 3d } )

Creates a new pie chart with the given name. This function must be called before adding data to the chart, modifying colors or display options, or displaying the chart graphic. A pie chart looks like this: <img src="images/piechart.png" alt="pie chart" border="1"/>

pieChartSetDataPoint ( category ; value )

Adds a value or a return separated list of values to a pie chart created with the pieChartCreate function. Calling this twice with the same category name will overwrite the previously set value.

pieChartSetSeriesColor ( category ; red ; green ; blue ; alpha )

Set the color that a particular category is displayed in. You should call chartSetColor AFTER adding values to the chart.

pieChartShowGraphic ( width ; height { ; additionalParams... } )

Returns the container image for the currently configured chart. Note that this also releases any resources used by the chart, so it can only be called once.

The additionalParams are optional parameters which can be used to customize the chart display.

See the Custom Parameters section for a list of parameters which this function accepts.

timeSeriesChartAddRegression ( seriesName { ; properties } )

Adds a regression to the time series. This should be called AFTER setting all time series data points.

The valid properties are:

• name: the name of the regression (this appears in the legend)
• color: the color of the regression line. This should be a color name (e.g. pink, red, blue, yellow, etc).

timeSeriesChartCreate ( name ; timeAxisLabel ; valueAxisLabel )

Creates a time series chart, for displaying a line chart which displays value information for dates.

timeSeriesChartSetDataPoint ( seriesName ; dateOrTime ; value )

Sets a value or a return separated list of values for a specific series and date or return separated list of dates. Note that if passing in a list of values make sure to passin a corresponding list of dates.

timeSeriesChartSetSeriesColor ( seriesName ; red ; green ; blue ; alpha )

Set the color that a particular time series is displayed in. You should call chartSetColor AFTER adding values to the chart.

timeSeriesChartShowGraphic ( width ; height { ; additionalParams... } )

Generates the time series chart containing all previously set data points.

The additionalParams are optional parameters which can be used to customize the chart display.

See the Custom Parameters section for a list of parameters which this function accepts.