Preferences

The menu Preferences contains settings for the layout and the application:

General

On the first card, General, you can set the path to the Initial layout root directory (for layout files and XML files) and the path to the Default image base directory (for images). Also you can set the Default XSL base path where all XSL and XSL-FO output will be stored. XSLfast will refer to these settings in the layout creation.

Path mode: The relative path mode indicates that all files currently used (images, templates, etc) will be saved relative to the XSLfast installation directory (e.g. ../input/mylayout.xsf). The absolute path mode indicates that the absolute path name will be saved with the layout (e.g. C/Program Files/XSLfast/input/mylayout.xsf).

Please note: The absolute path mode may lead to problems if the layouts are used on another machine with a different file structure.

As described above, there is a small wizard at the startup of XSLfast which offers you to open a new file, an existing one or one of those layout files that were recently modified. If you don’t want this wizard to open every time you start XSLfast or open a new layout, unselect the check box Show startup wizard.

Usually a layout will require an XML source, as we said above, but also there will be layouts without the need of one. For your convenience it is possible to set XSLfast to ask you for an XML source every time you open a new layout with the function Disable layouts without XML or to turn this function off if you unselect the check box.

The function Track all changes as separate versions of layouts allows you, to keep the original layout unchanged while performing changes on it. All changes will be saved as separate, independent file versions the next time you save the layout. The new files will be saved in the same folder as the original file and will receive the extension _v1, _v2 and so on in the file name (e.g. from the original file name Invoice.xsf to Invoice_v1.xsf and so on).

Attention: A separate layout version is saved but the new file is not automatically opened. The original file stays active. If you want to save the original file without an extension, use the function Save as or turn the function Track all changes as separate versions of layouts off.

You will need some external tools for the output: Acrobat Reader (to view the resulting PDF file), text editor (to view and maybe edit the XML file or template files) and XSL formatter (if that is your Renderer). The HTML browser is needed to display the help files of XSLfast. Please set the paths to the corresponding start files.

View Options

If you like working with a grid, the index card View Options gives you the chance to set it up and more:

Enter the grid size in pixel in the field Grid size.

The checkboxes Snap on grid and Show grid give you the opportunity to display or hide the grid and to snap the elements on it.

Other properties, which can be set on this index card:

The function Enable preview of fonts in font list box means that the list box for fonts that you see on the sheet when you put a text frame on it shows the name of the fonts in the corresponding font so you can see the look of the font right away:

If the list box is unchecked, the font names are displayed in a standard font:

The check box Show layout options in status bar displays the output format and the current Renderer in the lower right corner of the layout window.

On click, you can change it:

If you have more than one Renderer installed, you can switch between them here.

This function also controls if you see the current coordinates of your mouse cursor in the lower left corner (see chapter Menu bar).

With the check box Use simple filter dialog in inspector you specify if you want to see the grouping assistant if you need to group a frame:

or if you just simply want to enter the grouping manually in the inspector window. The Grouping option is not available in the context menu with this setting. This view is rather recommended for more experienced users.

If the option Contour object movement is unchecked, e.g. a text element, which is currently selected, shows a tab with the element type and the level it belongs to. An element, which is currently not selected, will show no means of identification:

With this function active, the element will display not the tab but the element type and also the level it belongs to inside the element:

When dragging frames, the background is sometimes covered by the frame, which makes it hard to place the frame exactly in the desired spot. If you select the check box Transparent while dragging, all frames are semitransparent and allow seeing the background while they are dragged over the sheet.

The next four check boxes allow you to hide or display four indicators:

Of course, all indicators can be active at the same time:

Use advanced sort wizard means that the dialog window for sorting is called by the Sort function in the inspector window, otherwise you need to enter the sort criteria by hand.

If you want to give your tables more than two alternating colors, check the check box Use advanced alternate colors wizard. If this is unchecked, you can only assign two alternating colors with the function in the inspector window.

If you check the function Show XML in alphabetical order, the nodes and their contents in the XML tree are sorted alphabetically in the XML window while keeping their general structure:

Not sorted Sorted

This function can be useful if you work with intricate XML sources with many nodes and deep nesting.

The function Length of History in XPath expressions refers to the "If-Condition" builder and controls the number of XPath expressions, which are saved during a session. This number of used XPath expressions can be viewed and reselected in a list box. The "If-Condition" builder is described later in this manual. Remove all entries in the history with the button "Clear history".

XSLfast offers you to use four different units of measures in your layout. These measures can be: points (pt), millimeters (mm), centimeters (cm) and inches (in). By default all these measures are being converted into the points (pt) in generated XSL file.

Due to the calculation from e.g. mm/inches into pt, there can be a lot of decimals. The Default precision specifies how many decimals should be displayed in the entry field in the inspector window.

Attention: After you changed the precision value, you need to restart the application to apply the setting.

Choose the precision you need to be applied in your layout in Default precision field:

Note: Minimum precision is 2 decimals and maximum precision is 15 decimals.

The function Default System Font allows you to specify the font, which is used by default for the XML tree in your layout. Click the button "Change" to select another font:

Select the desired font, specify size and style and click "OK". The application will now use this font everywhere in XSLfast, also in the display of the XML tree.

Paper size setup

These functions help you define the measures of your working sheet.

Choose a page format from the combo box Size. It offers you DIN A3, A4, A5, A6, also the formats B5, US Letter, US Legal and Tabloid and the opportunity to enter custom sizes. If you choose custom, enter the size in the fields Width and Height manually.

You can alter the Orientation of your working sheet with the corresponding radio button into Portrait and Landscape.

Paper margins are boundary lines and frame the print space of your sheet where all elements should be placed. Margins are marked by grey lines and can be sized with the entry fields here or dragged with the mouse. By default, they are set to 10pt.

Regions are areas on your sheet, which have special properties. They are located at the top, the bottom, the right and the left of the sheet, indicated by a blue line and refer to the paper margins. You can specify their size with the entry fields here or by dragging the blue lines on the sheet; by default, the region size is set to 28pt. All elements placed in these regions will be repeated on every page of the resulting document. This also applies for elements only touching a region, as explained above.

Pick your desired unit of measure from the list box Unit of Measure. Choose between millimeters, centimeters, inches and points.

XSD/DTD settings

Some special characters cannot be entered as plain text in XSLfast but must be defined as an entity. If you want to have your own custom entity descriptions added to the target XSL and XSL-FO files, activate the checkbox Enable custom entity descriptions and select the file containing the descriptions with the browser window. It is usually a simple text file with the extension .xfd where the required entities are listed (e.g. <!ENTITY euro "&#x20ac;"> which can be used to add the Euro sign (as &euro;)). This function allows you to add your own custom entity descriptions to the target XSL files and enhance the range of entities in XSLfast. A typical entity file could look like this:

<!ENTITY euro "&#x20ac;">

<!DOCTYPE xml [<!ENTITY pound "&#163;">]>

All entities can be listed this way.

Enable custom namespaces is used e.g. for Java namespaces or your custom XSLT engine extensions like Saxon or MS XSLT component. This is typically a simple text file with the extension .xfn. Custom namespaces are used to add custom functions like Java mathematical functions, and custom elements inside XSL, like Saxon variables. Just a simple example is xmlns:saxon="http://icl.com/saxon". A typical namespace file could look like this:

<xmlns:jcat="http://jcatalog.com/jCatalog">

<xmlns:xslfast="http://jcatalog.com/XSLfast">

<xsl:stylesheet xmlns:date="http://www.jclark.com/xt/java/java.util.Date">

All namespaces can be listed this way.

The check box Omit comments and entity descriptions in XML tree makes sure that comments and entity descriptions contained in the XML file are not displayed in the tree structure.

The function Do not bind layout to top node allows to select the root node "/" in the layout. This root node can be used as a general node to support the creation of layouts with different XML files containing different root nodes. If you need to specify an alternative XML root XSLfast offers you to not automatically bind the layout to the top node.

Example 1: The XML tree is bound to the top node:

Example 2: The XML tree is not bound to the top node:

Apply your modifications with the button "OK" or abort with the button "Cancel". The settings are applied right away.

XSL output settings

XSLfast supports some custom extensions currently available for particular XSLT engines; here you can switch on or switch off Saxon optimizations in the XSL output produced by XSLfast. Activate this checkbox if you are planning to use XSL with Saxon. Keep the checkbox Use Saxon extensions deactivated if you plan to use non-Java XSLT engines like Microsoft MS XSLT.

If you need to use lines which are not orthogonal in your layout, check the check box Use SVG graphics for lines. If this check box is not active, lines are created by FO-Blocks, which will lead to problems with non-vertical or non-horizontal lines.

Activate the check box Include Java namespaces (possible problems with non-Java-XSLT systems) if you want to use Java namespaces. Namespaces make static functions e.g. from the Math library available in XSLfast.

Attention: There may be problems using the XSL output with Non-Java processors if you activate this check box.

Example 1: Java namespaces are not included in the layout. In the beginning of the XSL file you can see strings such as these:

<xsl:stylesheet xmlns:fox="http://xml.apache.org/fop/extensions" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.1" xmlns:date="http://exslt.org/dates-and-times" xmlns:saxon="http://icl.com/saxon" extension-element-prefixes="saxon" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

Java namespaces are included in the layout:

<xsl:stylesheet xmlns:fox="http://xml.apache.org/fop/extensions" xmlns:Integer="java.lang.Object.Integer" xmlns:Calendar="java.util.Calendar" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.1" xmlns:saxon="http://icl.com/saxon" extension-element-prefixes="saxon" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:Math="java.lang.Math" xmlns:Double="java.lang.Object.Double" xmlns:Date="java.util.Date" xmlns:String="java.lang.String" xmlns:date="http://exslt.org/dates-and-times" xmlns:Locale="java.util.Locale">

xmlns:Integer, xmlns:Calendar, xmlns:Math, xmlns:Double, xmlns:Date, xmlns:String, xmlns:Locale - these are namespaces, which can be used in layout.

Example 2: This example will show how to print current date and time using Java namespaces.

Java-Namespaces are included in the layout. Choose the menu Preview -> Layout settings -> Additional templates and press the "Edit" button opposite to Internal variables title. This will open the Edit internal variables window.

Enter <xsl:variable name="rightNow" select="Date:new()" />. This phrase means that you declare a variable named rightNow and call the function new () from the Java class Date:

Put an XSL Code element on the page, open the text editor by double clicking the element and enter the call for the variable (<xsl:value-of select="$rightNow" />) to generate its value, which was declared in the Internal variables field:

Generate the layout. The result of the specifications described above will be:

The checkbox Prefer CYMK color space if possible has the effect that you will be offered to enter CMYK color values in the process of creating the layout which support the printing process of the file.

Please note: The CMYK colors values that you enter in the fields may differ from the displayed colors.

XSLfast offers you to use four different units of measures in your layout. These measures can be: points (pt), millimeters (mm), centimeters (cm) and inches (in). By default all these measures are converted internally into points (pt) in the generated XSL file. To avoid converting the unit of measures used in the layout, XSLfast offers you to use the selected unit of measures in the XSL output: Use selected unit of measures in XSL output means that the currently selected unit of measure (mm, pt, inch, cm) is kept for the XSL output. If this option is unchecked, all units of measure are converted into pt in the XSL output.

If you use the function Smart vertical alignments (FOP specific), XSLfast puts a little top padding in text elements, depending on the font size. This is helpful because FOP does not support top, middle or bottom alignment for text.

Example: You want to have text of different size in one text frame. With the smart vertical alignment it could look like this:

If you turn the function on, it changes into this:

A top padding has been automatically set so that the bigger text is not stuck to the top rim of the element.

XSLfast offers the possibility to choose the encoding which the XSL output should have, select the encoding from the list box XSL output encoding.

Default settings

XSLfast offers you to make default settings for all elements. This feature is useful if you need to create several identical objects with the same values for different parameters. The folder in the list on the left contains more cards for that purpose:

All functions and features for all the elements can be seen here. Settings made here are considered as default and are saved within the application. If you want to restore the original settings, click the button "Restore default settings".

Select the element you need from the tree on the left. Then set the parameters values for it in the inspector window on the left.

There is a special setting for each element, which is the check box Uneditable. If you check this check box in Default settings, the settings for these elements are locked and cannot be changed; the element can also not be moved or deleted any more. But each element has its own Uneditable check box in the inspector window so the lock can be deactivated for each element separately on the sheet.

The settings you make in the folder Default Settings itself refer to all elements you create after you made this setting.

After changing one or more parameters for a component you can easily return to default values by pressing the button on the right bottom corner of the inspector.

All element functions are described for each element a little later in this manual.

All settings you make in Preferences will be available for the next sessions.