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.
Open top_level_items.docx in the DocxFactory/exercises/templates/ directory (see picture below).
 |
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).
 |
To create an item, first highlight the area of the item.
Highlight the entire report (see picture below).
 |
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).
 |
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.
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.
import com.docxfactory.WordProcessingCompiler; public class runme { public static void main(String argv[]) { try { long startTime = System.currentTimeMillis(); WordProcessingCompiler.compile( "/opt/DocxFactory/exercises/templates/top_level_items.docx", "/opt/DocxFactory/exercises/templates/top_level_items.dfw"); System.out.println( "Completed (in " + (double) (System.currentTimeMillis() - startTime) / 1000 + " seconds)."); } catch (Throwable e) { System.err.println(e); } } } |
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 com.docxfactory package, its WordProcessingCompiler class and its compile method (see details below).
WordProcessingCompiler Class
Provides methods for compiling template files.
Package:
import com.docxfactory.*;
Methods:
compile |
|
|---|---|
setTempDir |
|
getTempDir |
|
getWorkDir |
|
WordProcessingCompiler.compile Method
Compiles a .DOCX file to a .DFW file.
Declaration:
public static void compile(String p_sourceName, String p_targetName);
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.
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.
import com.docxfactory.WordProcessingMerger; public class runme { public static void main(String argv[]) { try { long startTime = System.currentTimeMillis(); WordProcessingMerger.load( "/opt/DocxFactory/exercises/templates/top_level_items.dfw"); for (int i = 0; i < 3; i++) { WordProcessingMerger.paste("Account"); } WordProcessingMerger.save("/tmp/top_level_items.docx"); System.out.println( "Completed (in " + (double) (System.currentTimeMillis() - startTime) / 1000 + " seconds)."); } catch (Throwable e) { System.err.println(e); } } } |
The code introduces the WordProcessingMerger class and its load, paste and save methods (see details below).
WordProcessingMerger Class
Provides methods for merging templates with data.
Package:
import com.docxfactory.*;
Methods:
load |
|
|---|---|
save |
|
printDoc |
|
closeDoc |
|
setClipboardValue |
|
setChartValue |
|
paste |
|
merge |
|
getItems |
|
getFields |
|
getItemFields |
|
getItemParent |
|
setUpdateTocMethod |
|
setLocale |
|
setCodePage |
|
setNumFracSep |
|
setNumThSep |
|
setDateFormat |
|
setYearOffset |
|
getLocale |
|
getCodePage |
|
getNumFracSep |
|
getNumThSep |
|
getDateFormat |
|
getYearOffset |
|
getFirstWeekDay |
|
setTempDir |
|
getTempDir |
|
getWorkDir |
|
printFile |
|
WordProcessingMerger.load Method
Creates a new document and cuts all the template items into the DocxFactory clipboard.
Declaration:
public static void load(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”.
WordProcessingMerger.paste Method
Pastes an item from the DocxFactory clipboard with all its field values on to the new document.
Declaration:
public static void paste(String 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.
WordProcessingMerger.save 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:
public static void save(String 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”.
Open the created .DOCX file.
As you can see, every top level item starts in a new page (see picture below).
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).
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).