Getting Started with Flying Saucer R5 Release (beta 2)

June 29, 2005

The Flying Saucer team is proud to present the first beta release of version R5 of the Flying Saucer XML/CSS renderer, R5pre1. Download now!

flying-saucer-binary-R5pre1.zip - 1.3M; just the binaries, no source

To access the full source code and related files, connect to our java.net CVS resource--see instructions on https://xhtmlrenderer.dev.java.net/source/browse/xhtmlrenderer/. You'll need a java.net account to use this.

R5 includes a whole range of improvements and changes

• faster rendering
• more accurate page layout
• support more CSS properties
• support for layout of pure XML using only CSS
• dynamic styling on mouse hover
• support for pluggable SAX/XML parsers for source documents
• new simplified top-level packages to get you up and running

Where do I Start?

With R5, we created a new package structure with a minimum number of easy-to-use classes to get you started: org.xhtmlrenderer.simple.

Drop an XHTMLPanel in your Swing application, call setDocument() and you'll be rendering right away. Want scrolling ans standard keyboard bindings for navigation? Add your XHTMLPanel to an FSScrollPane. Need to create a BufferedImage from your XML and CSS? Use our Graphics2DRenderer in the same package, with one method call--renderToImage(). The new simple package clears the decks and puts you in control of your rendering.

How to Help Us

Please download and try the new code out. There are many improvements since our last release, R4, and our test pages are looking better and better--and rendering faster. A lot of work still to be done, and this is where you can help. Join our mailing lists by going to https://xhtmlrenderer.dev.java.net/servlets/ProjectMailingListList. The users mailing list is a good place to start if you just want to ask questions and join the discussion. You can also request an observer role by logging in to java.net and going to our home page at https://xhtmlrenderer.dev.java.net/; as an observer, you can add issues to our issue tracker at https://xhtmlrenderer.dev.java.net/servlets/ProjectIssues.

You can also send us samples--we want to see what neat things you're doing with Flying Saucer. Send us pages!

Installation

Download our release. Right now we're bundling this as two JAR files:

flying-saucer-binary-R5pre1.zip - just the binaries, no source

Start with the flying-saucer-binary-R5pre1.zip. Unpack the ZIP into your chosen target directory. Then adjust your CLASSPATH, and add core-renderer-R5pre1.jar and cssparser-0-9-4.jar. That's all!

Sample Applications

If you want to see how the code fits into a whole Swing application, take a look at our simple, but complete, "browser". This is not a complete browser by any means, but shows how you might build a browser with navigation controls and history. To run the browser, add fs-browser.jar to your CLASSPATH, then run org.xhtmlrenderer.demo.browser.BrowserStartup.

Renderer Configuration

Flying Saucer loads a configuration file from resources/conf/xhtmlrenderer.conf. A default version of this is packaged in the core-renderer JAR file. There are docs in the shipping version. You can modify that version and re-pack it in the JAR, or include a different version earlier in your CLASSPATH. You can also leave the default version alone and override any of the properties by writing a text file with new property assignments (propname = value) and saving it in your user home directory, under .flyingsaucer/local.xhtmlrenderer.conf.

Properties are loaded statically during the first execution of any of the Flying Saucer classes, and kept in memory until restart.

CSS Default Stylesheet

Flying Saucer ships with default CSS styles for all XHTML elements, following samples provided by the W3C. This default CSS file is packaged in the JAR under /resources/css/default.css. You can write your own and specify its location in the FS configuration file (see above). Be careful when changing this file--it's meant to render pages with no styling with a reasonable look and layout. Don't break anything!

• The Basics: Showing a Page
• Getting control of loading data - UserAgentCallback
• Handling different document types - NamespaceHandler

The Basics: Showing a Page

If you just want to show a webpage in your application then start with the XHTMLPanel, in org.xhtmlrenderer.swing. Here is a simple example:

import javax.swing.*;
import org.xhtmlrenderer.simple.XHTMLPanel;
public class test {
   public static void main(String[] args) throws Exception {
       
      XHTMLPanel panel = new XHTMLPanel();
      panel.setDocument("test.xhtml");
   
      JScrollPane scroll = new JScrollPane(panel);
   
      JFrame frame = new JFrame();
      frame.getContentPane().add(scroll);
      frame.pack();
      frame.setSize(400,400);
      frame.setVisible(true);
   }   
}

First create an XHTMLPanel and set it's preferred size. Call setDocument() to set the path of the xhtml file that should be displayed (relative to the current working directory). Then drop it into a JScrollPane and add the pane to a JFrame.

To show a css-styled xml document with no default css, use the org.xhtmlrender.swing.BasicPanel instead