Table of Contents
List of Tables
FOP Editor is used to create PDF file from the input sources that are XSL:FO formatted. These input sources can be one of:
content of the FOP Editor applet and data from HTML form
XSL:FO parameter from browser's address bar - path to some XSL:FO file
XML+XSL parameters from browser's address bar - paths to some XML and XSL files
According this, FOP Editor is divided in two parts:
Java applet which is text editor with possibility for basic text formatting.
Enhydra application which is used to take parameters form applet or from address bar and to render PDF file.
PDF files are created using Apache Software Foundation's FOP tool (http://xml.apache.org/fop). FOP is a Java application that reads a formatting object tree and then turns it into a PDF document.
There are some requirements for using FOP Editor:
FOP Editor resources
FOP libraries
Web browser
Java plug-in
Adobe Acrobat Reader
FOP Editor resources consists of FOP Editor applet and FOP Servlet - Enhydra Application fopes. This servlet is just example servlet which helps to generate a PDF from input sources. User can develop his own servlet to generate more different PDF documents from this.
This FOP Editor is developed and tested with FOP version 0.20.4. so you should use this version or above. FOP jar files that are necessary for generating a PDF file are fop.jar, avalon-framework-cvs-20020806.jar and batik.jar so, these files have to be in CLASSPATH. If you use FOP Editor with fopes application, than you shouldn't setting up an additional environment parameters like CLASSPATH or similar. In fopes's internal classpath these files are included already.
Web browsers can be any browser that support Java applets.
FOP Editor applet is a swing Java applet so you have to use Java plug-in version 1.3 or above.
To install and run FOP Editor, first you have to add FOP Editor applet and fopes application to Enhydra Multiserver application.
FOP Editor applet consists of HTML files, applet class files and resources (gif and property files). To add applet to Enhydra Multiserver you have to set “Class Name” to org.enhydra.servlet.servlets.FileServerServlet and “DocRoot” to directory where are HTML files placed (see Enhydra Multiserver Help documentation). After that, you should to set connection and start this applet from Multiserver GUI. In FOP Editor applet DocRoot directory, there is index.html file which will be invoked by default when you call FOP Editor applet.
Adding a fopes to Enhydra Multiserver is similar like adding FOP Editor applet. It is only important to set appropriate port of application on exactly that port which is defined in HTML (see next section).
In all HTML files there are some predefined values for http address of Enhydra Application. These values are http://localhost:8011/ServletEditor.po. You should change localhost to name of computer where Web server is installed and 8011 to number of registrated port on which fopes application is running.
If you are using FopEditor.jar distributed with Enhydra5.1 (signed jar) cut, copy and paste functions in interaction with other applications and system should be enabled if you accept to trust the applet signed by the Enhydra Development Team.
If you want to be able to use cut, copy and paste functions in interaction with other applications and system, using the classes built from our source, you should to enable these Java permissions on your system. There are two ways to do this. In one of them, you have to copy the file .java.policy at your HOME directory (under Windows it will be c:\Documents and Settings\<user_name> ). You can copy this file from <FOPapplet_dir>/Misc directory.
Other way is to editing Java security file. Path to this file is <JRE>/lib/security/java.policy (for e.g. c:/Program Files/Java/J2re1.4.0/lib/security/java.policy). Following line has to be put:
permission java.awt.AWTPermission "accessClipboard", "access";
After that, applets are permitted to use system clipboard.
Like it is said before in Introduction, it is possible to generate PDF from FOP Editor applet or by submitting a parameters from address bar. If you run FOP Editor applet, you can generate PDF file if you click on “Generate PDF” button. In this case, whole contents of applet and all input fields form HTML form will be submitted.
Second way to generate PDF is to submit a XSL:FO file to fopes application. Example:
http://localhost:8011/ServletEditor.po?fo=c:\Examples\test.fo
Finally, third way to generate PDF is to submit XML and XSL file to fopes application. Example:
http://localhost:8011/ServletEditor.po?xml=c:\Examples\test.xml&xsl=c:\Examples\test.xsl
In <FOPapplet_dir>/Misc directory, there are some examples of .fo, .xml and .xsl files.
By default, FOP Editor supports following fonts: Helvetica, Courier and Times (with their variations - bold, italic and underline). Beside these fonts, it is possible to extend default setting to embed some other fonts. If you want to embed some other fonts you have to do two things:
Build XML font metric files - as it is described in FOP documentation (http://xml.apache.org/fop/fonts.html)
Edit userconfig.xml file
Fonts that you want to embed, have to be copied in <fopes_dir>/Config/Fonts directory. Similarly, XML font metric files have to be copied in <fopes_dir>/Config/XML directory.
To edit userconfig.xml file, you actually have to edit userconfig.xml.in file which resides in <fopes_dir>/input directory. In this file, there are two values that have to be modified - location of XML font metric file (metrics-file) and location of embed font (embed-file). You MUST NOT edit values for font-triplet parameters because these parameters are expected by FOP applet. After that, you have to build fopes application again.
Configuration file of fopes application (fopes.conf) has parameter UserConfigFilePath. This parameter helps to locate userconfig.xml file and it is automatically generated when fopes application is builds.
FOP editor applet is like any other text processor and it has a some standard functions. Text can be easily formatted using menubar and/or toolbar. The WEB Administrator can adjust content of menubar or toolbar through the property file, so some of Editor's functionality or even whole menubar and/or toolbar could be hidden from the user (which will be described in the next chapter).
Menubar consists of four menus: File, Edit, Format and Info.
File menu consists of three menu items: Open, Save and Close. These commands are standard, but one thing is different.Text which is stored ih these files is in the form of applet internal presentation.So,if you open this file with other application text will not be understandable. Files which are saved have extension .fap. Also,this goes to for file which you want to open.
Edit menu consists of three menu items: Cut, Copy and Paste. These commands are not standard. When you copy or cut some Editor-formatted text and then paste it to other location in Editor, you'll have the same formatted text at new location. Previous commands, in general, can't be used to copy some Editor-formatted text and then paste it into another application, nor to copy some text from other applications and then paste it to an Editor. To do so, user have to enable Java applet permission for using a system clipboard (as it is describe previous). After that user can paste text from other applications into FOP editor (whole inserted text will be formatted like the character before inserted text) and copy text from applet to other applications (which doesn't make sense, because text will not be copied as it is, but it will have the form of applet internal presentation).
Format menu is used to choose fonts (family, size and style). Three standard fonts are available: SansSerif (Helvetica), Monospaced (Courier) and Serif (Times Roman). There could be maximum 9 font sizes defined: 8, 10, 12, 14, 16, 18, 24, 36 and 48. Available styles are Bold, Italic and Underline. Different formatting can be applied to every part of the text.
Info menu consists of menu items Parameter Info and About. Parameter Info contains information of default values written in "main" property file and information of which property files are defined, by <PARAM> tags from HTML document, to be used by applet. About is standard about message box.
Toolbar contains shortcuts to the most using commands of FOP editor applet. It consists of buttons cut, copy and paste which have the same functionality as corresponding menu items. There are also corresponding toggled buttons for menu items Bold, Italic and Underline which is used for creating styles. Combo's on toolbar corresponds to menu items for choosing font family and size. There are also three buttons for aligning text (Left, Center and Right) which don't have corresponding menu items.
Table of Contents
Property files can adjust FOP editor's look and functionality. One of main task of the property file is to adjust Editor for different users - fully customizability of property files. Functionality of property files are divide into two separate property files: one (so called main), with the functionality of FOP editor's look, and other (so called language), with the definitions of labels.
FOP editor applet is the same for all users, but WEB administrator (or some responsible person) can put one property file for some user group and other file for other users. FOP editor is fully customizable which is mean that responsible person may sets them. Property files are used to set the applet depending on the users group and language that users want to use.
For example, let TextEditor.properties be the main property file for one group of users, then depending of user's choice of language (by choosing appropriate HTML document designed for that language) he will use the "language" property file for chosen language. For example, the language property file for German language is Text_de.properties, but for Spanish language is Text_es.properties. If the Editor can't find the match (if there is no property file for that language) then it uses the default "language" property file named Text.properties which is English.
As it is said before, there are two types of property files.
The first type is the main property file. Within the "main" property file, WEB Administrator defines menubar's content (which menus makes menubar), menu's content (which menu items makes some menu), menu item's properties (actions, images), toolbar content (which buttons and combos makes toolbar), buttons and combos properties (actions, images) and default font and color values.
The second type is the language property file. Within the "language" property file, WEB Administrator defines the labels for all menus and menu items and tooltip texts for all buttons. These labels and tooltip texts are supposed to be written in different languages for different "language" property files.
Default "language" property file must have a name "Text.properties" and within this file all labels and tooltips for default (English) language must be defined. This labels and tooltips are always used if there is no appropriate labels and tooltips within the property file for chosen language. Property files for other languages must have names that follow this rule:
name = "Text_" + language + ".properties"
which means that property file for Italian language will be "Text_it.properties", for German language will be "Text_de.properties", etc.(NOTE: it is not strictly defined that language property files must have above mentioned names for language part; you can for e.g. give the name "Text_German.properties" for German language property file, but then you also must define the parameter "Language" in appropriate HTML document as "German").
For every group of users that should have different setup for menus and toolbar there should be a different "main" property file, for e.g. Group 1 should have "TextEditor1.properties", Group 2 should have "TextEditor2.properties". Suppose that inside every group of users there are users that uses different languages (for e.g. English, France, German, Spanish, ...). Then every English user will use "Text.properties" (default) "language" property file along with his "main" property file, every French user will use "Text_fr.properties" "language" property file along with his "main" property file, etc. For this to be done, there must be defined two parameters within the appropriate HTML document, for e.g. for French user from fourth group there should be HTML document which will contain following:
<PARAM NAME = "Resource" VALUE = "TextEditor4"> <PARAM NAME = "Language" VALUE = "fr">
NOTE: The HTML document will be explained in following section of this document
You can comment lines in property file by putting '#' at beginning of line. In that case content of this line is not considered by applet.
The settings that can be adjusted by the main property file are:
content of menubar
content of toolbar
content of menus (menu items)
menu item's action
toolbar button's actions
menu item icons
toolbar icons
font size labels
lineHeight parameter
Menubar can consist of file, edit, format and info menu (all of them, some of them or non of them) which is determined by the property file line: menubar = edit format info - if you want all menus, menubar = edit format - if you want some of them. If you don't want menubar you don't write anything about that in property file
Toolbar can consist of cut, copy, paste, bold, italic, underline, left, center and right buttons and font family and font size combos (all of them, some of them or non of them), which is determined by the property file line: toolbar=cut copy paste - bold italic underline - left center right - fontfamily fontsize - if you want all of them, toolbar=cut copy paste - bold italic underline - left center right - if you want some of them. If you don't want toolbar at all, you don't write anything about that to the property file. (NOTE: '-' means that buttons are delimited by space)
Every menu consists of menu items, for e.g. edit menu consists of menu items cut, copy and paste which is determined by property file line: edit = cut copy paste, or for e.g. info menu consists of menu items parameter and about delimited by '-' which is determined by property file line: info = parameter - about
There are some standard predefined actions which can be managed in following way:cutAction = cut-to-clipboard copyAction = copy-to-clipboard and similar for other commands.
These are only labels that are defined in "main" property file because they always have the same numeric values which don't depend on language.
Menu item icons can be easily set by property file, for e.g. menu item 'cut' has icon which is determined by property file line: cutImageMenu =Images/Cut16.gif which means that icon is a gif file Cut16.gif located in subdirectory Images of directory where HTML file which contains our applet is placed. Menu item icons dimensions should be the same for all items (16x16 pixels recommended).
Toolbar button icons can also be easily set by property file, for e.g. toolbar button 'cut' has icon which is determined by property file line: cutImageTool = Images/Cut24.gif which means that icon is gif file Cut24.gif located in subdirectory Images of directory where HTML file which contains our applet is placed. Toolbar icons dimensions should be the same for all buttons (24x24 pixels recommended).
lineHeight parameter is used when applet context is formatted in a form of XSL:FO format, and it determines the height of lines in resulting PDF document. Valid values for this parameter are between 8 and 96.
These actions are shareable with corresponding menu items (except actions used to align text) and are not defined separately.
The settings that can be adjusted by the “language” property file are:
menu labels and menu item labels
tooltips
Menu labels can be set according to the language, for e.g. menu item “cut” could have menu label cutLabel = Cut in English version of property file (“Text.properties”), but cutLabel=Couper in French version of property file (“Text_fr.properties”).
Tooltips of toolbar buttons are managed by property file lines like following line for adjusting tooltip text of cut button: cutTooltip=Move selection to clipboard.
There are some default values for "main" property file:
font family (e.g. defFontFamily=SansSerif) font size (e.g. defFontSize=16) bold font style (e.g. defbold=true) italic font style (e.g. defitalic=false) underline font style (e.g. defunder=true) foreground color (e.g. foreground=Color.blue) background color (e.g. background=SystemColor.info) caret color (e.g. caretColor=Color.blue) selected text color (e.g. selectedTextColor=Color.cyan) selection color (e.g. selectionColor=Color.lightGray) border color (e.g. border=Color.orange)
By setting these values in property file, every time Editor starts, the startup settings will correspond to these values. Color values can't be changed after Editor starts, while other values, of course, can change. Possible settings for default values are:
Table 6.1. Possible default values
NAME OF DEF. VALUE | POSSIBLE SETTINGS |
---|---|
defFontFamily | SansSerif, Serif, Courier |
defFontSize | 8, 10, 12, 14, 16, 18, 24, 36, 48 |
defbold,defitalic, defunder | true, false |
foreground, background, caretColor, selectedTextColor, selectionColor, border | Color.black, Color.blue, Color.cyan, Color.darkGray, Color.gray, Color.green, Color.lightGray, Color.magenta, Color.orange,Color.pink, Color.red, Color.white, Color.yellow, SystemColor.desktop, SystemColor.activeCaption, SystemColor.activeCaptionText,SystemColor.activeCaptionBorder, SystemColor.inactiveCaption, SystemColor.inactiveCaptionText, SystemColor.inactiveCaptionBorder, SystemColor.window, SystemColor.windowBorder, SystemColor.windowText, SystemColor.menu, SystemColor.menuText, SystemColor.text, SystemColor.textText, SystemColor.textHighlight, SystemColor.textHighlightText, SystemColor.textInactiveText, SystemColor.control, SystemColor.controlText, SystemColor.controlHighlight, SystemColor.controlLtHighlight, SystemColor.controlShadow, SystemColor.controlDkShadow, SystemColor.scrollbar, SystemColor.info, SystemColor.infoText |
Example HTML page contains:
1. Fields for entering data
2. FOP Editor applet (where we can put some formatted text)
3. Button “Create PDF”
When the Button “Create PDF” is pressed, JavaScript calls applet's method FormatFO() that returns a String which represents a content of applet and is already formatted as a part of XSL:FO file (so when XSL:FO file is formatted at servlet this String is just build-in), and put it in a hidden field on HTML page. Then servlet reads from HTML page content from all visible fields plus one hidden field. In that moment begins formatting of XSL:FO file at servlet. Like a result we receive a PDF file. After that, Acrobat Reader is being opened with the data we put in HTML document fields plus the Editor content.
Here we'll be explained HTML documents that serve as example of using FOP Editor applet. The line with META tag specifies the character encoding for a document as being “ISO-8859-1”:
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1>
That is important for charset to be latin1 because for some other charsets browser is inserting entity names (for e.g. for sign “ñ” browser inserts entity name "ñ" which causes error during processing text into a PDF document. This line could be omitted because charset is by default set to "ISO-8859-1".
There is a JavaScript function in HTML document that transforms (by interaction with applet) the applet written text to a XSL:FO file format and puts it in a hidden field named. This field is defined elsewhere in HTML document. (Notice that names used in this example are: 'FOPForm' - the form name, 'context' - the name of the hidden field and 'FOPApplet' - the name used to access the applet)
<SCRIPT type="text/javascript"> <!-- // call this function when button "Create PDF" pressed function CreatePDF() { // calls Java method FormatFO() which make formatted string for // .XSL:FO file and put this string in hidden field 'context'; // after that is executed FORM method "post", who send string // to the servlet named ServletEditor document.FOPForm.context.value=document.FOPApplet.FormatFO(); } //--> </SCRIPT>
Now we come to the form definition. In this example form is used to place some labels and text fields in it (only one field is necessary - the field named “context”), to place the applet and to place the button that will cause the action defined by the FORM tag. All form components, except the “context” field, are placed into the cells of tables defined by the tag TABLE. When the form is submitted (when user presses “Create PDF” button) JavaScript that transforms applet context into XSL:FO file format is executed, and such formatted text is put in a hidden field. After that, the form will be sent to the program specified by the action attribute, in our case it will be (for example purpose made) servlet ServletEditor.po:
<FORM NAME = "FOPForm" action = "http://localhost:8011/ServletEditor.po" method = "post" >
Inside the FORM tag there is a TABLE tag. Table is made of cells that contains labels and input fields for entering some data, such as "Date", "Name" and "Subject" in this HTML examples. Content of every INPUT element control inside the FORM is passed to the servlet when submit button is pressed.
The applet is added to HTML in following way:
<OBJECT classid = "clsid:8AD9C840-044E-11D1-B3E9-00805F499D93" ID="FOPApplet" WIDTH = "650" HEIGHT = "300" codebase = "http://java.sun.com/products/plugin/1.3/jinstall-13-win32.cab#Version = 1,3,0,0"> <PARAM NAME = ARCHIVE VALUE = "FOPEditor.jar" > <PARAM NAME = CODE VALUE = "TextEditor.class" > <PARAM NAME = "type" VALUE="application/x-java-applet;version=1.3"> <PARAM NAME = "scriptable" VALUE="true"> <PARAM NAME = "Resource" VALUE = "TextEditor"> <PARAM NAME = "Language" VALUE = "en"> <COMMENT> <EMBED NAME = "FOPApplet" type="application/x-java-applet;jpi-version=1.3" ARCHIVE = "FOPEditor.jar" CODE = "TextEditor" WIDTH = "650" HEIGHT = "300" Resource = "TextEditor" Language = "en" scriptable=true pluginspage="http://java.sun.com/products/plugin/index.html#download"> <NOEMBED>This browser does not appear to support Applets.<NOEMBED> </EMBED></COMMENT></OBJECT>
This program listing has two parts. One (<OBJECT> tag) is used for MS Internet Explorer browser (and similar browsers). Other part (;<EMBED> tag) is for Netscape's like browsers (Netscape Communicator, Mozilla,...). The applet is not added by the APPLET tag because APPLET tag can't force the browser to use Java Plug-in. When you add applet in a way written above, the browser will understand it and execute it.
Let us explain the meaning of OBJECT tag (and similar meaning is for EMBED tag):
The classid attribute in the OBJECT tag is the class identifier for Java Plug-in itself. This class identifier should be the same in every HTML page. When browser renders this class identifier in the OBJECT tag, it will try to load Java Plug-in into the browser.
determines the width and height of the applet
represents the name used to access the applet within the HTML document (the JavaScript function CreatePDF() access to the applet function through this name)
represents the location from which to download Java Plug-in when it is not found on the local machine.
identifies the java .jar file which is the applet, actually
identifies the base class inside of jar file
identifies the type of the Java executable, such as an applet or a JavaBean, so Java Plug-in knows how to initialize the Java executable.
indicates if the applet requires scripting support
determines the name of the "main" property file to be used
determines the name of the "language" property file to be used
When writing your own HTML document or adjusting this document, you should only change the width and height attributes and resource and language parameter if needed.
Now we came to the definition of submit button:
<input type="submit" value="Create PDF" onClick = "CreatePDF()" name="Submit">
Attribute type defines this control as a submit button. When activated, the submit button submits the form. Attribute value is the text that will be written on the button. Attribute onClick defines which script to process after clicking the button. Attribute name is a name of a button used to access him within an HTML document.
At the end of the document is defined hidden INPUT field named 'context' which purpose is to hold the applet formatted text after pushing submit button.
<input type="hidden" name="context">