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).

    image2.png

  2. 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).

    image3.png

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

    Highlight the entire report (see picture below).

    image4.png

  4. 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).

    image5.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.

    template-docxfactory.png

    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.

  5. 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 following code:

    USING DocxFactory.*.
ETIME(TRUE).
WordProcessingCompiler:compileTemplateIfChanged(   
    "/opt/DocxFactory/exercises/templates/top_level_items.docx",   
    "/opt/DocxFactory/exercises/templates/top_level_items.dfw").
MESSAGE "Completed (in" ROUND(ETIME(FALSE) / 1000, 3) "seconds)".
CATCH oErr AS Progress.Lang.AppError:
    MESSAGE oErr:ReturnValue VIEW-AS ALERT-BOX.
END CATCH.

    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 DocxFactory package, its WordProcessingCompiler class and its compileTemplateIfChanged method (see details below).

WordProcessingCompiler Class

Provides methods for compiling template files.

Package:

USING DocxFactory.*.

Methods:

compileTemplate

Compiles a .DOCX file to a .DFW file.

compileTemplateIfChanged

Compiles a .DOCX file to a .DFW file, if there is no .DFW or the .DOCX was updated after compiling the .DFW file (.DOCX timestamp > .DFW timestamp) or the DocxFactory version is different than the DocxFactory version used to compile the .DFW file.

setFieldBracket

Sets the field brackets e. g. '<>'.

setFieldFormats

Sets field formats which adds to or overrides the existing field formats in the template.

WordProcessingCompiler:compileTemplateIfChanged Method

Compiles a .DOCX file to a .DFW file, if there is no .DFW or the .DOCX was updated after compiling the .DFW file (.DOCX timestamp > .DFW timestamp) or the DocxFactory version is different than the DocxFactory version used to compile the .DFW file.

Declaration:

METHOD STATIC PUBLIC VOID compileTemplateIfChanged(

INPUT pcSourceFile AS CHARACTER,

INPUT pcTargetFile AS CHARACTER ).

Parameters:

pcSourceFile - The source .DOCX file.

pcTargetFile – 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.

  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.

USING DocxFactory.*.

DEFINE VARIABLE i AS INTEGER NO-UNDO.

ETIME(TRUE).

WordProcessingMegrer:loadTemplate(

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

DO i = 1 to 3:

WordProcessingMerger:paste("Account").

END. /* 1 to 3 */

WordProcessingMerger:saveDoc("/tmp/top_level_items.docx").

MESSAGE "Completed (in" ROUND(ETIME(FALSE) / 1000, 3) "seconds)".

CATCH oErr AS Progress.Lang.AppError:

MESSAGE oErr:ReturnValue VIEW-AS ALERT-BOX.

END CATCH.

The code introduces the WordProcessingMerger class and its loadTemplate, paste and saveDoc methods (see details below).

WordProcessingMerger Class

Provides methods for merging templates with data.

Package:

USING DocxFactory.*.

Methods:

loadTemplate

  • Creates a new document from a .DFW template.

saveDoc

  • 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.

printDoc

  • Prints the new document and closes the document.

closeDoc

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

setClipboardValue

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

setChartValue

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

paste

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

merge

  • Merges XML or JSON with the template.

getItems

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

getFields

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

getItemFields

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

getItemParent

  • Returns the parent of an item.

setUpdateTocMethod

  • Sets the table of contents automatic update method.

setLocale

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

setCodePage

  • Sets the code page for strings passed to SetClipboardValue method.

setNumFracSep

  • Sets the number fraction separator sign.

setNumThSep

  • Sets the number thousand separator sign.

setDateFormat

  • Sets the date format.

setYearOffset

  • Sets the year offset for 2 digit years.

getLocale

  • Returns the locale.

getCodePage

  • Returns the code page.

getNumFracSep

  • Returns the number fraction separator sign.

getNumThSep

  • Returns the number thousand separator sign.

getDateFormat

  • Returns the date format.

getYearOffset

  • Returns the year offset.

getFirstWeekDay

  • Returns the first day of the week.

setTempDir

  • Sets the temporary directory used for saving temporary files.

getTempDir

  • Returns the temporary directory.

getWorkDir

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

printFile

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

WordProcessingMerger:loadTemplate Method

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

Declaration:

METHOD STATIC PUBLIC VOID loadTemplate(

INPUT pcTemplateFile AS CHARACTER ).

Parameters:

pcTemplateFile - 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”.

WordProcessingMerger:paste Method

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

Declaration:

METHOD STATIC PUBLIC VOID paste( INPUT pcItemName AS CHARACTER ).

Parameters:

pcItemName – The item name.

Notes:

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

WordProcessingMerger:saveDoc Method

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:

METHOD STATIC PUBLIC VOID saveDoc( INPUT pcTargetFile AS CHARACTER ).

Parameters:

pcTargetFile – 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).

    image6.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).

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