Using xmCHART

Written by Joe Rovang

Introduction

xmCHART is a FileMaker plug-in that uses input text (containing data and options you specify) to generate an output graphic, most commonly a chart. Usually this is done with the Draw Chart[] script step, which works like Set Field (set a field equal to some result — in this case, set a container field equal to the graphic produced when xmCHART processes your input text).

xmCHART also comes with the function xmCH_DrawChart for generating graphics through the calculation engine (such as in a calculated container field).

Chart Structure

The input text you pass to xmCHART uses functions (not to be confused with FileMaker functions) which describe the graphic you're asking for. A typical chart has the following structure:

  1. OpenDrawing() (to specify the image size)
  2. ChartData (to populate the chart)
  3. a function for a particular chart type
  4. assorted appearance functions
  5. CloseDrawing() (optional)

For more complex drawings, use OpenChart() to position a chart precisely within the drawing, or to place multiple charts in the same drawing (including overlaying charts over each other), see examples here. Use OpenView() or OpenGroup() to establish drawing groups if desired, see examples here.

xmCHART supports single-line // and multi-line /* */ comments.

Chart Data

  • A chart requires data, usually consisting of multiple values, often arranged in multiple series/sections.
  • Use ChartData() to include data in your xmCHART code (use whitespace such as spaces or returns to separate values, and semicolons to separate series/sections), or use ChartDataRead() to read data directly from a text file (use tabs and returns, or specify custom separators).
  • Don't use commas as thousands separators in input numbers.
  • Dates can be read as M/D/Y, D/M/Y, or Y/M/D depending on DateTimeOptions(). Dashes or slashes may be used in dates. Timestamps must use & to join dates and times.
  • Use NULL to indicate a missing value (beware the potential for FileMaker's List() function to condense gaps).
  • A null value can be forced if data falls outside an expected range using ChartDataLowerLimits() and/or ChartDataUpperLimits().
  • Use a legend to assign names to data series.
Data Order

Use ChartDataOptions() to change how data is read (see examples below). XXYY is default.

If you have a single 1-dimensional series with one data point (such as a radial gauge):

  • Use XXYY, XYXY, or XYXY2 if your data looks like:
    value

If you have a single 1-dimensional series with multiple data points (such as a single-color bar chart):

  • Use XXYY or XYXY2 if your data looks like:
    value value /* Values space-separated. */
  • Use XYXY if your data looks like:
    value ; value /* Values semicolon-separated. */

If you have a single 2-dimensional series with one data point (such as a single-point 2D scatter chart):

  • Use XXYY or XYXY2 if your data looks like:
    x ; y /* Values semicolon-separated. */
  • Use XYXY if your data looks like:
    x y /* Values space-separated. */

If you have a single 2-dimensional series with multiple data points (such as a single-color 2D line chart):

  • Use XXYY or XYXY2 if your data looks like:
    x x ; /* All X values. */
    y y ; /* All Y values. */
  • Use XYXY if your data looks like:
    x y ; /* First data point. */
    x y ; /* Second data point. */

If you have multiple 1-dimensional series with one data point each (such as a pie chart):

  • Use XXYY or XYXY2 if your data looks like:
    value ; value /* Series semicolon-separated. */
  • Use XYXY if your data looks like:
    value value /* Series space-separated. */

If you have multiple 1-dimensional series with multiple data points each (such as a multi-colored bar chart with multiple categories):

  • Use XXYY or XYXY2 if your data looks like:
    value value ; /* All values for series 1. */
    value value ; /* All values for series 2. */
  • Use XYXY if your data looks like:
    value value ; /* First values for all series. */
    value value ; /* Second values for all series. */

If you have multiple 2-dimensional series with one data point each (such as a 2D scatter chart with assorted point colors):

  • Use XXYY if your data looks like:
    x ; y ; /* Coordinates for series 1 (semicolon-separated). */
    x ; y ; /* Coordinates for series 2 (semicolon-separated). */
  • Use XYXY if your data looks like:
    x y x y /* Coordinates for all series (space-separated). */
  • Use XYXY2 if your data looks like:
    x y ; /* Coordinates for series 1 (space-separated). */
    x y ; /* Coordinates for series 2 (space-separated). */

If you have multiple 2-dimensional series with multiple data points each (such as a 2D line chart with multiple lines):

  • Use XXYY if your data looks like:
    x x ; /* All X values for series 1. */
    y y ; /* All Y values for series 1. */
    x x ; /* All X values for series 2. */
    y y ; /* All Y values for series 2. */
  • Use XYXY if your data looks like:
    x y x y ; /* First data point for all series. */
    x y x y ; /* Second data point for all series. */
  • Use XYXY2 if your data looks like:
    x y x y ; /* All data points for series 1. */
    x y x y ; /* All data points for series 2. */

Chart Types

Several chart options vary by chart type. Notably, chart types may differ in the number of values used to describe a single data point, the number of data points allowed in a series, and the total number of series allowed (see below).

Chart type Values per data point Points
per series		 Max
series		 Appearance
constants		 Other options
AreaChart()
(like a 1D line chart but drawn with a filled area)
  1. point's Y coordinate
 ∞10000shadow, label, symbol, horizontal, stacked, proportional AreaChartOptions(), filled areas
AreaChart2D()
(like a 2D line chart but drawn with a filled area)
  1. point's X coordinate
  2. point's Y coordinate
 ∞10000shadow, label, symbol AreaChartOptions(), filled areas
BarChart()
(standard bar chart)
  1. bar's height
 ∞10000shadow, label, symbol, horizontal, stacked, proportional BarChartOptions(), BarStyle(), filled areas
BarChart2D()
(each bar has an X coordinate)
  1. bar's X position
  2. bar's height
 ∞10000shadow, label, symbol, horizontal, stacked, proportional BarChartOptions(), BarStyle(), filled areas
BoxPlot()
(box with some dots inside and some outside)
  1. point's Y coordinate
 ∞10000shadow, symbol, horizontal BoxPlotOptions(), filled areas
BubbleChart()
(like a 1D scatter chart, but with varying point sizes)
  1. circle's Y coordinate
  2. circle's diameter
 ∞10000shadow, label, symbol, horizontal BubbleChartOptions(), filled areas
BubbleChart2D()
(like a 2D scatter chart, but with varying point sizes)
  1. circle's X coordinate
  2. circle's Y coordinate
  3. circle's diameter
 ∞10000shadow, label, symbol BubbleChartOptions(), filled areas
CandlestickChart()
(stock prices as boxes with high/low lines)
  1. box's high mark
  2. box's low mark
  3. box's close value
  4. box's open value
 ∞10000shadow, horizontal CandlestickChartOptions(), filled areas
CandlestickChart2D()
(stock prices, but each box has an X coordinate)
  1. box's X position
  2. box's high mark
  3. box's low mark
  4. box's close value
  5. box's open value
 ∞10000shadow CandlestickChartOptions(), filled areas
CircularBarChart()
(circular progress bars)
  1. bar's length
 110000shadow, label BarStyle(), filled areas
ContourPlot()
(topographic map)
  1. value (points in series arranged as grid)
 ∞1shadow, label, symbol ContourPlotOptions(), lines, filled areas (border only)
DensityPlot()
(grid of colored blobs)
  1. value (points in series arranged as grid)
 ∞1shadow, label, symbol DensityPlotOptions(), FillColorScale()
GanttChart()
(range-based timeline)
  1. range's start value
  2. range's end value
 ∞10000shadow, label, symbol, horizontal BarStyle(), filled areas
HeatMap()
(grid of colored tiles)
  1. value (points in series arranged as grid)
 ∞1shadow, label HeatMapOptions(), FillColorScale(), filled areas (usually border only)
HighLowChart()
(like a candlestick chart without the boxes)
  1. range's high mark
  2. range's low mark
  3. range's close value (optional)
  4. range's open value (optional)
 ∞10000shadow, label, symbol, horizontal HighLowChartOptions(), lines
HighLowChart2D()
(like a 2D candlestick chart without the boxes)
  1. range's X position
  2. range's high mark
  3. range's low mark
  4. range's close value (optional)
  5. range's open value (optional)
 ∞10000shadow, label, symbol, horizontal HighLowChartOptions(), lines
Histogram()
(a bar chart that groups values into several buckets)
  1. value to count
 ∞10000shadow, label, symbol, horizontal, stacked HistogramOptions(), HistogramRange(), filled areas
LinearGauge()
(points on a number line)
  1. marker's value
 110000shadow, label, horizontal symbols
LinearMeter()
(progress bar)
  1. bar's start value
  2. bar's end value
 110000shadow, symbol, horizontal filled areas
LineChart()
(like a 1D scatter chart with connecting lines)
  1. point's Y coordinate
 ∞10000shadow, label, symbol, horizontal lines
LineChart2D()
(like a 2D scatter chart with connecting lines)
  1. point's X coordinate
  2. point's Y coordinate
 ∞10000shadow, label, symbol lines
PieChart()
(basic pie chart)
  1. slice amount
 ∞1shadow, label, oval pie charts, filled areas
PolarChart()
(like a 2D area chart displayed with a polar grid)
  1. point's cartesian X coordinate
  2. point's cartesian Y coordinate
 ∞10000shadow, label, symbol, oval PolarChartOptions(), filled areas, ArrowStyle()
RadarChart()
(like a 1D area chart but on a polar grid)
  1. point's Y coordinate (radius)
 ∞10000shadow, label, symbol, oval RadarChartOptions(), filled areas, ArrowStyle()
RadialGauge()
(like a speedometer)
  1. needle's angle
 110000shadow filled areas
ScatterChart()
(like a bar chart, but with points instead of bars)
  1. point's Y coordinate
 ∞10000shadow, label, horizontal symbols
ScatterChart2D()
(points drawn at X/Y coordinates)
  1. point's X coordinate
  2. point's Y coordinate
 ∞10000shadow, label symbols
TreeMap()
(various numbers sorted into rectangles of descending size)
  1. rectangle's size
 ∞10000shadow, label TreeMapOptions(), FillColorScale(), filled areas (usually border only)
VectorPlot()
(like a 1D scatter chart, but with arrows of some length and direction)
  1. vector's Y coordinate
  2. vector's line length
  3. vector's direction
 ∞10000shadow, label, symbol, horizontal VectorPlotOptions(), lines
VectorPlot2D()
(like a 2D scatter chart, but with arrows of some length and direction)
  1. vector's X coordinate
  2. vector's Y coordinate
  3. vector's line length
  4. vector's direction
 ∞10000shadow, label, symbol VectorPlotOptions(), lines
VennDiagram()
(2 or 3 intersecting circles with counts by category)
  1. value to compare across series
 ∞3label, horizontal filled areas
ViolinPlot()
(used to represent statistical distributions)
  1. point's Y coordinate
 ∞10000shadow, horizontal ViolinPlotOptions(), filled areas

Chart Appearance

Colors and Patterns
Filled Areas
Lines
Symbols
  • Series in charts with the symbol option enabled (or which are inherently symbol-based) can have their points styled with SymbolStyle(). A symbol color scheme can be defined using SymbolColorScheme().
  • See a list of symbol types here.
Shadows
  • Series in charts with the shadow option enabled can have their shadows configured with ShadowStyle().
  • Read here about shadow options which can be defined in ShadowStyle and other functions which include a shadowEffect parameter.
Axes
Grid
Background
Title
Legend
Value Labels
Pie Charts
Additional Lines
Formatting Numbers, Dates, Times, and Text

Other Graphical Objects

xmCHART drawings may also incorporate barcodes, vector objects, text tags, and data tables.

Output

The drawing can be exported as an image file using various save functions (or using FileMaker's Export Field Contents command, if the drawing has been inserted into a container field).


Scroll to Top