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
Set this to "false" to hide the legend at the bottom of the chart.
explodeSeries
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.
strokeWidth
The width of the stroke used to outline the parts of the chart.
backgroundColor
The background color of the chart. Pass in three numeric values, e.g. 64,128,255
plotBackgroundColor
The background color of the plot area (excluding the headers and legends). Pass in three numeric values, e.g. 64,128,255
noDataMessage
The message to display when there is no data to display in the chart
label
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.
outline
1 or 0 to show/hide a single border around the chart, but within the legend.
outlines
1 or 0 to enable/disable outlines around individual chart elements (for pie charts only)
hideLabels
Whether to hide labels on the chart (for pie charts only)
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
)
)
]

Installation

Requirements

FileMaker version 7 or higher.

Java Virtual Machine (JVM) version 1.4.2 or later. If you are running a JVM earlier than 1.4.2, you should upgrade. Download a JVM from http://www.java.com/en/download/. If you are not sure what version of Java you have installed, you can do 'java -version' on the command line in Windows or OS X.

Windows, or Mac OS X version 10.4 or higher.

Note to intel Mac users: running this plugin under Rosetta is not supported. Upgrade to FileMaker 8.5 to run our plugin in native Intel mode.

Install Steps for FileMaker Pro

Drag the plugin from the MAC or WIN folder into your FileMaker extensions, and restart FileMaker. You will need to enter your license key before you can use it. After FileMaker starts up with the plugin installed, open FileMaker preferences, click on the Plug-ins tab, select the plugin from the list, and click the Configure button. Enter your license key and company name in this dialog. You will only need to do this once on a given machine. Alternately, you can use the registration function to register the plugin during a startup script.

This will also enable the plugin for use with Instant Web Publishing from the FileMaker Pro client software.

If the plugin does not load correctly, double-check that you meet the system requirements.

Install steps for FileMaker Web Publishing Engine / Instant Web Publishing

You do not need to do this step unless you plan on using the plugin with Instant Web Publishing or Custom Web Publishing with FileMaker Server Advanced. You will need an Enterprise License to use this feature.

For installing into the Web Publishing Engine with FileMaker 9 Server or FileMaker Server Advanced, drag the plugin from the MAC or WIN folder into the FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins folder. If there is no 'Plugins' folder inside the 'wpc' folder, then create it manually. Restart FileMaker Web Publishing, and now the plugins should be ready to go.

Note that you must use the registration function to register the plugin, since there is no preferences dialog in the FileMaker Web Publishing Engine to enter the license key and company name.

Note that due to a bug which we and other plugin vendors have reported to FileMaker, web plugins do not work in FileMaker Web Publishing Engine 8.0v4 on Mac OS X. You will need to use a later version, like 9, or an earlier version, like 8.0v3. The Windows FileMaker Server 8.0v4 does not have this bug, and will work correctly.

The easiest way to test whether the plugin is working is to have a calculation which calls the version function of the plugin, and display that on an IWP layout. If it shows "?", then the plugin is not working. If it shows a number, then the plugin has been installed successfully.

Install steps for FileMaker Server 9

You do not need to do this step unless you plan on using the plugin with scheduled script triggering, a new feature in FileMaker Server 9. You will need an Enterprise License to use this feature.

  1. Drag the plugin from the MAC or WIN folder into the FileMaker Server/Extensions/Plugins folder.
  2. Verify that the permissions on the plugin give the fmserver / fmsadmin user all access
  3. Restart FileMaker Server. In the Server Admin application, go to Configuration -> Database Server->Server Plug-ins.
  4. Check the box that says 'Enable FileMaker Server to use plug-ins', and then check the 'enabled' box for this plugin. You should now be able to write schedules that trigger scripts which use the plugin.

Note that you must use the registration function to register the plugin, since there is no preferences dialog in FileMaker Server to enter the license key and company name.

Feedback

We love to hear your suggestions for improving our products! If you are experiencing problems with this plugin, or have a feature request, or are happy with it, we'd appreciate hearing about it. Send us a message on our website, or email us!

Function Summary

Function Detail

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

Create a bar chart. A bar chart looks like this:

bar chart

Parameters:
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.
Returns: 1 on success, or "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.

Parameters:
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
Returns: 1 on success, or "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.

Parameters:
category - a category which was set in a previous call to barChartSetDataPoint.
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.
Returns: 1 on success, or "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.

Parameters:
width - the width of the resulting image
height - the height of the resulting image
additionalParams - additional parameters
Returns: an image containing the chart of the supplied dimensions.

chartLastError

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

chartLicenseInfo

Returns information about the license used.

chartRegister ( key ; registeredTo )

Registers the Plugin.

Parameters:
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.
Returns: 1 on success, or "ERROR" on failure.

chartVersion

Returns the version of the plugin.

Returns: an integer version number.

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

Create a line chart.

Parameters:
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
Returns: 1 on success, or "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 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.

Parameters:
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
Returns: 1 on success, or "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.

Parameters:
category - a category which was set in a previous call to lineChartSetDataPoint.
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.
Returns: 1 on success, or "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.

Parameters:
width - the width of the resulting image
height - the height of the resulting image
additionalParams - additional parameters
Returns: an image containing the chart of the supplied dimensions.

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:

pie chart

Parameters:
name - The optional name of the chart.
use3d - whether to use a three-dimensional effect on the chart.
Returns: 1 on success, or "ERROR" if there was a problem (use ChartLastError for more detailed information about the nature of the error).

pieChartSetDataPoint ( name ; value )

Adds a value to a pie chart created with the pieChartCreate function. Calling this twice with the same category name will overwrite the previously set value.

Parameters:
name - The category name whose value is being set
value - The numeric value for the category.
Returns: 1 on success, or "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.

Parameters:
category - a category which was set in a previous call to pieChartSetDataPoint.
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.
Returns: 1 on success, or "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.

Parameters:
additionalParams - additional parameters which customize how the chart is generated
Returns: the chart image

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:

Parameters:
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.

Parameters:
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
Returns: 1 on success, or "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 for a specific series and date.

Parameters:
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
Returns: 1 on success, or "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.

Parameters:
seriesName - a seriesName which was set in a previous call to timeSeriesChartSetDataPoint.
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.
Returns: 1 on success, or "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.

Parameters:
width - the width of the resulting image
height - the height of the resulting image
additionalParams - additional parameters
Returns: an image containing the chart of the supplied dimensions.