Home Page FO Designer user guide. XSL-FO tool for Oracle APEX and the Java[TM] platform
                                                    FO Designer guide
                                                  • First steps
                                                  • Introduction
                                                  • The user interface
                                                  • Working with the interface
                                                  • Structure of the template
                                                  • Executing the template to create PDF files
                                                  • Learn by doing
                                                  • The invoice IDOC example
                                                  • The Group by example
                                                  • The two columns example
                                                  • Barcodes
                                                  • Charts
                                                  • The running totals example
                                                  • Interactive forms
                                                  • Flavours
                                                  • The base template
                                                  • Long texts and HTML fields
                                                  • The memo field explained
                                                  • Advanced functionalities
                                                  • FOP Could Server
                                                  • Migration of existing XSL-FO files
                                                  • FAQS
                                                  • Troubleshooting
                                                  • Licenses
                                                  • FAQS

                                                    21. FAQS

                                                    How to prevent NaN values in numeric fields

                                                    If you are using the format-number function or another numeric function on a non numeric field (or a numeric field that is empty) you will get the value NaN in your report. If you want to remove the NaN values you can use the j4lext:replaceStr function to replace them with an empty string.

                                                    For example if your current area is based on a XML node that has a child node called QUANTITY, which you want to format using the format-number function you can use the following xpath expression:

                                                    j4lext:replaceStr(format-number(QUANTITY, '##.0'),'NaN',' ')

                                                    this would prevent the NaN values in case the QUANTITY node is empty (empty string). Note however if you use functions with the j4lext prefix you must use the J4L FOP server, if you use another XSL-FO processor these functions are not available.

                                                    How to enable the designer console

                                                    Edit the file fodesigner.ini in the installation directory, add the line





                                                    Restart the designer, now the designer console will be shown, where you can eventually see error messages.

                                                    How to debug Oracle APEX requests

                                                    If you are using Oracle APEX and:

                                                    • the report is working in the designer
                                                    • but not in Oracle APEX this is what you need to check:
                                                      • make sure the XSL-FO file has encoding UTF-8, depending on your APEX installation you might need to change it to ANSI.
                                                      • If you using Oracle Data Rest Services as print server, make sure the „APEX encoding“ has been disabled in the designer
                                                      • If none of the above helps, try removing fields from the report one by one until the one causing the problem can be found. Look first at field having potential issues like have international characters in the text.
                                                      • the last alternative is installing the J4L FOP Server (http://www.java4less.com/apache/fop.php), for debugging purposes. The server will allow you to log the APEX request (see  http://www.java4less.com/apache/fop.php?info=faq#debug ) and find out where the problem is.

                                                    How to enable Oracle APEX logging on Glassfish

                                                    You can enable 2 types of loggings:
                                                    1.  In the ORDS configuration file default.xml set this value:

                                                      <entry key="debug.debugger">true</entry>
                                                    2. On the Glassfish administration console → Configurations → server-config → Logger settings, add the entry „oracle.dbtools“ and set the desired log level.

                                                      The log file will located in the directory glassfish\domains\yourdomain\logs

                                                    How to create a user defined XPath function

                                                    If you want to create your own function the following example shows how to do it:

                                                    • Create a Java class with your favorite development tool. The class should contain your static method, for example, we will create a function called toUpperCase

                                                      public class
                                                      Functions {

                                                      /**this function converts a string to upper case

                                                    public static
                                                    String toUpperCase(String input) { return input.toUpperCase();


                                                    • Compile the java class into a jar file. The file must be called userfunctions.jar and you have to copy it to the installation directory of the J4L FO Designer.
                                                    • Restart the J4L FO Designer
                                                    • In the properties of your template you must enter the Java class name in the User functions class field, see highlighted field in the screenshot, then close and reopen the report in the editor.

                                                    • Now you can use your function in the XPath editor since the function will appear in the list of available functions:

                                                    Note: When you insert the function in the output, the function name will have the prefix j4luserext:

                                                    How to add new fonts to J4L FO Designer

                                                    J4L FO Designer supports the five built-in PDF base fonts (Helvetica, Times, Courier, Symbol and Zapfdingbats) which must be supported by any PDF reader.

                                                    However you can add new fonts using a TTF file in the following way:

                                                    1. Open the FO Designer and select Tools -> TTF Font tool

                                                      the Input File must point to your TTF file and the Output XML file to the output metrics file (you can select any name you like).

                                                    2. Click on „Create XML“ and close the dialog.
                                                    3. Edit the created XML metrics file and make sure the font-name element has the same value as the node. For example:

                                                      <font- metrics
                                                      metrics-version="2" type="TYPE0">
                                                      Sans MS</font-name>
                                                      Sans MS</family-name>

                                                    4. Now you have to tell J4L FO Designer to use the XML metrics file you created. You do this by editing the file located in the root J4L FO Designer directory.

                                                      You have to add these lines:

                                                      <font metrics-url="file:///c:/yourdirectory/comic.xml" kerning="yes" embed-url="file:///C:/windows/fonts/comic.ttf">
                                                      <font-triplet name="Comic Sans MS" style="normal" weight="normal"/> </font>

                                                      note you have to change the the embed-url, the metrics-url and the name values. The name must be the same family-name value from step 3.
                                                    5. Now you can start the J4L FO Designer and open the font dialog of any field, the new font will be available in the font selection dialog:

                                                      Note about microsoft TTF files

                                                      If you want to know if you may use microsoft TTF files in your PDF Document you need to:
                                                      1. Download the Microsoft Font properties extension (https://www.microsoft.com/en-us/Typography/TrueTypeProperty21.aspx)
                                                      2. Install the software
                                                      3. Located the TTF File you want to use and select right mouse click, properties. If the properties extension has been installed you will see a new tab called „Embedding“ where you can see the license type for embedding the fonts in documents.

                                                    How to add new fonts to Oracle ORDS

                                                    Once you added the new fonts to the designer as explained in the previous FAQ, the next step is adding it to the runtime server. This section will show how to add new fonts to Oracle ORDS.

                                                    • Edit the ORDS configuration file default.xml , add the following line:

                                                      <entry key="fop.configfile">C:\ords\ords\fopUserConfig.xml</entry>

                                                      Replace the bold text with your own directory (place the fopUserConfig.xml where you like)
                                                    • In the fopUserConfig.xml file (which you can copy from the FO Designer installation directory) you might have an entry like this:

                                                      <font metrics-url="file:///C://fonts//verdana.xml" kerning="yes" embed-url="file:///C://fonts//verdana.ttf">   
                                                      <font-triplet name="Verdana" style="normal" weight="normal"/>        

                                                    This would add Verdana font support to your reports.

                                                    How does the designer deal with namespaces

                                                    The xsl-fo file generated by the designer is not namespace aware. This means the XML to PDF conversion will fail in Apache FOP if your input file contains namespace information. In order to avoid this error you have to:

                                                    • In the designer activate the namescape removal. This has to be don ein the windows-> preferences dialog .
                                                    • At runtime you use:
                                                      • either our servlet which supports the REMOVENS parameter
                                                      • or our com.java4less.xreport.fop.FOProcessor class whose process() method supports the removeNS parameter that must be set to true.

                                                    How does support for international character sets work

                                                    You can use J4L FO Designer with any language, the following features support internationalization:

                                                    • You can add new fonts that support your language.
                                                    • The XSL-FO files generated by the designer use UTF-8 encoding, so any national character can be used.
                                                    • At runtime UTF-8 encoding is recommended however the runtime module will look into the XML preamble to determine the correct encoding.

                                                    How to add my own xslfo attributes to the fields

                                                    In most cases FO Designer will generate the xsl-fo output so you do not have to worry about the details of the language. However if you are familiar with xsl-fo and you want to add some additional attributes to the fo:blocks created by FO Designer you can use the property shown below:

                                                    How to add page numbers and page total count

                                                    You can add page numbers and page total counts in the page header and page footer areas using the following value for the field:

                                                    Page <fo:page-number></fo:page-number> of <fo:page-number-citation ref-id='last-page'/>

                                                    the text <fo:page-number></fo:page-number> stands for the current page number and the text <fo:page-number-citationref-id='last-page'/> will be replaced with the total page count.