360Works Charts/Documentation
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
- barChartCreate ( name ; categoryAxisLabel ; valueAxisLabel { ; isVertical ; use3d } ) — Create a bar chart.
- barChartSetDataPoint ( group, category ; value ) — Set a data point in a bar chart.
- barChartSetSeriesColor ( category ; red ; green ; blue ; alpha ) — Set the color that a particular category is displayed in.
- barChartShowGraphic ( width ; height { ; additionalParams... } ) — Generates the bar chart containing all previously set data points.
- 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.
- 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.
- lineChartSetSeriesColor ( category ; red ; green ; blue ; alpha ) — Set the color that a particular category is displayed in.
- lineChartShowGraphic ( width ; height { ; additionalParams... } ) — Generates the line chart containing all previously set data points.
- pieChartCreate ( name { ; 3d } ) — Creates a new pie chart with the given name.
- pieChartSetDataPoint ( category ; value ) — Adds a value or a return separated list of values to a pie chart created with the
pieChartCreate
function. - pieChartSetSeriesColor ( category ; red ; green ; blue ; alpha ) — Set the color that a particular category is displayed in.
- pieChartShowGraphic ( width ; height { ; additionalParams... } ) — Returns the container image for the currently configured chart.
- timeSeriesChartAddRegression ( seriesName { ; properties } ) — Adds a regression to the time series.
- 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.
- timeSeriesChartSetSeriesColor ( seriesName ; red ; green ; blue ; alpha ) — Set the color that a particular time series is displayed in.
- timeSeriesChartShowGraphic ( width ; height { ; additionalParams... } ) — Generates the time series chart containing all previously set data points.
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"/>
name
- the optional name of the chart
categoryAxisLabel
- the optional label for the category axis of the chart
valueAxisLabel
- the optional label for the value axis of the chart
isVertical
- Whether to orient the chart horizontally (0) or vertically (1)
use3d
- whether to apply a three-dimensional effect to the chart.
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
group
- unique group name identifier.
category
- category name identifier. Typically, the same categories are repeated for each group.
value
- the numeric value for the group/category combination
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
category
- a category which was set in a previous call to {@link #barChartSetDataPoint(String, String, double)}.
red
- a number between 0-255
green
- a number between 0-255
blue
- a number between 0-255
alpha
- a number between 0-255 indicating the transparency of the color. 0 is completely transparent.
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
width
- the width of the resulting image
height
- the height of the resulting image
additionalParams
- additional parameters
width
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.
licenseKey
- a valid license key string, or the literal string "DEMO" to run in demo mode.
registeredTo
- the company name for the license key used.
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.
errorCapture
- set to true to suppress the default popups.
chartVersion
Returns the version of the plugin.
lineChartCreate ( name ; categoryAxisLabel ; valueAxisLabel { ; isVertical ; use3d } )
Create a line chart.
name
- The title of the chart
categoryAxisLabel
- The label for the category axis
valueAxisLabel
- The label for the value axis
isVertical
- Whether to orient the line chart vertically or horizontally (pass a 1 for vertical)
use3d
- whether to apply a three-dimensional effect to the chart
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
seriesName
- the name of the series (or line) that this data point will apply to.
category
- category name identifier. This appears in the category axis of the line chart.
value
- the numeric value for the group/category combination
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
category
- a category which was set in a previous call to {@link #lineChartSetDataPoint(String, String, String)}.
red
- a number between 0-255
green
- a number between 0-255
blue
- a number between 0-255
alpha
- a number between 0-255 indicating the transparency of the color. 0 is completely transparent.
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
width
width
- the width of the resulting image
height
- the height of the resulting image
additionalParams
- additional parameters
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"/>
name
- The optional name of the chart.
use3d
- whether to use a three-dimensional effect on the chart.
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
category
- category name
value
- The numeric value for the category.
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
category
- a category which was set in a previous call to {@link #pieChartSetDataPoint(String, String)}.
red
- a number between 0-255
green
- a number between 0-255
blue
- a number between 0-255
alpha
- a number between 0-255 indicating the transparency of the color. 0 is completely transparent.
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
width
height
additionalParams
- additional parameters which customize how the chart is generated
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).
seriesName
- the name of the series to add the regression to. If blank, the first series is used.
properties
- optional arguments
timeSeriesChartCreate ( name ; timeAxisLabel ; valueAxisLabel )
Creates a time series chart, for displaying a line chart which displays value information for dates.
name
- The optional name of the chart (this will be displayed in the chart header)
timeAxisLabel
- the optional label for the time axis
valueAxisLabel
- the optional label for the value axis
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
seriesName
- The series name (or line) whose value is being set.
date
- the date whose value is being set.
value
- the value of the series on the specified date
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
seriesName
- a seriesName which was set in a previous call to {@link #timeSeriesChartSetDataPoint(String, String, String)}.
red
- a number between 0-255
green
- a number between 0-255
blue
- a number between 0-255
alpha
- a number between 0-255 indicating the transparency of the color. 0 is completely transparent.
ERROR
" if there was a problem (use ChartLastError for more detailed information about the nature of the error).
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.
width
width
- the width of the resulting image
height
- the height of the resulting image
additionalParams
- additional parameters