Fields
Fields are place holders in items for inserting values.
Fields Exercise
Open fields.docx in the DocxFactory/exercises/templates/ directory (see picture below).
To add fields, type the field name in squiggly brackets. You can also add an optional format after the field name separated by a space. For example: “{MyNumber #,##0.00}”.
Add the fields below to your template (see picture below):
{LineDate MMM d, yyyy} in the Date column.
{LineDesc} in the Description column.
{LineAmt $#,##0.00} in the Deposit column.
{PrintDate MMM d, yyyy} in the header of the document.
Note: The same field name can be used more than once in the same document and even in the same item. When setting the field values, if there is more than one field with the specified field name then all the fields with that name are set.
Note: If your fields do not fit in the table columns and you do not want the columns width to change while you are designing your template then you can select Fixed Column Width in the AutoFit menu in the Layout ribbon (see picture above).
Note: If you want to use squiggly brackets in your template then escape the brackets by entering double brackets (“{{“ or “}}”). The brackets will show up only once in the created .DOCX file.
There are 3 basic field types. The field type is decided according to the field format entered in the template.
Text Format
Text fields have no format and are the default field type if no format is entered.
Note: At the moment, text fields have no format but text field format is planned to be added in future versions of DocxFactory.
Number Format
Number fields use the Microsoft Excel number formats.
For example:
$#,##0.00
#0%
[GREEN]#,##0.0#;[RED]-#,##0.0#;-
In the template the number format should always be entered using the American number format (using a comma “,” for the thousands separator and a dot “.” for the decimal point). In the created .DOCX file the number values are displayed in the current DocxFactory number format. This approach allows for sharing templates created in different countries with different number formats.
Note: You can also enter colors using the six digits hexadecimal format prefixed with a #. For example: “[#FF00FF]”.
Datetime Format
Like number formats, datetime formats also use the Microsoft Excel datetime formats.
For example:
MMM d, yyyy
[h]:mm:ss.sss AM/PM
MM/dd/yyyy hh:mm:ss
In the template you can also enter a “99/99/99” or “99/99/9999” in the date format. In the created .DOCX file the day, month and year places in the date value are displayed according to the current DocxFactory date format.
Note: You can also escape characters that are used by any of the formats using the “\” sign. For example: “\M\D\Y MMM d, yyyy”.
Note: You can also use comments in your field definition using the C/C++ multiline comment syntax. For example: “{MyField /*MMM d, yyyy*/ 99/99/99}”.
Compile the template.
Create the .DOCX file.
Copy and run the code below.
using System; using System.Diagnostics; using DocxFactory; public class Runme { public static void Main() { try { // For MONO on UNIX/Linux: DocxFactory default input codepage is UTF8. // Use SetCodePage() to change the codepage. // WordProcessingMerger.SetCodePage("ISO8859-1"); var stopwatch = Stopwatch.StartNew(); WordProcessingMerger.Load( "C:/Program Files/DocxFactory/exercises/templates/fields.dfw"); WordProcessingMerger.SetClipboardValue( "_header", "PrintDate", DateTime.Now); WordProcessingMerger.Paste("Account"); for (int i = 0; i < 3; i++) { WordProcessingMerger.SetClipboardValue( "Line", "LineDate", DateTime.Now); WordProcessingMerger.SetClipboardValue( "Line", "LineAmt", (double) i); WordProcessingMerger.SetClipboardValue( "Line", "LineDesc", "Desc" + i); WordProcessingMerger.Paste("Line"); } WordProcessingMerger.Save("C:/temp/fields.docx"); Console.WriteLine( "Completed (in {0:F3} seconds).", (double) stopwatch.ElapsedMilliseconds / 1000); } catch (Exception e) { Console.WriteLine(e); } } } |
The code sets the field values of an item in the clipboard and pastes the item, copying the item with the set field values to the new document. Because of that, field values must be set before the item is pasted otherwise if the item is pasted before the values are set then the item will be pasted with empty values to the new document. Every time after a Paste method is run all the fields in the clipboard are automatically cleared so you would not need to clear old values manually.
The code sets the values for all the basic field types:
Text fields are set with a string value.
Number fields are set with a double value.
Datetime fields are set with a System.DateTime object.
In addition, the PrintDate field in the header of the document is set. The “_Header” item name is used to refer to fields that are both in the header or footer of the document. The same item name is used to refer to both the header and footer to help separate between the design and code. For example: If you move a field in the header to the footer in your template then no changes in your code will be required. Unlike regular items, the header and footer do not need to be pasted and are always part of the document.
The code introduces the SetClipboardValue method in the WordProcessingMerger class (see details below).
WordProcessingMerger.SetClipboardValue Method
Sets the field value of an item in the DocxFactory clipboard.
Sets the field with a string value.
Sets the field with a number value.
Sets the field with a datetime value.
Declaration:
1. public static void SetClipboardValue(
String itemName,
string fieldName,
string str);
2. public static void SetClipboardValue(
String itemName,
String fieldName,
double num);
3. public static void SetClipboardValue(
String itemName,
string fieldName,
System.DateTime dt);
Parameters:
itemName - Item name.
fieldName - Field name.
str - String value.
num - Number value.
dt - Datetime value.
Notes:
The item names are not case sensitive. For example: “Account” and “account” refer to the same item.
The field names are not case sensitive. For example: “LineDate” and “linedate” refer to the same field.
If there is more than one field with the specified field name then all the fields with that name are set.
If the item name is not specified (“”) then the fields anywhere in the document with the specified field name are set. It is recommended to specify an item name to avoid setting unintended fields.
Use the “_Header” item name to refer to items that are in the header or footer of the document.
If a text field is set with a number value then the number value is converted to a string value using the current DocxFactory number format.
If a number field is set with a string value then the string value is converted to a number value using the current DocxFactory number format.
Datetime fields can be set with a double value of UNIX time (seconds from 1/1/1970 at 00:00:00). Fractions of a second values are also supported.
Datetime fields can also be set with a string value of ISO datetime or just a date string in the current DocxFactory date format or just a time string.
For example:
1999-12-31T23:59:59.123+11:30 (“T” can be replaced with a blank “ “)
1999-12-31T23:59:59
1999-12-31
31/12/1999
31/12/99
23:59:59.999
23:59:59
The only way of setting the timezone for a datetime field is with an ISO datetime string value.
Open the created .DOCX file (see picture below).
The code in this exercise contains all the main components for creating a .DOCX file: create a new document from a template, set field values, paste items and save the .DOCX file. As you can see, there are only 4 main methods needed to create a .DOCX file.
 |