20. Migration of existing XSL-FO files

This section describes how to migrate existing XSL-FO files to the FO Designer. Note we explicitelly use the word migrate to remark that the FO Designer is not an XSLT editor, therefore it is not posible to import XSL-FO files 1 to 1. Instead we provide a tool that will preserve most of the layout of your existing report and most of the style (fonts, colors and alignments). However you will still need to do some fine adjustments.


We will improve the tool over the next releases, contact us if you have some files you cannot migrate.

Limitations

You will get the best result will the miigration tool if:

• you only have a limited amount of XSLT code in the file
• and the FOP formating code has been structured in form of FO tables, rows and cells.
  

Some current limitation in the tool today are:

• The supported XSLT elements are: variable, attribute, attribute-set, use-attribute-sets, apply-templates, template, stylesheet, with-param, param , choose, when, otherwise, if, key, call-template, output, value-of, comment, decimal-format and for-each.
• The supported FOP elements are: block, block-container, external-graphic, flow, inline, inline-container, layout-master-set, marker, retrieve-marker, page-sequence, page-sequence-master, region-body, region-after, region-before, root, simple-page-master, static-content, table, table-header, table-body, table-row, table-column and table-cell.
• The supported style attributes are: text-align, font-size, font-weight (bold), font-family, font-style (italic), color, background-color, text-decoration (underline). These are supported for block, block-container, inline and inline-container.
• The supported position attributes are: margin-left, margin-top, margin-right, width, height, position, top, left and right.
• Only one simple page master is supported.
  

Migration step by step

The migration tool is located in the File menu:




after selecting it, the open file dialog will shown. Make sure you select a valid xsl-fo file:

• the file must be UTF-8 encoded
• a valid XSL-FO file starts with
  
  <?xml version="1.0" encoding="UTF-8"?>
  <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format"  ....
  ......
  <fo:root>
  .....
  
  
• and contains both XSLT (xsl) and FOP (fo) elements, as in the lines above.
  

If the file is valid the system will propose the creation of a FO Designer report. On the right hand side the report areas will be displayed (marked below with red squares) and the fields within the areas:





If you double click on the output area on the right ("detail area 2"), the corresponding source element in the input file will be selected on the left handside window "Table width..." in this case.




As rule of thumb (there are some exceptions), the tool will create a new output area for each one of these input elements:

• Table element. For example:
  
  <fo:table ....
  
  
• for-each element. For example:
  
  <xsl:for-each select="OrderDetail/ListOfItemDetail/ItemDetail">
  
  
• apply-templates element. for example:
  
  <xsl:apply-templates select="/LIST/S_UNB/S_UNH" />

The same concept applies for output fields which will be mapped to input "value-of":

Use now the "Create report" button

this will create a new project and the report template.

the next step is checking whether the Xpath's of the areas are correct. Note for this you need to have an understanding of how the designer works. If you are completely new to the FO Designer please have a look at our "Learn by doing" chapter in the main help page.

Afterwards check the individual XPath of th fields.

In the project there will be also a file called migrationLog.html. In this file you can see what the designer was able to migrate and how. Look for the OUTPUT lines with yellow or red background color and whose text is "IGNORING" or "ERROR". These will give you a hint on what you need to manually correct in the report.

The final step would be running the report.
For this:

• copy a test XML file to the "XML test fles" folder of the project
  
• select the file in the "settings" tab
  
• and click the "PDF" button (1 below) in the tool bar.

In case the output is not the expected one, use the trace button (2 below). Please refer to the chapter "Structure of the template -> How to analyze the report execution".