insert chart

Calculation to insert a chart into a generated document, such as a Word document.

Function

insert chart([chart-name])

insert chart([chart-name], optional-settings)

insert chart([chart-name] with column-filters)

insert chart([chart-name], optional-settings with column-filters)

Arguments

Optional Named Arguments

Comments

The insert chart keywords are used in document generation macros to insert a chart image into a generated Word document.

The chart function requires a chart name to be provided. The chart name typically requires square brackets (it is an identifier). There must be exactly one chart with a name that matches the name provided.

For example:

{ MERGEFIELD insert chart([My Chart Name]) }

Column Filters

Every chart is based on a report. You may provide a list of one or more column names, along with a value, to drill down or filter the chart to only consider matching records.

To use column filters, use the with keyword inside the function, and then follow it with a comma separated list of filters. Each field includes has the column name, followed by a colon, and then the value. Use square brackets if the column name contains spaces or special characters.

For example:

{ MERGEFIELD insert chart([Task Chart] with [Priority]:1) }

{ MERGEFIELD insert chart([Task Chart] with [Priority]:1, [Status]:'Open', [Owner]:currentuser()) }

These example macros assume that there exist exactly one chart named "Task Chart", and that it is based on a report that contains (at least) a "Priority" column that contains numbers and an "Owner column" that displays Person records.

The calculation data type provided to each column needs to match the data type of the report column. For example, a text value cannot be passed to a number column.

Report name columns, and related name columns are record data types to ensure that the exact records match, rather than just all records with the same name. The value provided may be either:

• a calculation that returns a record of the appropriate type. For example, the context function or a calculation that follows a relationship.
• or the name of the record, surrounded in single quotes. There must be exactly one record of the required type that matches the name.

Typical Usage Example for Column Filters

Use column filters to achieve within a document the same type of drill down effect that you may use on screens.

For example, consider a scenario of tasks assigned to employees in departments. You may have an existing report of Departments and wish to be able to right-click on one department record and generate a Word document that includes a chart showing the number of tasks assigned to each employee in the department. This can be achieved as follows:

1. Create a new report for the chart called "Department Tasks Report"
   • Create the report to be of type Department
   • Follow the Employees relationship to show the employees in the department
   • Follow the Tasks relationship to show the Tasks for each employee
   • You should have a report that contains columns "Department", "Employee" and "Task"
   • Save the Report
2. Create a new chart named "Department Tasks Chart"
   • Create a new column chart based on the "Department Tasks Report"
   • Drag the "Employee" column onto the Primary chart input
   • Drag the "Count" source onto the Count chart input
   • You should see a column chart that shows the number of Tasks for each employee across all Departments
   • Save the Chart
3. Create a new Word document template
   • Include the macro:   { MERGEFIELD insert chart([Department Tasks Chart] with [Department]:context()) }
   • Upload the template document to the ReadiNow documents folder
   • Create a new Document Template record that Department as its Object, and the new document template selected.
   • Save the Document Template

The context function will return the department record that was right-clicked to generate the document. It should now be possible to right-click any Department record in any report of Departments and generate a document. The generated document will be filtered to only include records for the department that was right-clicked.

Display Settings

After the chart name you may optionally provide several settings to control the sizing of the chart and other aspects of how the chart is drawn. Unlike most functions, both the name and value of these settings need to be provided, with the name, followed by  a colon, then a value. A calculation may be used for the values. Each of the display settings is optional.

WidthCm and HeightCm

The WidthCm and HeightCm options allow the size of the chart, as it appears in the generated Word document, to be adjusted. You may also specify one without the other. If only one value is specified, then the other is selected automatically to maintain a consisten aspect ratio.

For example:

{ MERGEFIELD insert chart([My Chart Name], WidthCm:8, HeightCm:6) }

Rotate

The chart may be rotated by providing a clockwise rotation in degrees.

For example, to rotate to the right:

{ MERGEFIELD insert chart([My Chart Name], Rotate:90) }

PixelsPerInch

The PixelsPerInch the resolution that is used when drawing the chart. It affects the width of lines, size of text, and how many grid lines will appear.

The document generation engine uses the WidthCm, HeightCm, and PixelsPerInch settings to calculate a pixel width and height, which is then used to generate a chart as though it had that much space available.

Using Display Settings and Column Filters together

If you need to include display settings and column filters, place the display settings before the with keyword, and column filters after the keyword.

For example:

{ MERGEFIELD insert chart([Task Chart], WidthCm:6, HeightCm:5 with [Owner]:currentuser()) }