Skip to main content

Helpcenter

Top Level Items

Top level items are items that are not inside any other item. When a top level item is pasted it starts in a new page.

Top Level Items Exercise

The following exercises in this tutorial walk you through creating a Bank Account Activity Report.

  1. Open top_level_items.docx in the DocxFactory/exercises/templates/ directory (see picture below).

image6.png

  1. The recommended way to divide your layout into parts, in Microsoft Word, is using tables without borders. The table only purpose is layout and is completely hidden.

To see the table, click inside the table and the Design and Layout ribbons will show. In the Layout ribbon, select View Gridlines (see picture below).

image7.png

  1. To create an item, first highlight the area of the item.

Highlight the entire report (see picture below).

image8.png

  1. Then insert a bookmark for the highlighted area with the name of the item.

In the Insert ribbon, press the Bookmark button to open the Bookmark dialog box. In the Bookmark name, type “Account” and press the Add button (see picture below).

image9.png

Note: A table cell cannot be marked as an item so it will not be possible to create a table with rows that have a different number of cells. A table row is the smallest part of a table that can be marked as an item. If a table cell is marked as an item then the area is expanded to mark the whole table row. Future versions will support marking columns for horizontal pasting.

Note: In most cases, you’ll find it easier if you create items that map closely to your data structure. For example: if you have a Bank Account table with the Bank Account’s data, you can create a Bank Account item with the Bank Account’s fields.

A top level item should start after the previous page break (or the start of the document) and end right before the next page break (or the end of the document) where the next top level item starts (see picture below).

For 2 reasons: 1. The start of a new page at the start of the top level item in the template is the start of a new page when the top level item is pasted in the new document. 2. Everything in the template should be in an item.

Even though you can: not put everything in items, put more than one top level item between page breaks, put page breaks in the middle of an item or not put any items in the template this is not the intended use and although the template will still compile and the program will still run you may not get the results you intended.

  1. Before you can use the template you must compile the .DOCX file to a .DFW file - (D)ocx (F)actory (W)ordprocessing template file.

Copy and run the code below.

#include "dfwc.h"

#include <stdio.h>

#include <time.h>

int main()

{

time_t l_start = clock();

dfwc_compile( "/opt/DocxFactory/exercises/templates/top_level_items.docx",

"/opt/DocxFactory/exercises/templates/top_level_items.dfw");

if (dfwc_getErrorFlag()) goto ERROR;

printf("Completed (in %.3f seconds).\n",

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

return 0;

ERROR:

printf("%s\n", dfwc_getErrorWhat());

return 1;

}

The code compiles the template file. If the template is successfully compiled then the time it took to compile is displayed. If an exception is thrown then the description of the exception is displayed.

Note: The code in the exercises uses the Linux installation directories for running on Linux. To run the code on Windows, use the Windows installation directories.

Note: You can get the source .DOCX file from the compiled .DFW file, in case the .DOCX file is lost. The .DFW file is actually a .ZIP file. You can open the .ZIP file (on Windows you can add a .ZIP extension to the end of the file name and open the .ZIP file with the Windows Explorer) and find the .DOCX file inside in the root directory with a # prefix.

The code introduces the dfwc.h include file, its dfwc_compile function and error handling functions (see details below).

dfwc.h Include File

The DocxFactory Word Processing Compiler Include File.

Header File:

#include "dfwc.h"

Functions:

dfwc_compile

  • Compiles a .DOCX file to a .DFW file.

dfwc_setTempDir

  • Sets the temporary directory used for saving temporary files.

dfwc_getTempDir

  • Returns the temporary directory.

dfwc_getWorkDir

  • Returns the current working directory used for resolving relative paths.

dfwc_getErrorWhat

  • If an error occurred in the last function call then returns the error description.

dfwc_getErrorFlag

  • If an error occurred in the last function call then returns true.

dfwc_compile Function

Compiles a .DOCX file to a .DFW file.

Declaration:

unsigned char dfwc_compile(

const char* p_sourceFile, const char* p_targetFile);

Parameters:

p_sourceFile - The source .DOCX file.

p_targetFile – The target .DFW file.

Notes:

  • Relative paths are resolved relative to the current working directory. For example: “dir/template.docx” is resolved to “[working directory]/dir/template.docx”.

  • The target file must end with a “.dfw” file extension. If it does not then a “.dfw” file extension is added to the end of the file name.

  • If the target file is blank then the source file is used.

dfwc_getErrorFlag Function

If an error occurred in the last function call then returns true.

Declaration:

unsigned char dfwc_getErrorFlag();

dfwc_getErrorWhat Function

If an error occurred in the last function call then returns the error description.

Declaration:

const char* dfwc_getErrorWhat();

  1. Create a new document from the template we created, paste the top level item and save the .DOCX file.

    Copy and run the code below.

#include "dfw.h"

#include <stdio.h>

#include <time.h>

int main()

{

time_t l_start = clock();

dfw_load("/opt/DocxFactory/exercises/templates/top_level_items.dfw");

if (dfw_getErrorFlag()) goto ERROR;

for (int i = 0; i < 3; i++)

{

dfw_paste("Account");

}

dfw_save("/tmp/top_level_items.docx");

if (dfw_getErrorFlag()) goto ERROR;

printf("Completed (in %.3f seconds).\n",

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

return 0;

ERROR:

printf("%s\n", dfw_getErrorWhat());

return 1;

}

The code introduces the dfw.h include file and its dfw_load, dfw_paste and dfw_save functions (see details below).

dfw.h Include File

The DocxFactory Word Processing Merger Include File.

Header File:

#include "dfw.h"

Functions:

dfw_load

  • Creates a new document from a .DFW template.

dfw_save

  • Saves the new document to a .DOCX file (possibly converts to a .PDF, .HTML or other) and closes the document. The document cannot be used after it is closed.

dfw_print

  • Prints the new document and closes the document.

dfw_close

  • Closes an open document. Used for checking fields and items only without saving.

dfw_setClipboardValueByStr

  • Sets a field value of an item in the clipboard from a string value.

dfw_setClipboardValueByDouble

  • Sets a field value of an item in the clipboard from a double value.

dfw_setChartValueByStrStr

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

dfw_setChartValueByStrDouble

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

dfw_setChartValueByDoubleDouble

  • Sets a value in the chart field values matrix by X double value and Y double value.

dfw_paste

  • Pastes an item from the clipboard with its field values to the new document.

dfw_merge

  • Merges XML or JSON with the template.

dfw_getItems

  • Returns a comma separated list of all the items in the template.

dfw_getFields

  • Returns a comma separated list of all the fields in the template.

dfw_getItemFields

  • Returns a comma separated list of all the fields in an item.

dfw_getItemParent

  • Returns the parent of an item.

dfw_setLocale

  • Sets the locale which sets all the regional settings i.e. code page, number and date format, week days and month names etc.

dfw_setCodePage

  • Sets the code page for strings passed to dfw_setClipboardValue procedure.

dfw_setNumFracSep

  • Sets the number fraction separator sign.

dfw_setNumThSep

  • Sets the number thousand separator sign.

dfw_setDateFormat

  • Sets the date format.

dfw_setYearOffset

  • Sets the year offset for 2 digit years.

dfw_setFirstWeekDay

  • Sets the first week day.

dfw_getLocale

  • Returns the locale.

dfw_getCodePage

  • Returns the code page.

dfw_getNumFracSep

  • Returns the number fraction separator sign.

dfw_getNumThSep

  • Returns the number thousand separator sign.

dfw_getDateFormat

  • Returns the date format.

dfw_getYearOffset

  • Returns the year offset.

dfw_getFirstWeekDay

  • Returns the first day of the week.

dfw_setTempDir

  • Sets the temporary directory used for saving temporary files.

dfw_getTempDir

  • Returns the temporary directory.

dfw_getWorkDir

  • Returns the current working directory used for resolving relative paths.

dfw_printFile

  • Prints a file from disk. Unlike printDoc the document does not need to be loaded and generated before printing.

dfw_getErrorWhat

  • If an error occurred in the last function call then returns the error description.

dfw_getErrorFlag

  • If an error occurred in the last function call then returns true.

dfw_load Function

Creates a new document and cuts all the template items into the DocxFactory clipboard.

Declaration:

unsigned char dfw_load(const string& p_templateFile);

Parameters:

p_templateFile - The template .DFW file.

Notes:

  • Relative paths are resolved relative to the current working directory. For example: “dir/template.dfw” is resolved to “[working directory]/dir/template.dfw”.

dfw_paste Function

Pastes an item from the DocxFactory clipboard with all its field values on to the new document.

Declaration:

unsigned char dfw_paste(const char* p_itemName);

Parameters:

p_itemName – The item name.

Notes:

  • The item names are not case sensitive. For example: “Account” and “account” refer to the same item.

dfw_save Function

Saves the new document out to a file. After saving, the document is closed and no more data can be merged until a new template is loaded.

Declaration:

unsigned char save(const char* p_targetFile);

Parameters:

p_targetFile – The target file.

Notes:

  • If the target file is not a .DOCX file (for example: .PDF file) then DocxFactory first saves the document as a .DOCX file and then converts the file to the target file.

  • Relative paths are resolved relative to the current working directory. For example: “dir/template.docx” is resolved to “[working directory]/dir/template.docx”.

  1. Open the created .DOCX file.

    As you can see, every top level item starts in a new page (see picture below).

    image10.png

  2. Save as .PDF file.

    In your code, change the save file to "/tmp/top_level_items.pdf". Run and open the file (see picture below).

    image11.png

Note: DocxFactory can only create .DOCX files directly. To create .PDF, .HTML or other file formats, DocxFactory first creates a .DOCX file and then converts the file using conversion tools. Likewise to print, DocxFactory uses printing tools.

You must have printing and conversion tools installed to print and convert to other file formats (see the chapter on printing and conversion tools installation in the beginning for details).

In this section: