Visual-XSL (VisualXSL) User Guide

The primary purpose of the application is to prepare a XSL stylesheet to format a document (with already existing static form). The result of application work can be both XSL stylesheet and formatted PDF/PS document with using of XEP formatter. Its advantage lies in performing of formatting for dynamic data only, using static form data as background.

That considerably speeds up document formatting in comparison to traditional method of doing it.

Easy-To-Use Layout Designer

A user can design a document visually using VisualXSL application. The application enables a user to put data fields onto document layout. A user can just drag and drop data directly to layout designer.

The layout designer (also mentioned below as the layout or the designer area) has a very simple style, and can be learned easily and fast.

High-Speed Document Generation

VisualXSL generates specific stylesheet to render your designed document. With this stylesheet XEP formatter provides high speed of the PDF (or PostScript) document generation.

Single- and Multi-Page Forms Support

Multi-page forms can be filled with data as well as single page ones.

If a user set a multi-page PDF as a background, application will extract every page to the separate PDF and set it as the background of corresponding page in the project. New pages will be created automatically if needed. The application offers user an opportunity to create an Acrobat PDF form from existing project.

Textboxes, Check Boxes, Pictures and Barcodes

There are the following types of data fields that can be placed into a form:

Text fields will be rendered as a text from the XML.

Check boxes will be rendered as check marks that will appear depending on the XPath expression result.
Pictures will be rendered according to the size set on the layout.
Barcodes will be rendered using RenderX stylesheets and the data from the XML source file. The barcodes can be of UPC-A (E, EAN-13, EAN-8), Interleaved2of5, codabar, code39 types.
Paragraph blocks can be inserted and edited by application. They can be formed from XPath expressions as well as from static text. Also application can provide different formatting for block text parts.
Special field can be inserted into project, it will be used to declare additional parameter for generated stylesheet and field’s value will be used for parameter as default one.
Additional formatting can be applied to field containing date values (in ODBC or ISO8601 format).
Group of selected frames can be aligned to the first object in the selection.
All fields can be rotated at the angle divisible by 90 degrees.

Conditional Rendering

Every data field has a property that can be set to determine its rendering under certain condition.

XPath Validation

Almost all XPath expressions are created automatically when a user drags and drops XML tree node to layout designer. But a user can also create or edit them manually. The application validates all XPath expressions and offers to modify a wrong expression.

Docking Windows

The application gives an opportunity to use a docking window interface. A user can dock and undock tool windows to create an optimal work configuration. For example, if there is a dual-monitor system, some tool windows can be undocked and placed on the second monitor.

Print XML Data on Preprinted Form

The application makes possible for user to print XML data over the paper (preprinted) form. See the section “How to Fill in Preprinted Forms with Data” for more information.

Generation of Fillable PDF Form

The application has an option to generate Fillable PDF Form for documents with PDF background (currently textboxes and checkboxes are supported). See the section “How to Generate Fillable PDF Form” for more information.

2. Installation

2.1. Hardware/Software Requirements

Before installing the application you have to get the following list of software installed:

Microsoft Windows 2000/XP/2003 Server.
Microsoft .NET Framework 2.0.
RenderX XEP formatter 4.5 or later.
RenderX XEP Win 2.1 (a part of the installation package).
Adobe Acrobat Reader 5.x. or later.
Microsoft Internet Explorer 5.5 or later.
Any PostScript viewer (optional, to have an ability to preview prepared PostScript documents).

2.2. How to Install VisualXSL

Run setup.exe and follow the installation instructions. If a user has failed to set correct path to license.xml, the license file can be copied to the application installation folder (by default: C:\Program Files\RenderX\VisualXSL).

2.3. Inside the Product Package

The installation folder contains the following subfolders:

“XSL” contains XSL stylesheets used internally by the application and it is not to be used separately from application.
“Etc” contains some data used internally.
“Doc” contains user's manual.

After the installation new folder will be created (see below):

…\All Users\Documents\VisualXSL Projects – all users’ shared documents folder.

3. Getting Started

3.1. Making Your First Project

Let’s start from the simplest (andnow existing) project. Suppose that you have to prepare a great number of reports in W9 form. You have already found a sample PDF file with W9 form on the Internet and you have XML file exported from your database. Your task is to prepare reports from these data.

Try to repeat creating one of sample projects W9 step-by-step.

So, start the application. As soon as it has started a new project is created.
Prepare a new folder in “All Users\Documents\VisualXSL Projects” for it. Call it “1stTry”. Copy “w9src.xml” and “w9_blank.pdf” files from “All Users\Documents\VisualXSL Projects” to new directory.
Add data source (File -> Open Source XML), select “w9src.xml” from a newly created folder. Mind that node “batch/W9” is set as Pattern property by application in page properties after the last step. Save your project as “1stTry.vxl”.
Click on the design layout. Then page properties will be shown in the appropriate window. Select BackgroundPath property, click (…) button and open “w9_blank.pdf” file. Application will show its rasterized image on design layout.

Fig. 3.1.1 BackgroundPath property for a new project page

Find in XML tree “name” node, drag and drop it to the layout. Place and resize it to fit template in background form.
Switch to its properties. Expand InnerText property, then TextProperties. Change its font settings clicking the (…) button. You can change formatting not only for one data field at a time but for all data fields on the whole page (once specific formatting is not already set for data field). As you are going to add data fields with the same formatting, change page formatting properties (TextProperties->Font Arial; 10pt).

Fig. 3.1.2 Text formatting properties of the selected data field

So the first steps are made. It is time to see what you will get as a result. Click preview button in toolbar and switch to Log window. You can monitor the formatting process by tracing messages from XEP formatter. In a second you will have the preview of resulting document.
Drag and drop the rest of XML nodes to layout (except the ones corresponded to checkboxes). Resize them to fit empty spaces on the background. Do not bother with additional formatting so far, you will do it later. Then your project should look like the one from the screenshot (Fig. 3.1.2).
But your project is still far from being perfect. There must be marks done in empty squares (they should be rendered under certain conditions), the address must be correctly formed fromcity, state, and ZIP node values; the data field with SSN (or employes indentification number) should be justified across the appropriate rectangle.
First of all correct the data field with city name. You should change the property Pattern to “batch/W9” and InnerText->XPathValue to “concat(city,', ',state,' ',zip)” to do it. So XSL code will be generated in template with attribute match=“batch/W9” and also will render data getting by XPath expression “concat(city,', ',state,' ',zip)”.
Moreover you should make checkmarks in appropriate boxes. For getting that, select the XML node “batch/W9” and choose Data->Add CheckBox from the menu. Switch to the property Test of the created field and type in the following: “entity_type = 'individual'” (XPath expression to be used asthe condition to render the field). So the field will be rendered only if the condition is true. Repeat this procedure for the rest of checkboxes, setting the Test property correspondingly “entity_type = 'corporation'”, “entity_type = 'partnership'” and “entity_type = 'other'”.
And the last step is correcting of social id number placing. Select soc_sec_number in the XML tree and drag it to the layout. Resize it to fit the grid on the background.
Choose BlockProperties–>AlignLastproperty and change its value to “Justify”, to set spaces between digits properly. Make a preview of the project. Now you are supposed to have result similar to sample W9 project one (except barcodes).

Fig. 3.1.3 Unfinished project (no checkmarks, malformed address, etc)

3.2. Creating a New Project from the Scratch

Now you should prepare XML source and PDF background by yourself. It is not as difficult as it seems. To complete this tutorial you must have Microsoft Office Professional Edition 2003 (or greater) installed. You will use Microsoft Excel to prepare XML source file and Microsoft Word to make an invitation letter form. You are supposed to prepare and mail anniversary party invitations to all company managers from name of its CEO. All employees’ information is stored in Excel spreadsheet (see Fig. 3.2.1). The letter should look like the one on the Fig. 3.2.1 and you should be able either to print it and to e-mail it as an electronic document.

Fig. 3.2.1 The invitation letter

Fig. 3.2.2 Data in the Excel spreadsheet

First of all create XML source file. You should have some XML schema to be able to map data to XML tags and export it to XML file. The simplest way to do that is to prepare a little XML file describing the common structure of your data.

Your XML file should look like following one (you can omit some elements not necessary for your task). Write down XML node corresponding to data record twice to make MS Excel understand that this node can be replicated many times. Here it is:

<LastName>Davolio</LastName>

<FirstName>Nancy</FirstName>

<Title>Sales Representative</Title>

<City>Seattle</City>

</record>

<LastName>Davolio</LastName>

<FirstName>Nancy</FirstName>

<Title>Sales Representative</Title>

<City>Seattle</City>

</record>

</employees>

Attach new XML map by doing the following:

1) Open XML source tab by selecting Data >> XML >> XML Source.

2) Then click on “XML maps…” button that will bring up the window with XML map list.

3) Add a new one by clicking “Add…” button and selecting the prepared XML file as XML source.

4) When a warning message that no XML schema is referred to this file appears, just click “Ok” and Excel will create schema automatically.

Fig. 3.2.3 Warning that Microsoft Excel will create a schema based on selected XML file.

Now you have to map all XML elements to spreadsheet data columns. After you have finished that you can export the spreadsheet to XML.

Fig. 3.2.4 XML elements mapped to Microsoft Excel spreadsheet data columns.

Save your spreadsheet as XML file to your project folder.

It is time to prepare PDF document that should be used as the background. Use Microsoft Word text processor and create a document with space left for data to be changed. The document may look like this one (see Fig. 3.2.5). Save it as an XML (WordML) file.

Fig. 3.2.5 Letter with space left for employee personal data

Use XEP Assistant and WordML2FO stylesheets from XEPWin package to produce a PDF file from your mockup. Finally you have all necessary files to create a new project.

3.3. Preparing XML File: Exporting Data from SQL Server

Let's make an example using test database Northwind. We will use Query Analyzer (Microsoft SQL Server 2000) for data conversion.

Open SQL Query Analyzer (Microsoft SQL Server 7/2000). Connect to database Northwind.
We will convert data from table Employees (see Fig.3.3.1).

Fig. 3.3.1 Data in Employees table

Let’s assume, that a file with converting data should be placed here c:\temp\
Create in this folder conversion template file “template.tpl” using any text editor.
Write down there following

<root>

<%begindetail%>

<%insert_data_here%>

<%enddetail%>

</root>

Put (type or paste) the following query into SQL Query Analyzer window (see Fig.3.3.2):

EXECsp_makewebtask @outputfile ='c:\temp\myxmlfile.xml',

@query = 'select * from Employees for xml auto',

@templatefile = 'c:\temp\template.tpl'

Where:

@outputfile - a full way to file XML.

@query – sql query for necessary data

@templatefile - the file template on which will be made XML a file.

Run the query by pressing F5 or select Query -> Execute from menu.

As result of query execution you will have a “myxmlfile.xml” file in the folder c:\temp\

Fig.3.3.2 Query to export table data

Finally, we have Employees table data exported to XML format (see Fig. 3.3.3).

Fig. 3.3.3 Resulting XML file

4. Interface

4.1. Application Panes and What They Are Intended For

Application has docking style tool window interface (“pane” term is used as well as “tool window” one further on documentation). There are several predefined windows layout combinations. The project window consists of the following panes:

Fig. 4.1.1 VisualXSL interface with sample project W9 opened

XML Tree View displays a XML schema.
XPath View displays a list of XPath expressions.
Layout(Designer Area) represents the primary working area, where all the data fields are placed according to the form mockup on the background.Almost all actions that were made in this pane can be rolled back using Undo command. There are some specifics about this feature:
- All changes made to the data field, while it is still selected are considered as one, so Undo/Redo will treat them as a single action. To have possibility to undo some particular change of data field change selection before doing it.
- All operations concerning adding or removing pages can not be undone.
Selected data fields or a whole page can be copied (cut) to Clipboard and then pasted into the same or another window of the application several times.
Important! Please make sure that new pasted data field has correct XPath expression (you can do it by selecting Build->Validate (F6)) or clicking appropriate toolbar button.
Properties pane displays properties of the selected object in the property grid. In order to distinguish it further in documentation we will refer to this pane as “object properties”. User can select few objects clicking them with Ctrl button pressed. Only common properties of selected objects are displayed. In the case the properties values coincide they are displayed with current value, otherwise they are shown as blank.
Preview shows PDF document preview.
Log stores all formatter messages.

User can choose the most comfortable tool windows combination from predefined set (menu Window) or arrange tool windows manually. Anyway the last window configuration will be saved if application exits successfully and will be restored on the next application startup.

4.2. Menus and Toolbars

The basic commands are placed on the tool bar for quick access. Most of them are available in the menu.

File operations

New Project creates new project.

Open is a drop-down button list (see the description below).

Open Project loads an existing project.

Open Source XML opens and adds XML data source to the project.

Save Project saves changes of the current project.

Print prints currently generated PDF document.

Data operations

Add Text Data Field adds text field using XPath expression of the current XML node to get data from the XML source file to the layout.

Add BarcodeData Field adds barcode field using XPath expression of the current XML node to get data from the XML source file to the layout.

Add Picture Data Field adds empty image field to the layout.

Insert Page Number Field inserts page number data field to the layout.

Add Checkbox Data Field adds checkbox to the layout. Test property could be specified to render it under certain condition. It must be the correct XPath expression in the context of the node-set determined by the expression from Pattern property.

Add Address Labelstarts the wizard to add an address label to the layout.

Add Paragraphadds an empty paragraph block to the design layout (see detailed description in “5.8. Paragraph Block” section).

Edit operations

Remove Data Field removes a selected data field from the layout.

Add Page, this option adds a new page to the project (available in the menu only).

Remove Page, this option removes the current page from the project (available in the menu only).

Undo Last Action rolls back the last action.

Redo Last Undone Action redoes the last undone action.

Note. All actions performed to the data field are considered to be a single action, while the data field is still selected. For example, if the data field size and position are changed while it is selected undo will rollback both changes. However, if the size is changed for data field and position for another one, then Undo will rollback the last action only.

Cutis a standard "cut to clipboard" command

Copy is a standard "copy to clipboard" command

Pasteisa standard "paste from clipboard" command

Edit Para/Finish Editing Para, this option starts or finishes editing of paragraph block according to the current name.

Build operations

Validate checks all XPath expressions in all data fields in the project.

Refresh design layoutcalculates all XPath expressions and refreshes data fields content on the design layout (where it’s possible).

Generate XSL generates XSL stylesheet for the current layout. Then this stylesheet could be used with RenderX XEP formatter to produce PDF files.

Preview generates PDF document preview using the specified number of data records.

Create PDF generates a document (PDF or Postsript) using all data records from data source.

Generate PDF form generates a Fillable PDF Form using opened project.

Selection alignment buttons

Aligns object selection to leftside of the first selected frame.

Aligns object selection to center (horizontally)of the first selected frame.

Aligns object selection to rightside of the first selected frame.

Aligns object selection to topside of the first selected frame.

Aligns object selection to center (vertically)of the first selected frame.

Aligns object selection to bottomside of the first selected frame.

Makes all objects height the sameas the first object height.

Makes all objects width the sameas the first object width.

Makes all objects size the sameas the first object size.

Other operations

Zoom scales the layout.

Active page switches the current page (available for multi-page forms).

Open Helpopens the user’s manual.

4.3. Application Options

The application options dialog can be accessed by main menu Options→ Preferences.

Fig. 4.3.1 Options dialog

Rendering

Number of records to preview enables to limit the number of records used to generate the preview. It can be useful in case of source XML contains a big number of records.
Open last project on start enables/disables last project to be opened automatically on start of the application.
Render form background switch on/off generation of the form background.

Rasterization

Resolution of the rasterized image, dpi (dots per inch)specifies the horizontal and vertical resolution of the rasterized image of the form background.
Color depth of the rasterized images is the number of bits per pixel in an image format used to rasterize the form background.
File format used for rasterized images is the raster format of the image file.

Note. Only Number of records to preview and Render from background options will take an effect immediately, others require application restart.

Layout Grid

Snap to grid switches on/off designer area feature to align data field to the grid.
Grid size is the size of grid cell in pixels. If the size is too small for selected scale grid will not be displayed.

5. Data Fields

All data fields placed onto the design layout are shown as frames. Such frame can be selected by clicking. To select several frames keep pressing Ctrl and click on them. Properties of the selected frame (or group selection) are shown in the Properties pane. Look for detailed description of them below.

5.1. General Data Field Properties

Data field properties are grouped into the following groups.

Appearance

BackgroundColor lets you choose the color for the background. E.g. white – to make the area beneath the data field in the resulting PDF invisible.

BlockProperties is a subgroup that contains block-level properties. They are described below.

Alignment is a text alignment (inherited, left, start, center, right, end, justified).

AlignmentLast is a text alignment applying only to the last line of the text block. It has the same set of values as the Alignment.

IndentationFirst, IndentationLast, IndentationLeft and IndentationRight lets setting the corresponding indent for the data field. They are corresponding to XSL-FO traits text-indent, last-line-end-indent, start-indent and end-indent accordingly.

LineFeed corresponds to XSL-FO linefeed-treatment property, defines the way of line feed characters handling. Displaying of this feature in designer area is not implemented.

Inherit sets this property to the value of the parent container;
TreatAsSpace forces the formatter to treat line feed character as a space;
Ignore lets the formatter ignore any line feed characters;
Preserve treats all line feed characters as line breaks;
TreatAsZeroWidthSpace forces the formatter to treat a line feed character as zero width space.

WrapOption specifies whether or not the text should be wrapped to fit the frame size.

Border allows specifying the border properties. It includes color (BorderColor), line style (BorderStyle) and line width (BorderWidth).

Orientation property is setting block orientation, it allows rotating data fields. This property is analogue of XSL-FO reference-orientation trait.

VerticalAlignment specifies vertical alignment. Values meanings are listed below:

Auto sets vertical alignment to default value or to value of the parent container;
Before sets vertical alignment to the top of the area;
Center sets vertical alignment to the center of the area;
After sets vertical alignment to the bottom of the area;

Data

InnerText is a subgroup that contains properties that concern to the content of the field.

Comment is a description for the field. It is used to generate comment in the resulting stylesheet. Also it can be helpful for navigating the document structure.

DataTypespecifies data type stored in XML source. This property provides necessary information for formatting of the text from XML source. Currently only Date and Text types are supported.

DataFormat contains code that defines additional field formatting. For more details see sub-section 5.6. Data Fields Additional Formatting (Date/Time Only), also there is a table of available codes. Application does not provide the list of codes and does not check their validity. If an incorrect value is set for this property the default code (0) will be used for formatting.

Text is a design time text to be displayed at the layout. It has special meaning for some fields (see below description of the Image specific properties and special fields).

TextProperties contains properties for text formatting inside the block.

Font is font properties (font family, size, styles, direction, etc).

ForeColor is a color of field’s text.

XPathValue is an XPath expression that returns a value from a node set defined in the Pattern.

Patternis an XPath expression that selects an XML branch (node set).

Caution! If a user manually modifies an XPath expression in Pattern property he should make sure that it is correct and evaluated to some XML node-set and this node-set is a descendant of XML node evaluated with page Pattern property.

Test contains the XPath expression that defines condition to show or not the content.

Coordinates

Locationisthecoordinates of the data field frame’s top left corner.

Size is width and height of the data field frame. The value for these properties can be using following measure units: points (pt), pixels (px), inches (in), centimeters (cm), millimeters (mm). If no measure unit is specified the default one (points) is used.

5.2. Checkbox Specific Properties

Appearance

FontSize defines the font size of the check mark inside of the field.

Data

CheckType defines the checkbox style.

5.3. Image Specific Properties

Data

XPathValue is not used by default for a newly created field. In order to extract the image URI from the source XML using XPath a user should manually edit ImageUrl property. For more details see description and example below.

ImageUrl is an URL or a local path to the image file. By default it is a static path to image. It can be changed by clicking (…) button (this will bring browse dialog). In case user wants to use XPathValue to extract a part of the URI from XML, he has to use the tag {xpath-value} inside ImageUrl property.

Example

Suppose that we have some storage of employee’s photos in a shared folder of our intranet server. All files are named in the following way:

http://intranet-server.com/photo/XXXX.jpg,

Where “XXXX” is a serial number from 1 to 9999

Suppose that we have the following XML fragment describing every employee:

<recordid="1">

</record>

<recordid="2">

<name>Adam Smith</name>

</record>

</employees>

We should use the following values to render images in our document

Property	Value
ImageUrl	http://intranet-server.com/photo/{xpath-value}.jpg
XPathValue	@id
Pattern	records/record

5.4. Barcode Specific Properties

Appearance

Module is the width of the narrowest stripe in a barcode. Use this parameter to control the width of the barcode.

Data

Type is the barcode type. Available types of barcodes to render are EAN8, EAN13, UPC-A, UPC-E, Interleaved 2 of 5, Code 3 of 9, Codabar, Code128, Australian Post 4-state code. Please, keep in mind that no validation of XPath expression result to barcode specification rules is available.

5.5. Special Fields

The application makes possible to insert a special field into the project. On the step of generating XSL stylesheet they will be transformed into XSL parameters. It enables a user to set some values at XSL transformation stage.

Special fields are described in format-plugin.xml (it is created in %ProgramFiles%/VisualXSL/XSL subfolder of the application folder). Just drag and drop XML node from XML tree view to the layout to insert the one. Change the value of XPathValue property in its object properties to the name of a desired field (see list below). The name should be specified with preceding symbol “$”.

Field name	Description	Default value
PrintDate	Date when project is transformed last time	Current date
CreateDate	Date when project is created	None
AuthorName	Name of the project author	None
CompanyName	Name of the author’s company	None

A user can also insert the custom special field, which will be later transformed into stylesheet parameter. In this case XPathValue should be set to “$<special-name>”. Where special-name is CName (satisfies standard XSL demands of variable naming). Set default value of the parameter by changing Text property.

5.6. Data Fields Additional Formatting

The application makes possible to apply additional formatting to the field content. Currently only different date formats are implemented. The date value in source XML file should be properly specified in ISO8601 format (yyyy-mm-ddThh:mm:ss:mmm) or ODBC canonical format (yyyy-mm-dd hh:mi:ss).

Select field containing correct date value for applying formatting. Switch to its object properties; choose Datevalue for DataType property. Then specify format code for DataFormatproperty (all supported format codes listed in the table below). To refresh the designer area (and see updated formatting of data field) click Refresh button.

Date format codes

Code		Description
without century	with century	Description
0 or 100		Default mon dd yyyy hh:miAM (or PM)
1	101	USA mm/dd/yy
2	102	ANSI yy.mm.dd
3	103	British/French dd/mm/yy
4	104	German dd.mm.yy
5	105	Italian dd-mm-yy
6	106	dd mon yy
7	107	Mon dd, yy
8	108	hh:mm:ss
9 or 109		Default + milliseconds mon dd yyyy hh:mi:ss:mmmAM (or PM)
10	110	USA mm-dd-yy
11	111	JAPAN yy/mm/dd
12	112	ISO yymmdd
13 or 113		Europe default + milliseconds dd mon yyyy hh:mm:ss:mmm(24h)
14	114	- hh:mi:ss:mmm(24h)
20 or 120		ODBC canonical yyyy-mm-dd hh:mi:ss(24h)
21 or 121		ODBC canonical (with milliseconds) yyyy-mm-dd hh:mi:ss.mmm(24h)
-	126	ISO8601 yyyy-mm-ddThh:mm:ss:mmm(no spaces)

Milliseconds (if they are specified in XML data for a field) will not be rendered after the layout being refreshed, but will be rendered in the resulting PDF document.

5.7. Address Label Wizard

The application provides wizard for adding address labels to the document. The resulting label will be aligned vertically to the bottom of the label and will consist of 4 or 5 address lines. There are three areas in the wizard dialog (see the figure 5.7.1). The first one is a tree representing the first element from the XML source file (further XML tree). The second is a group of textboxes for address parts. And the third one (placed right down the second one) is a sort of preview for the address label. A user can add data from XML tree to textboxes by double click on tree node, by dragging nodes into or by clicking Add >> button.

Fig. 5.7.1 Address Block Wizard

In a case a user clicks Add >> button data will be added to the highlighted textbox. When a user tries to add new data to the textbox that already contains some text, the new data will replace the previous one. And vice versa, by clicking << Rem button the textbox can be cleared. The data added from XML tree in such a way will be inserted into the resulting document dynamically. Also a user can type in some static data if needed.

The application forms the PostNet barcode from 3 last textboxes. It assumes that all data typed into them are numeric, so please make sure that XML data represents a proper number for post code.

Note. Currently application has no option to specify fonts to be used in document formatting. So a user should manually edit the configuration file for XEP and add a section to describe PostNet True Type font.

Example

Let’s assume that XEPWin is installed to “C:\Program Files\RenderX\XEPWin” folder.

Open XEP.xml file from subfolder “xep”.
Find XML element <font-group/> with attribute @label=”Windows TrueType”.
Add the following text inside the found element:

<font-familyname="IDAutomationPOSTNET"embed="true">

<font>

<font-data ttf="IDAutomationPOSTNET.ttf"/>

</font>

</font-family>

That makes possible for XEP formatter to use True Type font for Postnet barcodes rendering.

5.8. Paragraph Block

The application has an ability to put some paragraphs with different formatting properties into one block-container. Example of such a block-container is an address block. The main advantage of such a feature is possibility to prepare text blocks using XML data of variable length (so there is no possibility to leave blank for a data field). Also it may be helpful when different formatting should be applied to different parts of one paragraph.

Initially, when a user adds a paragraph block to the project (from menu Data -> Add Paragraph menu) it has no paragraphs and will not be rendered in the preview or the result document. A user should select Edit –> Edit Para from the menu to add paragraph or to edit existing ones inside the block. This will bring up the following view:

Fig. 5.8.1 Empty paragraph block added to the layout

A user can type in a static text there, drag and drop nodes with data from XML tree or type the XPath expression inside curly brackets. To apply formatting to the text, select it and click the appropriate toolbar button.

Fig. 5.8.2 The paragraph block is being edited. Some data fields and static text have been added

To finish editing of the paragraph select Edit -> Finish Editing Para or click toolbar button with cross. Formatting of the text is limited by control possibilities that’s why most of XSL-FO features are inaccessible (that situation will be improved in the next application version).

Caution! Before editing a paragraph block a user should ensure that the whole block on the design layout is visible to them. In other case, a user will have to scroll design layout manually to see all text being edited. Undo/redo is not supported while user is editing the paragraph block.

6. How To

6.1. How to Create Your Own Project

To create a new project:

Run the application with one of the above-mentioned methods.
If a previous project loaded automatically on start up, press New Project button on the toolbar, menu File → New Project or press simultaneously Ctrl + N.
Use menu File →Open Source XML or press Ctrl + X to select an XML file (it must be a well formed XML document). After the XML file is successfully loaded its schema will be shown in the XML tree view.
Click on empty space of the page in Layout to set the required properties in Object Properties:
- Specify Pattern property in a property grid. Pattern property should contain valid XPath of an XML element with current page data. Note: the XPath expression is case sensitive.
- Set BackgroundPath property value to the valid full path to the previously prepared PDF file. That contains a form that you want to fill with data from the XML. It can be easily done by clicking button (…).
- You can also set an alternative value to RasterizedPathproperty. Set it to the valid full path of a previously prepared raster file with a form you want to fill with data from the XML.
Note. Currently application supports the following raster image formats: PNG, TIFF, JPG, GIF (for more details, see XEP reference).

6.2. How to Create Multi-Page Form Project

The easiest way to create a multi-page project is to follow these steps:

Create a new project.

Select an XML file using menu File →Open Source XML or by pressing Ctrl + X.
In the object properties set BackgroundPath property to a full path of the required multi-page PDF. You can click a button (...) to use the open file dialog. After a PDF background is selected you will see the first page rendered in the layout area and a full path to a rasterized version will appear in object properties in RasterizedPath property. Also the application creates PDF for every page of selected one and produces rasterized version of them. Files are created in the project folder and named: PdfFileNameXXXX.pdf (PdfFileNameXXXX.png), where XXXX is a page number starting from 0001. Those files are set as backgrounds for the corresponding pages.

Fig. 6.2.1 Adding a new page to the project
If you do not have a PDF file with a form, but a TIFF file (or other supported graphics format) instead, you may set its path to RasterizedPath property manually.
Now you can add and adjust data fields for this page (see “6.3. How to Add Data Fields” section).
When all data fields added and properly adjusted click the toolbar combobox with the active page number. You will see currently available pages numbers so there is a command New Page at the bottom of the drop down list. Click it every time you need to add a new page to the project or use menu Edit →Add Page menu or press Alt + P keys combination.
To remove the currently selected page use menu Edit →Remove Page menu or key Alt + R keys combination.

6.3. How to Add Data Fields

After the project is created data fields can be added, modified or removed.

Data field is a frame on the Layout. It is rendered in the resulting document “dynamically” getting data from the XML data file.

Follow these steps to add new data fields:

Select a node in the XML Tree View. The data stored in this node will be rendered in the resulting form.
Press Add to Layout tool bar button to add a field with selected XML node to the design layout. Also you may simply drag a selected tree node and drop it on the Layout. You will see a new frame that has appeared in the form layout. Optionally, you can drag item holding right mouse button. In that case after releasing mouse button in the desired place on the layout you can choose data field from context menu.

Fig. 6.3.1 Dragging XML node onto the design layout
You can now select a newly added frame by left clicking on it and set a desired position by dragging it over the layout area.
You can resize the frame by clicking on a small rectangle in the lower corner of the frame and dragging it.
Additional properties can be modified for a selected data field in the Properties pane.
After all data fields added and aligned, you can generate a stylesheet and/or a PDF document.
During the PDF rendering such field will be filled up with data from XML file.

See detailed properties description in the “General Data field properties description”.

6.4. How to Fill In Preprinted Forms with Data

In order to fill in paper forms with data fields follow these steps:

- Do the following:
- Create your own project in VisualXSL.
- Scan to a raster image preprinted form, set it as the background or use an existing PDF instead.
- Add data fields.
- Add all necessary pages.
- Use menu Options → Preferences, clear the checkbox Render Form Background.
- Save .VXL file;
Now you can generate your PDF with data fields only and print it in your preprinted form(s).
To restore the background rendering in the destination document, the checkbox should be checked back.

6.5. How to Use Log Pane

The log pane allows tracing the formatting progress. It contains all the messages from the XEP formatting engine. The messages are highlighted in the following way:

errors – red;
warnings – blue;
others - gray.

Some of them contain clickable links (warnings and errors concerning incorrect XPath expression in the data field). You can click them to go to the problematic object.

Fig. 6.5.1 Warnings are marked blue in log pane

It will be of use to take a look at the log after every document formatting. It is highly important if the document is not generated successfully because the log can show the reason.

6.6. How to Create PDF/PS Documents with VisualXSL

After the project is created and all necessary data fields

Download Now!

Visual-XSL (VisualXSL) User Guide

Conditional Rendering

XPath Validation

Docking Windows

Print XML Data on Preprinted Form

Generation of Fillable PDF Form

2.2. How to Install VisualXSL

4.1. Application Panes and What They Are Intended For

4.2. Menus and Toolbars

Data operations

Other operations

Rendering

Layout Grid

Appearance

Data

5.2. Checkbox Specific Properties

Appearance

Data

5.3. Image Specific Properties

Data

5.4. Barcode Specific Properties

Appearance

Data

5.5. Special Fields

Date format codes

6.3. How to Add Data Fields

6.4. How to Fill In Preprinted Forms with Data

6.5. How to Use Log Pane

6.6. How to Create PDF/PS Documents with VisualXSL