define. title The Flying Saucer User's Guide
define. headElementAdd
define. style
#toc {
page-break-before: always;
font-size: 18pt;
text-align: center;
}
.printOnly, #footer, #header {
display: none;
}
h1{text-align: center;}. The Flying Saucer User's Guide
divStart(printOnly).
p{font-size: 10pt; text-align: center}. _Getting Started with Flying Saucer_
p{font-size: 12pt; text-align: center}. Release R7
p{font-size: 12pt; text-align: center}. July 2007
divEnd.
divStart(#header){position: absolute; top: 0; left: 0; -fs-move-to-flow: 'header';}.
Flying Saucer User's Guide
divEnd.
divStart(#footer){position: absolute; top: 0; left: 0; -fs-move-to-flow: 'footer';}.
Page of
divEnd.
p(#toc). Table of Contents
toc. 2 4 #
h2. Document History
Updates to this document:
* 19-08-2007: Corrected sample for how to use UTF-8 fonts when rendering to PDF (PW)
h2. An Introduction to Flying Saucer
h3(fs_heading). What it is
Flying Saucer is an XML/CSS _renderer_, which means it takes XML files as input, applies formatting and styling using CSS, and generates a rendered representation of that XML as output. The output may go to the screen (in a GUI), to an image, or to a PDF file. Because we believe most people will rely on conventional practices, our main target for content is XHTML 1.0 (strict), an XML document format that standardizes HTML. However, we accept any well-formed XML for rendering as long as CSS is provided that tells us how to lay it out. In the case of XHTML, default stylesheets are provided out of the box and packaged within the library.
Internally, Flying Saucer works with an XML document and uses CSS to determine how to lay it out visually. The rules for layout come from the "CSS 2.1 specification":css21, and according to that spec, element nodes and attributes are matched to CSS selectors, where each selector identifies some formatting rules. We can't cover how to use CSS here--it's a long and complex specification--but there are many good books available, and tutorials on the web. Check out the "W3Schools CSS Tutorial":http://www.w3schools.com/css/default.asp for a starting point.
h3(fs_heading). What it does
Flying Saucer takes XML and CSS as input (where the CSS might be embedded in the document, or linked from it) and generates rendered content. Our current major output formats are in a GUI interface (a Swing JPanel) and in PDF; we can also render to image formats, e.g. render the page and save as an image. There is experimental support for output to SWT containers.
If rendering to a GUI, hyperlinks work so you can navigate between pages. As with HTML, you can also render forms, capture output, and create interactive applications. In a GUI, Flying Saucer provides a _read-only_ view of the output; we cannot replace a text area, say, or Swing's @JEditorPane@ or @JTextPane@. However, for static content, or content created by you, Flying Saucer can be used for help documents, tutorials, books, splash screens, presentations, and much more.
We can also render to PDF. For PDF, the layout rules come from the CSS. The difference is the rendered output uses the ${itext} library to generate PDF. Note that Flying Saucer supports media types for CSS, allowing you to distinguish between screen and print media, for example.
Last, we have utility classes to render output to an image file. With this, you could use XML and CSS to layout printable content--for example, a flyer, a poster, business cards, etc.--and save them as ../images you can print out or email. It's also a nice way to create thumbnail or reduced-size ../images of pages.
h3(fs_heading). What you can do with it
Flying Saucer can be used for any Java application that requires some sort of styled text, style-based layout, and for content that needs to look good in a GUI, on the Web, or in print. This can be as simple as a chat program or as complicated as a complete ebook reader with dynamic stylesheets. Flying Saucer is very forward-thinking and designed to be a part of the next generation of applications that combine rich desktop clients with web content. Some examples of application types are:
* chat programs
* online music stores
* a Gutenberg eBook reader
* a distributed dictionary application
* Sherlock style map and movie search
* Konfabulator and Dashboard components
* an RSS reader
* a Friendster client
* an eBay client
* a splash screen
* an about box
* a helpfile viewer
* a javadoc viewer
* report generation and viewing
* a stock ticker / weather reporter
h3(fs_heading). Where the Saucer Does not Fly (what it can't do)
Being honorable people, we must admit what Flying Saucer cannot do for you. This list applies to the current release when this document was written, R7; when in doubt, please contact us on our mailing list.
Limitations:
* Resource loading is single-threaded and occurs inline with layout.
* Support for XHTML is weaker than XML+CSS (for example, not all XHTML presentational attributes are supported nor are X/HTML features like the <object> element).
* No support for legacy HTML (although there are several open source Java HTML cleaners of varying quality available). We render well-formed XML; XHTML is a well-formed document standard. We can't render most HTML "in the wild". At best, you can "clean up" old HTML with "TagSoup":http://home.ccil.org/~cowan/XML/tagsoup/ or "JTidy":http://sourceforge.net/projects/jtidy and hope for the best. But without a bunch of work, you won't be able to use Flying Saucer for a real web browser component. However, note that's not a technical limitation, just a lack of time and resources.
* Swing printing is supported, but quality is lacking. Ask on the ${mailing-list} for details.
* No support for incremental layout (applies to screen media only).
* It cannot be used for user-editable content; output is read-only.
* HTML plugins, like applets, Flash programs, etc. are not supported. However, these could potentially be addressed using replaced element content (such as we use for HTML forms), at least for Java applets.
* Scripting (e.g. JavaScript) is not supported. We ignore script tags.
* Dynamic changes to the content requires a reload of the document (quick, but noticeable), that is, you can't dynamically change the DOM and see results live.
* Most DOM callbacks used in JavaScript are not yet implemented (onLoad, onClick, onBlur, etc.).
These limitations all have a pragmatic origin. Josh Marinacci, the founder of and original lead developer for the Flying Saucer project, realized that writing a fully capable HTML browser component (like Firefox's Gecko engine) could take many man-years of development. But if one focused on well-formed XML/XHTML only, and stuck to the CSS spec, you could cover most of the useful stuff you want to do with a rendering engine, and do it in a reasonable amount of time. So it's not impossible to add scripting, DHTML, plugins to Flying Saucer, we've just deferred this until someone has the time and energy to get it to work--that way, we stay focused on the goal, which is pure CSS 2.1 support for well-formed XML.
Of course, you can help fix any of these things. Contributors welcome!
h3(fs_heading). License and Dependencies
Flying Saucer itself is licensed under the "GNU Lesser General Public License":http://www.gnu.org/copyleft/lesser.html. You can use Flying Saucer in any way you want as long as you respect the terms of the license. A copy of the LGPL is provided under LGPL.txt in our distribution.
Flying Saucer uses a couple of FOSS packages to get the job done. A list of these, along with the license they each have, is listed in the LICENSE file in our distribution.
h3(fs_heading). Requirements for Running and Using Flying Saucer
Flying Saucer is built and tested on Java 1.4 and has some dependencies on libraries (such as JDK logging) only available in 1.4. In principle, you should be able to backport it to 1.3 (or earlier?), but we've not tried that and don't maintain a 1.3 branch.
Basic requirements:
* Java Runtime Environment 1.4 or above (or JDK of course)
* core-renderer.jar (our distribution)
* ${itext} (also at "iText PDF":http://itextpdf.sourceforge.net)
* "Ant":http://ant.apache.org if you want to build from source
* Minium antialiasing: Minimum is an anti-aliasing library donated by Julian Scheid. We distribute the JAR for this; don't know of it being posted elsewhere. This is only necessary if you want to use this anti-aliasing approach; the Browser demo shows it in practice, and you may like it better than the Java anti-aliasing support, especially in Java 1.4.
${itext} is not necessary at runtime if you are not generating PDFs, but is necessary for the build to satisfy compile-time dependencies. We include a version with our distribution; you should be able to use a release directly from the ${itext} project, as long as the API is the same.
Flying Saucer includes its own CSS parser. There is currently no adaptor for external parsers--we didn't find any high-quality, actively-maintained ones. However, such an adapter did exists--we used to use the SteadyState CSS parser, so in principle, a different CSS parser could be used.
Most of Flying Saucer does not rely on advanced Java features. It should be usable on alternate Java implementations, such as GNU Classpath or Apache Harmony, but this hasn't been tested. You do need solid Java2D (including font) support.
h3(fs_heading#set_classpath). Setting your Classpath
You only need the @core-renderer.jar@ and the @cssparser-0-9-4-fs.jar@ in your CLASSPATH. If you want PDF output, add @itext-paulo-155.jar@. If you want anti-aliasing using the Minium toolkit, add @minium.jar@. That is all you need for your own programs. You also need an XML parser to be in your classpath, but this already included in recent versions of the JRE. To run the browser or use any of it's support classes you will need the @browser.jar@ file.
To summarize, the easiest CLASSPATH to set is:
* @core-renderer.jar@ (required)
* @itext-paulo-155.jar@
* @minium.jar@
h3(fs_heading). Sample Applications
toc. 4 4 *
h4(fs_heading). The Browser
The Flying Saucer Browser demo, located under @demos/browser@ is *not* intended to be a real web browser--there are lots of things it can't do. But it can show you how to use Flying Saucer in a "real" Java application.
The Browser hosts the FS renderer ( @XHTMLPanel@ class) inside a scrollpane ( @FSScrollPane@ class) inside an application @JFrame@. You can move between pages using hyperlinks, menu items (see the list under the Demo menu), via File/Open File, or by entering a URL in the location bar. URLs in the location bar have to either @http://@ format, or the standard nonsense format for local files, if you aren't running in a sandbox. If you want to browse open files, use File/Open File to open one first, then use the same URL format to type in other file names.
You can use Alt-N/Alt-P to navigate between the demo pages, packaged along with the browser. On the View menu, there are shortcuts to change the text size (increase or decrease). On the Debug menu, you can control anti-aliasing, turn page box outlines on or off, or use a simple DOM inspector to view CSS properties for the page. The Help menu has a link to load this document, the Flying Saucer User's Guide.
If you are running outside of a sandbox, you can also enter a directory name in the location bar, and a simple page with the directory contents will show up. It's not a complete file browser, but should give you and idea of how to create XHTML on the fly.
If you have downloaded the source, you can run the Browser by typing
bcx.. ant browser
p. This will compile any changes in the core renderer and Browser, rebuild the jars, and launch the Browser. If you want to change any standard configuration settings when running the Browser, please see the section on our "configuration system":#configuration.
h4(fs_heading). The About Box
The About Box demo shows how to open a single dialog box with auto-scrolling enabled--to gradually show the user the information about your app.
The AboutBox is a prefab component which displays an XHTML document and automatically scrolls it. It is primarily useful for Help->About menu items and splash screens.
Here is an example of adding an about box to a menu item's action listener.
bcx..
import org.xhtmlrenderer.demo.aboutbox.AboutBox;
.
.
.
.
.
.
JMenuItem about = new JMenuItem("About...");
about.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent evt) {
AboutBox ab = new AboutBox
(
"About Flying Saucer",
"demos/about/index.xhtml"
);
ab.setVisible(true);
}
});
p. If you have downloaded the source, you can run the About Box by typing
bcx.. ant aboutbox
p. This will compile any changes in the core renderer and About Box, rebuild the jars, and launch the About Box demo. If you want to change any standard configuration settings when running the About Box, please see the section on our "configuration system":#configuration.
h4(fs_heading). DocBook
Our DocBook demo, under @demos/docbook@, shows how a DocBook XML document can be rendered using only CSS, without converting it to XHTML first. This relies on an CSS which we've packaged here--there are three different versions available in our source tree; your mileage may vary with each one, as there is really no active work in this direction.
To run the demo once you have our sources downloaded, just use our Ant build file and type @ant docbook@. The DocBook sample (taken from the jEdit User's Guide) is rendered in a single JFrame. The demo doesn't actually demonstrate anything new--the DocBook contains the reference to the CSS of choice (in the demo, wysiwygdocbook1.01).
p. If you have downloaded the source, you can run the DocBook demo by typing
bcx.. ant docbook
p. This will compile any changes in the core renderer and DocBook demo, rebuild the jars, and launch the demo. If you want to change any standard configuration settings when running the DocBook demo, please see the section on our "configuration system":#configuration.
Interestingly--in this case there is nothing special to be done, no special APIs in Flying Saucer to call. The DocBook XML for the jEdit document just has a link to the CSS required to render it, like this:
That's it. The rest is pure XML, following DocBook conventions. You just need to load this XML into a panel using @setDocument()@ and you're done.
h4(fs_heading). SVG
Our SVG demo, @ant svg@, shows how SVG references can be embedded in an XHTML page and rendered as ../images at runtime. This demonstrates how a @org.xhtmlrenderer.extend.ReplacedElementFactory@ can swap any XML content in the Document with another visual element--in this case, the SVG elements are parsed using the "SVGSalamander":http://svgsalamander.dev.java.net SVG library and returned as panels to the renderer. You could try using another Java SVG library, such as Batik--but the more important principle is that you are in control of how the elements are rendered to the screen. The code is available in @demos/svg@.
p. If you have downloaded the source, you can run the SVG demo by typing
bcx.. ant svg
p. This will compile any changes in the core renderer and SVG demo, rebuild the jars, and launch the demo. If you want to change any standard configuration settings when running the SVG demo, please see the section on our "configuration system":#configuration.
h2. Using Flying Saucer
h3(fs_heading). Important Concepts
The Flying Saucer library is meant to be fairly easy to use, which means you shouldn't have to do much to integrate it into your applications. This means that a number of aspects of the library are configured for you out-of-the-box; some other things you can modify via our "configuration system":#configuration. However, there are some characteristics of the library that you can't modify via configuration, but which you may want to modify for advanced use of the renderer.
h4(fs_heading). NamespaceHandler
The @org.xhtmlrenderer.extend.NamespaceHandler@ interface provides the renderer with knowledge about a document that is specific to that document type. The renderer just knows that its input is XML; it doesn't know how that particular XML format might include CSS styles, for example (XML and XHTML have different mechanisms for that).
Flying Saucer includes pre-built implementations of @NamespaceHandler@ for plain XML, XHTML, and a special version for converting legacy HTML element styling into valid CSS styles.
You can provide a @NamespaceHandler@ instance to a @BasicPanel@ during calls to @setDocument()@, or you can set it via the @SharedContext@ that the panel uses during rendering. By default, the @XHTMLPanel@ will use an @XhtmlNamespaceHandler@, which means you can load XHTML without extra works.
bcx.
import org.mycode.MyNamespaceHandler;
.
.
.
XHTMLPanel panel = new XHTMLPanel();
NamespaceHandler nsh = new MyNamespaceHandler;
panel.setDocument(new File("index.html"), nsh);
p. or
bcx.
import org.mycode.MyNamespaceHandler;
.
.
.
XHTMLPanel panel = new XHTMLPanel();
NamespaceHandler nsh = new MyNamespaceHandler;
panel.getSharedContext().setNamespaceHandler(nsh);
panel.setDocument(new File("index.html"));
h4(fs_heading). UserAgentCallback
The @org.xhtmlrenderer.extend.UserAgentCallback@ interface allows some control over the "user agent", a concept introduced by the W3C to abstract the notion of the "agent" responsible for rendering content to a user; you can think of the "user agent" in Flying Saucer as the UI component rendering a document.
In Flying Saucer, the @UserAgentCallback@ is used by the library for retrieving XML, CSS and image data, and for resolving URIs and base URIs, among other things. For example, this means that when the library encounters a reference to a CSS file, there is no built-in knowledge of how to retrieve that; the user agent is asked to retrieve the CSS using the URI. The user agent can then look in a local cache, in-memory, or just retrieve it over the network.
The library includes a simple UAC called @NaiveUserAgent@ which provides for very basic caching of image resources, and resolution of relative URIs. You will probably want to write your own in order to optimize image loading and caching, XML resource loading (or handling specialized XML sources) and CSS loading. You may also code handling for custom URIs--the demo Browser application uses a URI prefix "demoNav://" to manage navigation between demo pages, for example.
You can provide a new @UserAgentCallback@ instance in a constructor for the @BasicPanel@. Note that for PDF output, if you are going to use your own UAC, you should take a look at @org.xhtmlrenderer.pdf.ITextUserAgent@ in the source codebase; this class has some special handling for ../images to ready them for PDF output.
h4(fs_heading). ReplacedElementFactory
The @org.xhtmlrenderer.extend.ReplacedElementFactory@ provides XML-element replacement during the layout and render cycle. The most obvious use for this is for elements that point to content which is not itself part of the document, like ../images; with just an @@ element, the library has no way to actually render an image (or an icon, or whatever). To do this, it uses a @ReplacedElementFactory@, which resolves the @@ to, for example, an @ImageIcon@, and returns this (wrapped in an interface) as a pre-sized component that the library can render in-place. In our SVG demo, this same technique is used to render specific @
Flying Saucer is an XML/CSS _renderer_, which means it takes XML files as input, applies formatting and styling using CSS, and generates a rendered representation of that XML as output. The output may go to the screen (in a GUI), to an image, or to a PDF file. Because we believe most people will rely on conventional practices, our main target for content is XHTML 1.0 (strict), an XML document format that standardizes HTML. However, we accept any well-formed XML for rendering as long as CSS is provided that tells us how to lay it out. In the case of XHTML, default stylesheets are provided out of the box and packaged within the library.
Internally, Flying Saucer works with an XML document and uses CSS to determine how to lay it out visually. The rules for layout come from the "CSS 2.1 specification":css21, and according to that spec, element nodes and attributes are matched to CSS selectors, where each selector identifies some formatting rules. We can't cover how to use CSS here--it's a long and complex specification--but there are many good books available, and tutorials on the web. Check out the "W3Schools CSS Tutorial":http://www.w3schools.com/css/default.asp for a starting point.
h3(fs_heading). What it does
Flying Saucer takes XML and CSS as input (where the CSS might be embedded in the document, or linked from it) and generates rendered content. Our current major output formats are in a GUI interface (a Swing JPanel) and in PDF; we can also render to image formats, e.g. render the page and save as an image. There is experimental support for output to SWT containers.
If rendering to a GUI, hyperlinks work so you can navigate between pages. As with HTML, you can also render forms, capture output, and create interactive applications. In a GUI, Flying Saucer provides a _read-only_ view of the output; we cannot replace a text area, say, or Swing's @JEditorPane@ or @JTextPane@. However, for static content, or content created by you, Flying Saucer can be used for help documents, tutorials, books, splash screens, presentations, and much more.
We can also render to PDF. For PDF, the layout rules come from the CSS. The difference is the rendered output uses the ${itext} library to generate PDF. Note that Flying Saucer supports media types for CSS, allowing you to distinguish between screen and print media, for example.
Last, we have utility classes to render output to an image file. With this, you could use XML and CSS to layout printable content--for example, a flyer, a poster, business cards, etc.--and save them as ../images you can print out or email. It's also a nice way to create thumbnail or reduced-size ../images of pages.
h3(fs_heading). What you can do with it
Flying Saucer can be used for any Java application that requires some sort of styled text, style-based layout, and for content that needs to look good in a GUI, on the Web, or in print. This can be as simple as a chat program or as complicated as a complete ebook reader with dynamic stylesheets. Flying Saucer is very forward-thinking and designed to be a part of the next generation of applications that combine rich desktop clients with web content. Some examples of application types are:
* chat programs
* online music stores
* a Gutenberg eBook reader
* a distributed dictionary application
* Sherlock style map and movie search
* Konfabulator and Dashboard components
* an RSS reader
* a Friendster client
* an eBay client
* a splash screen
* an about box
* a helpfile viewer
* a javadoc viewer
* report generation and viewing
* a stock ticker / weather reporter
h3(fs_heading). Where the Saucer Does not Fly (what it can't do)
Being honorable people, we must admit what Flying Saucer cannot do for you. This list applies to the current release when this document was written, R7; when in doubt, please contact us on our mailing list.
Limitations:
* Resource loading is single-threaded and occurs inline with layout.
* Support for XHTML is weaker than XML+CSS (for example, not all XHTML presentational attributes are supported nor are X/HTML features like the <object> element).
* No support for legacy HTML (although there are several open source Java HTML cleaners of varying quality available). We render well-formed XML; XHTML is a well-formed document standard. We can't render most HTML "in the wild". At best, you can "clean up" old HTML with "TagSoup":http://home.ccil.org/~cowan/XML/tagsoup/ or "JTidy":http://sourceforge.net/projects/jtidy and hope for the best. But without a bunch of work, you won't be able to use Flying Saucer for a real web browser component. However, note that's not a technical limitation, just a lack of time and resources.
* Swing printing is supported, but quality is lacking. Ask on the ${mailing-list} for details.
* No support for incremental layout (applies to screen media only).
* It cannot be used for user-editable content; output is read-only.
* HTML plugins, like applets, Flash programs, etc. are not supported. However, these could potentially be addressed using replaced element content (such as we use for HTML forms), at least for Java applets.
* Scripting (e.g. JavaScript) is not supported. We ignore script tags.
* Dynamic changes to the content requires a reload of the document (quick, but noticeable), that is, you can't dynamically change the DOM and see results live.
* Most DOM callbacks used in JavaScript are not yet implemented (onLoad, onClick, onBlur, etc.).
These limitations all have a pragmatic origin. Josh Marinacci, the founder of and original lead developer for the Flying Saucer project, realized that writing a fully capable HTML browser component (like Firefox's Gecko engine) could take many man-years of development. But if one focused on well-formed XML/XHTML only, and stuck to the CSS spec, you could cover most of the useful stuff you want to do with a rendering engine, and do it in a reasonable amount of time. So it's not impossible to add scripting, DHTML, plugins to Flying Saucer, we've just deferred this until someone has the time and energy to get it to work--that way, we stay focused on the goal, which is pure CSS 2.1 support for well-formed XML.
Of course, you can help fix any of these things. Contributors welcome!
h3(fs_heading). License and Dependencies
Flying Saucer itself is licensed under the "GNU Lesser General Public License":http://www.gnu.org/copyleft/lesser.html. You can use Flying Saucer in any way you want as long as you respect the terms of the license. A copy of the LGPL is provided under LGPL.txt in our distribution.
Flying Saucer uses a couple of FOSS packages to get the job done. A list of these, along with the license they each have, is listed in the LICENSE file in our distribution.
h3(fs_heading). Requirements for Running and Using Flying Saucer
Flying Saucer is built and tested on Java 1.4 and has some dependencies on libraries (such as JDK logging) only available in 1.4. In principle, you should be able to backport it to 1.3 (or earlier?), but we've not tried that and don't maintain a 1.3 branch.
Basic requirements:
* Java Runtime Environment 1.4 or above (or JDK of course)
* core-renderer.jar (our distribution)
* ${itext} (also at "iText PDF":http://itextpdf.sourceforge.net)
* "Ant":http://ant.apache.org if you want to build from source
* Minium antialiasing: Minimum is an anti-aliasing library donated by Julian Scheid. We distribute the JAR for this; don't know of it being posted elsewhere. This is only necessary if you want to use this anti-aliasing approach; the Browser demo shows it in practice, and you may like it better than the Java anti-aliasing support, especially in Java 1.4.
${itext} is not necessary at runtime if you are not generating PDFs, but is necessary for the build to satisfy compile-time dependencies. We include a version with our distribution; you should be able to use a release directly from the ${itext} project, as long as the API is the same.
Flying Saucer includes its own CSS parser. There is currently no adaptor for external parsers--we didn't find any high-quality, actively-maintained ones. However, such an adapter did exists--we used to use the SteadyState CSS parser, so in principle, a different CSS parser could be used.
Most of Flying Saucer does not rely on advanced Java features. It should be usable on alternate Java implementations, such as GNU Classpath or Apache Harmony, but this hasn't been tested. You do need solid Java2D (including font) support.
h3(fs_heading#set_classpath). Setting your Classpath
You only need the @core-renderer.jar@ and the @cssparser-0-9-4-fs.jar@ in your CLASSPATH. If you want PDF output, add @itext-paulo-155.jar@. If you want anti-aliasing using the Minium toolkit, add @minium.jar@. That is all you need for your own programs. You also need an XML parser to be in your classpath, but this already included in recent versions of the JRE. To run the browser or use any of it's support classes you will need the @browser.jar@ file.
To summarize, the easiest CLASSPATH to set is:
* @core-renderer.jar@ (required)
* @itext-paulo-155.jar@
* @minium.jar@
h3(fs_heading). Sample Applications
toc. 4 4 *
h4(fs_heading). The Browser
The Flying Saucer Browser demo, located under @demos/browser@ is *not* intended to be a real web browser--there are lots of things it can't do. But it can show you how to use Flying Saucer in a "real" Java application.
The Browser hosts the FS renderer ( @XHTMLPanel@ class) inside a scrollpane ( @FSScrollPane@ class) inside an application @JFrame@. You can move between pages using hyperlinks, menu items (see the list under the Demo menu), via File/Open File, or by entering a URL in the location bar. URLs in the location bar have to either @http://@ format, or the standard nonsense format for local files, if you aren't running in a sandbox. If you want to browse open files, use File/Open File to open one first, then use the same URL format to type in other file names.
You can use Alt-N/Alt-P to navigate between the demo pages, packaged along with the browser. On the View menu, there are shortcuts to change the text size (increase or decrease). On the Debug menu, you can control anti-aliasing, turn page box outlines on or off, or use a simple DOM inspector to view CSS properties for the page. The Help menu has a link to load this document, the Flying Saucer User's Guide.
If you are running outside of a sandbox, you can also enter a directory name in the location bar, and a simple page with the directory contents will show up. It's not a complete file browser, but should give you and idea of how to create XHTML on the fly.
If you have downloaded the source, you can run the Browser by typing
bcx.. ant browser
p. This will compile any changes in the core renderer and Browser, rebuild the jars, and launch the Browser. If you want to change any standard configuration settings when running the Browser, please see the section on our "configuration system":#configuration.
h4(fs_heading). The About Box
The About Box demo shows how to open a single dialog box with auto-scrolling enabled--to gradually show the user the information about your app.
The AboutBox is a prefab component which displays an XHTML document and automatically scrolls it. It is primarily useful for Help->About menu items and splash screens.
Here is an example of adding an about box to a menu item's action listener.
bcx..
import org.xhtmlrenderer.demo.aboutbox.AboutBox;
.
.
.
.
.
.
JMenuItem about = new JMenuItem("About...");
about.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent evt) {
AboutBox ab = new AboutBox
(
"About Flying Saucer",
"demos/about/index.xhtml"
);
ab.setVisible(true);
}
});
p. If you have downloaded the source, you can run the About Box by typing
bcx.. ant aboutbox
p. This will compile any changes in the core renderer and About Box, rebuild the jars, and launch the About Box demo. If you want to change any standard configuration settings when running the About Box, please see the section on our "configuration system":#configuration.
h4(fs_heading). DocBook
Our DocBook demo, under @demos/docbook@, shows how a DocBook XML document can be rendered using only CSS, without converting it to XHTML first. This relies on an CSS which we've packaged here--there are three different versions available in our source tree; your mileage may vary with each one, as there is really no active work in this direction.
To run the demo once you have our sources downloaded, just use our Ant build file and type @ant docbook@. The DocBook sample (taken from the jEdit User's Guide) is rendered in a single JFrame. The demo doesn't actually demonstrate anything new--the DocBook contains the reference to the CSS of choice (in the demo, wysiwygdocbook1.01).
p. If you have downloaded the source, you can run the DocBook demo by typing
bcx.. ant docbook
p. This will compile any changes in the core renderer and DocBook demo, rebuild the jars, and launch the demo. If you want to change any standard configuration settings when running the DocBook demo, please see the section on our "configuration system":#configuration.
Interestingly--in this case there is nothing special to be done, no special APIs in Flying Saucer to call. The DocBook XML for the jEdit document just has a link to the CSS required to render it, like this:
That's it. The rest is pure XML, following DocBook conventions. You just need to load this XML into a panel using @setDocument()@ and you're done.
h4(fs_heading). SVG
Our SVG demo, @ant svg@, shows how SVG references can be embedded in an XHTML page and rendered as ../images at runtime. This demonstrates how a @org.xhtmlrenderer.extend.ReplacedElementFactory@ can swap any XML content in the Document with another visual element--in this case, the SVG elements are parsed using the "SVGSalamander":http://svgsalamander.dev.java.net SVG library and returned as panels to the renderer. You could try using another Java SVG library, such as Batik--but the more important principle is that you are in control of how the elements are rendered to the screen. The code is available in @demos/svg@.
p. If you have downloaded the source, you can run the SVG demo by typing
bcx.. ant svg
p. This will compile any changes in the core renderer and SVG demo, rebuild the jars, and launch the demo. If you want to change any standard configuration settings when running the SVG demo, please see the section on our "configuration system":#configuration.
h2. Using Flying Saucer
h3(fs_heading). Important Concepts
The Flying Saucer library is meant to be fairly easy to use, which means you shouldn't have to do much to integrate it into your applications. This means that a number of aspects of the library are configured for you out-of-the-box; some other things you can modify via our "configuration system":#configuration. However, there are some characteristics of the library that you can't modify via configuration, but which you may want to modify for advanced use of the renderer.
h4(fs_heading). NamespaceHandler
The @org.xhtmlrenderer.extend.NamespaceHandler@ interface provides the renderer with knowledge about a document that is specific to that document type. The renderer just knows that its input is XML; it doesn't know how that particular XML format might include CSS styles, for example (XML and XHTML have different mechanisms for that).
Flying Saucer includes pre-built implementations of @NamespaceHandler@ for plain XML, XHTML, and a special version for converting legacy HTML element styling into valid CSS styles.
You can provide a @NamespaceHandler@ instance to a @BasicPanel@ during calls to @setDocument()@, or you can set it via the @SharedContext@ that the panel uses during rendering. By default, the @XHTMLPanel@ will use an @XhtmlNamespaceHandler@, which means you can load XHTML without extra works.
bcx.
import org.mycode.MyNamespaceHandler;
.
.
.
XHTMLPanel panel = new XHTMLPanel();
NamespaceHandler nsh = new MyNamespaceHandler;
panel.setDocument(new File("index.html"), nsh);
p. or
bcx.
import org.mycode.MyNamespaceHandler;
.
.
.
XHTMLPanel panel = new XHTMLPanel();
NamespaceHandler nsh = new MyNamespaceHandler;
panel.getSharedContext().setNamespaceHandler(nsh);
panel.setDocument(new File("index.html"));
h4(fs_heading). UserAgentCallback
The @org.xhtmlrenderer.extend.UserAgentCallback@ interface allows some control over the "user agent", a concept introduced by the W3C to abstract the notion of the "agent" responsible for rendering content to a user; you can think of the "user agent" in Flying Saucer as the UI component rendering a document.
In Flying Saucer, the @UserAgentCallback@ is used by the library for retrieving XML, CSS and image data, and for resolving URIs and base URIs, among other things. For example, this means that when the library encounters a reference to a CSS file, there is no built-in knowledge of how to retrieve that; the user agent is asked to retrieve the CSS using the URI. The user agent can then look in a local cache, in-memory, or just retrieve it over the network.
The library includes a simple UAC called @NaiveUserAgent@ which provides for very basic caching of image resources, and resolution of relative URIs. You will probably want to write your own in order to optimize image loading and caching, XML resource loading (or handling specialized XML sources) and CSS loading. You may also code handling for custom URIs--the demo Browser application uses a URI prefix "demoNav://" to manage navigation between demo pages, for example.
You can provide a new @UserAgentCallback@ instance in a constructor for the @BasicPanel@. Note that for PDF output, if you are going to use your own UAC, you should take a look at @org.xhtmlrenderer.pdf.ITextUserAgent@ in the source codebase; this class has some special handling for ../images to ready them for PDF output.
h4(fs_heading). ReplacedElementFactory
The @org.xhtmlrenderer.extend.ReplacedElementFactory@ provides XML-element replacement during the layout and render cycle. The most obvious use for this is for elements that point to content which is not itself part of the document, like ../images; with just an @