Skip to main content

Helpcenter

Chart Fields

Charts are another special field. A big difference between charts and other fields is that unlike other fields which only hold a single value, charts hold multiple values. In most cases, charts display a value as a column at the height of the value for a sequence of categories. Other series of values (for the same categories) can be displayed in a different color. So charts hold a matrix of values by categories and series.

There are several exceptions:

  1. Single series charts

  • That can only have a single series like Pie charts (Doughnut charts are not a single series charts like Pie charts because they can have multiple series represented by different rings).

  1. Fixed series charts

  • That have a fixed number of series like Stock and Composite charts.

  1. X, Y, Size charts

  • That hold a list of X, Y, Size values like Scatter and Bubble charts instead of a values matrix by series and categories.

Chart Fields Exercise

  1. Open a new blank document and insert a column chart.

    Open a new blank document. Select Chart in the Insert ribbon to open the Insert Chart dialog box and select Clustered Column Chart from the Insert Chart dialog box (see picture below).

    image40.png

  2. Change the categories data type and format.

    After you insert a chart the values matrix by categories and series is opened and can be edited in Excel. Insert date values for the categories and set the format to month and year (see picture below).

    image41.png

    Just like all other fields, you set the data types and formats in the template and insert the values when creating a new document so all the values and number of series, categories and values will be removed and replaced with the values you insert but the data types and formats will remain.

    The series are the names of series of values by categories so they can only be text values. The sequence of categories can be date, number or text values. The values are represented by column heights so they can only be number values. Except for X, Y, Size charts which hold a list of X, Y, Size number values.

  3. Enter the chart field name.

    Select the chart. Click the corner of the Size group in the Format ribbon to open the Size dialog box. Select the Alt Text tab in the Size dialog box and enter "{ExpenseChart}" in the Alternative Text box (see picture below).

    image42.png

  4. Compile the template.

  5. Create the .DOCX file.

    Copy and run the code below.

#include "WordProcessingMerger.h"

#include <exception>

#include <iostream>

#include <ctime>

using namespace DocxFactory;

using namespace std;

int main()

{

try

{

WordProcessingMerger& l_merger =

WordProcessingMerger::getInstance();

time_t l_start = clock();

l_merger.load("/opt/DocxFactory/exercises/templates/chart.dfw");

l_merger.setChartValue("", "ExpenseChart", "Income", "2015-01-01", 3600.0);

l_merger.setChartValue("", "ExpenseChart", "Income", "2015-02-01", 3600.0);

l_merger.setChartValue("", "ExpenseChart", "Income", "2015-03-01", 3600.0);

l_merger.setChartValue("", "ExpenseChart", "Income", "2015-04-01", 4200.0);

l_merger.setChartValue("", "ExpenseChart", "Income", "2015-05-01", 4200.0);

l_merger.setChartValue("", "ExpenseChart", "Expense", "2015-01-01", 1000.0);

l_merger.setChartValue("", "ExpenseChart", "Expense", "2015-02-01", 1200.0);

l_merger.setChartValue("", "ExpenseChart", "Expense", "2015-03-01", 1300.0);

l_merger.setChartValue("", "ExpenseChart", "Expense", "2015-04-01", 1100.0);

l_merger.setChartValue("", "ExpenseChart", "Expense", "2015-05-01", 2200.0);

l_merger.save("/tmp/chart.docx");

cout<< "Completed (in "

<< (double) (clock() - l_start) / CLOCKS_PER_SEC

<< " seconds)."

<< endl;

}

catch (const exception& p_exception)

{

cout << p_exception.what() << endl;

}

}

Note: That no items were created in the template and no items were pasted in the code. DocxFactory supports templates that have only fields for such cases as simple letters.

The code introduces the setChartValue function in the WordProcessingMerger singleton (see details below).

DocxFactory::WordProcessingMerger::setChartValue Function

Sets a value in the chart field values matrix by category and series.

There are several exceptions:

  1. Single series charts

  • For charts that can only have a single series like Pie charts, the setChartValue function ignores the series name parameter. The series name in the created document is the same series name in the template.

  1. Fixed series charts

  • For charts that have a fixed number of series like Stock and Composite charts, the setChartValue function only accepts values for the fixed series that were in the template. Values for other series are ignored and are not set.

  1. X, Y, Size charts

  • For charts that hold a list of X, Y, Size values like Scatter and Bubble charts, the setChartValue function treats the 1st parameter as the X value, the 2nd parameter as the Y value and the 3rd parameter as the Size value regardless of their data type.

Declaration:

1. void setChartValue(

const string& p_itemName,

const string& p_fieldName,

const string& p_series,

const string& p_category, double p_value);

2. void setChartValue(

const string& p_itemName,

const string& p_fieldName,

const string& p_series,

double p_category, double p_value);

3. void setChartValue(

const string& p_itemName,

const string& p_fieldName,

double p_x,

double p_y, double p_size);

Parameters:

p_itemName - Item name.

p_fieldName - Field name.

p_series - Series name.

p_category - Category.

p_value - Value. p_x - X. p_y - Y. p_size - Size.

Notes:

  • The sort order of the chart series and categories in the created document is the order you add them to the values matrix.

  • The series and categories (if the categories values are text) are not case sensitive. For example: the series "Income" and "income" refer to the same series but the chart series and categories in the created document use the series and categories casing when they were first added with the exception of single series charts and fixed series charts that keep the series casing in the template.

  • Every time you add a new column or row to the values matrix by adding a new series or category the new values are initialized with a value of zero. For example: if you add a new series and not set one of the values for a category for that series then its value will be zero.

  • An empty chart with no values cannot be shown so if no values are set for a chart field then the chart will not be in the created document.

  • If a value for the same category and series is set more than once then the value is accumulated so you can set a chart field from a detailed list that will be summarized by categories and series.

  • The setChartValue function is the equivalent setClipboardValue function for chart fields and has the same rules for item and field casing, setting date and time values and converting between different field and parameter data types.

    1. Open the created .DOCX file (see picture below).

      image43.png
In this section: