include. include/common-defines.inc
define. title The ${fs} User's Guide
define. headAppend
define. style
#toc {
font-size: 18pt;
text-align: center;
}
.printOnly, #footer {
display: none;
}
h1{text-align: center;}. The ${fs} User's Guide
divStart(printOnly){ padding-top: 75px; }.
p{font-size: 10pt; text-align: center}. _Getting Started with ${fs}_
p{font-size: 12pt; text-align: center}. Release R8
p{font-size: 12pt; text-align: center}. April 2009
divEnd.
divStart(#footer).
${fs} Release R8 User's Guide
divEnd.
p(#toc){-fs-page-sequence: start;}. Table of Contents
toc. 2 4 #
h2. Document History
Updates to this document:
* 18-04-2009: Final copy-edit for release R8.
* 21-03-2009: Updated for release R8
h2. An Introduction to ${fs}
h3(fs_heading). What it is
${fs} 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 be interested in re-using their knowledge of web layout, 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, which means ${fs} can render most XHTML out of the box with decent results.
Internally, ${fs} 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.
As of release R8, ${fs} includes a handful of features from the CSS 3 specification, which are particularly useful in printed output; these include named pages, margin boxes and running elements.
h3(fs_heading). What it does
${fs} takes XML and CSS as input, where the CSS might be embedded in the document, or linked from it, lays it out, and renders it. The principle output targets are GUI interfaces via a Swing JPanel, and PDF; it can also render to image formats, e.g. render the page and save as an image. There is experimental support for output to SWT.
If rendering to a GUI, hyperlinks are clickable so you can navigate between pages. As with HTML, you can also render forms, capture output, and create interactive applications. In a GUI, ${fs} 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, ${fs} 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 using the print media qualifier. For PDF output we rely on the ${itext} library to generate PDF. Note that ${fs} 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
${fs} 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. ${fs} 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:
* generating PDF on-the-fly for immediate download on a website
* 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 Feedbook 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 ${fs} cannot do for you. This list applies to the current release when this document was written, R8; when in doubt, please contact us on our mailing list.
Limitations:
* Resource loading is single-threaded and occurs inline with layout. There are extension points where you may insert background loading.
* 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 or "street" HTML, although there are several open source Java HTML cleaners of varying quality available. We render well-formed XML; XHTML is a well-formed XML document which uses a special set of tags. 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 or similar library and hope for the best. But without a bunch of work, you won't be able to use ${fs} 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. This could probably be added, at least for simple cases (e.g. JS that doesn't modify the DOM) by hooking in calls to the Rhino JS implementation.
* 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 ${fs} project, realized that writing a fully capable HTML browser component (like Firefox's Gecko engine, or WebKit) 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 code it up in a reasonable amount of time. So it's not impossible to add scripting, DHTML, or plugin support to ${fs}, 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
${fs} itself is licensed under the "GNU Lesser General Public License":http://www.gnu.org/copyleft/lesser.html. You can use ${fs} 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.
${fs} 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 ${fs}
${fs} 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
As a rule, we try to limit our dependencies on external libraries to keep the download size to a minimum.
${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. As of release R8, we target the ${itext} 2.x API.
${fs} 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 exist in earlier ${fs} releases--we used to use the SteadyState CSS parser--so in principle, a different CSS parser could be used.
Most of ${fs} 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@ in your CLASSPATH. If you want PDF output, add @${itext.jar}@. You also need an XML parser to be in your classpath, but this already included in the JDK.
To summarize, the easiest CLASSPATH to set is:
* @core-renderer.jar@ (required)
* @${itext.jar}@
h3(fs_heading). Sample Applications
toc. 4 4 *
h4(fs_heading). The Browser
The ${fs} 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 ${fs} in a "real" Java GUI 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 export the current page to PDF using File/Export PDF.
You can use Ctrl-N/Ctrl-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 ${fs} 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 and render 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 Swing @JMenuItem'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 from older open source projects. Your mileage may vary with each one, as there is really no active work in formatting DocBook XML directly via CSS.
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 ${fs} 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 (CSS block-equivalent) 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 ${fs}
h3(fs_heading). Important Concepts
The ${fs} 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).
${fs} includes pre-built implementations of @NamespaceHandler@ for plain XML, for 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 directly.
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 ${fs} as the UI component rendering a document.
In ${fs}, 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. Only block-level (or equivalent) elements are replaced; see the ${css21}, chapter 9, for example 9.2, for details. The most obvious use for replaced elements 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, a Swing @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 @
${fs} 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 be interested in re-using their knowledge of web layout, 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, which means ${fs} can render most XHTML out of the box with decent results.
Internally, ${fs} 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.
As of release R8, ${fs} includes a handful of features from the CSS 3 specification, which are particularly useful in printed output; these include named pages, margin boxes and running elements.
h3(fs_heading). What it does
${fs} takes XML and CSS as input, where the CSS might be embedded in the document, or linked from it, lays it out, and renders it. The principle output targets are GUI interfaces via a Swing JPanel, and PDF; it can also render to image formats, e.g. render the page and save as an image. There is experimental support for output to SWT.
If rendering to a GUI, hyperlinks are clickable so you can navigate between pages. As with HTML, you can also render forms, capture output, and create interactive applications. In a GUI, ${fs} 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, ${fs} 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 using the print media qualifier. For PDF output we rely on the ${itext} library to generate PDF. Note that ${fs} 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
${fs} 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. ${fs} 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:
* generating PDF on-the-fly for immediate download on a website
* 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 Feedbook 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 ${fs} cannot do for you. This list applies to the current release when this document was written, R8; when in doubt, please contact us on our mailing list.
Limitations:
* Resource loading is single-threaded and occurs inline with layout. There are extension points where you may insert background loading.
* 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 or "street" HTML, although there are several open source Java HTML cleaners of varying quality available. We render well-formed XML; XHTML is a well-formed XML document which uses a special set of tags. 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 or similar library and hope for the best. But without a bunch of work, you won't be able to use ${fs} 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. This could probably be added, at least for simple cases (e.g. JS that doesn't modify the DOM) by hooking in calls to the Rhino JS implementation.
* 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 ${fs} project, realized that writing a fully capable HTML browser component (like Firefox's Gecko engine, or WebKit) 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 code it up in a reasonable amount of time. So it's not impossible to add scripting, DHTML, or plugin support to ${fs}, 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
${fs} itself is licensed under the "GNU Lesser General Public License":http://www.gnu.org/copyleft/lesser.html. You can use ${fs} 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.
${fs} 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 ${fs}
${fs} 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
As a rule, we try to limit our dependencies on external libraries to keep the download size to a minimum.
${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. As of release R8, we target the ${itext} 2.x API.
${fs} 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 exist in earlier ${fs} releases--we used to use the SteadyState CSS parser--so in principle, a different CSS parser could be used.
Most of ${fs} 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@ in your CLASSPATH. If you want PDF output, add @${itext.jar}@. You also need an XML parser to be in your classpath, but this already included in the JDK.
To summarize, the easiest CLASSPATH to set is:
* @core-renderer.jar@ (required)
* @${itext.jar}@
h3(fs_heading). Sample Applications
toc. 4 4 *
h4(fs_heading). The Browser
The ${fs} 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 ${fs} in a "real" Java GUI 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 export the current page to PDF using File/Export PDF.
You can use Ctrl-N/Ctrl-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 ${fs} 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 and render 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 Swing @JMenuItem'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 from older open source projects. Your mileage may vary with each one, as there is really no active work in formatting DocBook XML directly via CSS.
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 ${fs} 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 (CSS block-equivalent) 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 ${fs}
h3(fs_heading). Important Concepts
The ${fs} 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).
${fs} includes pre-built implementations of @NamespaceHandler@ for plain XML, for 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 directly.
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 ${fs} as the UI component rendering a document.
In ${fs}, 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. Only block-level (or equivalent) elements are replaced; see the ${css21}, chapter 9, for example 9.2, for details. The most obvious use for replaced elements is for elements that point to content which is not itself part of the document, like images; with just an @