src/documentation/content/xdocs/dev/design/extending.xml - xmlgraphics-fop - Git at Google

 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <!-- $Id$ -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">

 <document>
   <header>
     <title>Apache™ FOP Design: Extensions</title>
     <version>$Revision$</version>
     <authors>
       <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
     </authors>
   </header>

     <body>
 <section id="intro">
   <title>Introduction</title>
 <p>
 Apache™ FOP provides an extension mechanism to add extra functionality. There
 are a number of different types of extensions that apply to different
 steps when converting FO into the rendered output.
   </p>
   </section>
 <section>
   <title>Extensions</title>
   <p>
 SVG Graphic - This applies to svg and any other xml document that
 can be converted into svg in the output. All that is required is
 the element mapping for the xml and a converter that changes the
 document into svg. This conversion is done in the FO Tree. The
 conversion is done by the top level element of the namespace
 or in the case of an external image a Converter.
   </p>
   <p>
 XML Document - Instead of converting the document into svg it
 can be passed directly to the renderer. The renderer will need
 to have a handler for the xml document. This handler can add
 information directly to the output document.
   </p>
   <p>
 Output Document - This is used to add document level information
 to the output result. Such an extension will set information that
 is passed to the output document. The area tree handles these
 extensions and passs along the information to the renderer.
 The extension may contain resolveable objects. The extension
 can be passed to the renderer once resolve either immediately,
 after the next page or at the end of the document. This is so that
 the extension can be handled according to other associated data.
   </p>
   <p>
 FO Area - This is where an extension creates an normal or extended
 area in the Area Tree. This is useful when the normal FO objects
 cannot create the area in the way that is needed.
   </p>
   <p>
 Resolveable - In some cases it may require information to be
 resolved for information such as page numbers. This can apply
 to the XML Document, FO Area or output document extensions.
    </p>
   <ul>
 <li>Add a string ['(Continued)'] to a table header if the table spans
 multiple pages. These tables are part of the content and can start
 anywhere in the page.</li>
   <li>Separate page number display for a subsection. ie. - master document
 is page 4 of 7, but subsection is page 2 of 3.</li>
    </ul>
 </section>
 <section>
   <title>Examples</title>
   <p>
 Plan - The plan extension is a simple SVG graphic extension.
 Given a plan document either inside an InstreamForeignObject
 or as an external graphic, it converts the plan document into
 an svg graphic. The svg graphic is then passed through the
 Area Tree to the Renderer. The Renderer then renders the svg
 graphic as normal.
    </p>
   <p>
 PDF Outline - This is output document extension. If rendering to
 pdf and this extensionis used then the bookmark information is
 passed to the pdf document. This information is then set on the
 document.
    </p>
   <p>
 PDF Additions - This can be done with an XML Document extension.
 A simple xml document is defined that provides the appropriate
 information. When the document is rendered a handler converts the
 document into PDF markup.
    </p>
   <p>
 For example:</p>
 <source><![CDATA[<my:script-link script="app.execMenuItem('AcroSrch:Query');">
 Search
 </my:script-link>]]></source>
 <p>
 to result in a text box referencing the following PDF action:</p>
 <source><![CDATA[<<
 /S /JavaScript
 /JS (app.execMenuItem("AcroSrch:Query");)
 >>]]></source>

 </section>
     <section id="status">
       <title>Status</title>
       <section id="status-todo">
         <title>To Do</title>
       </section>
       <section id="status-wip">
         <title>Work In Progress</title>
         <ul>
           <li>mathml extension</li>
           <li>another xml -&gt; svg extension</li>
           <li>svg text normal text if that can be handled otherwise stroked this is done automatically</li>
         </ul>
       </section>
       <section id="status-complete">
         <title>Completed</title>
         <ul>
           <li>svg now in an xml handler, FOP can be used without batik</li>
           <li>bookmark extension improved a bit - changed bookmark extension, now requires a wrapping element bookmark</li>
         </ul>
       </section>
     </section>
     </body>
 </document>
	<?xml version="1.0" encoding="UTF-8" standalone="no"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<!-- $Id$ -->
	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">

	<document>
	<header>
	<title>Apache™ FOP Design: Extensions</title>
	<version>$Revision$</version>
	<authors>
	<person name="Keiron Liddle" email="keiron@aftexsw.com"/>
	</authors>
	</header>

	<body>
	<section id="intro">
	<title>Introduction</title>
	<p>
	Apache™ FOP provides an extension mechanism to add extra functionality. There
	are a number of different types of extensions that apply to different
	steps when converting FO into the rendered output.
	</p>
	</section>
	<section>
	<title>Extensions</title>
	<p>
	SVG Graphic - This applies to svg and any other xml document that
	can be converted into svg in the output. All that is required is
	the element mapping for the xml and a converter that changes the
	document into svg. This conversion is done in the FO Tree. The
	conversion is done by the top level element of the namespace
	or in the case of an external image a Converter.
	</p>
	<p>
	XML Document - Instead of converting the document into svg it
	can be passed directly to the renderer. The renderer will need
	to have a handler for the xml document. This handler can add
	information directly to the output document.
	</p>
	<p>
	Output Document - This is used to add document level information
	to the output result. Such an extension will set information that
	is passed to the output document. The area tree handles these
	extensions and passs along the information to the renderer.
	The extension may contain resolveable objects. The extension
	can be passed to the renderer once resolve either immediately,
	after the next page or at the end of the document. This is so that
	the extension can be handled according to other associated data.
	</p>
	<p>
	FO Area - This is where an extension creates an normal or extended
	area in the Area Tree. This is useful when the normal FO objects
	cannot create the area in the way that is needed.
	</p>
	<p>
	Resolveable - In some cases it may require information to be
	resolved for information such as page numbers. This can apply
	to the XML Document, FO Area or output document extensions.
	</p>
	<ul>
	<li>Add a string ['(Continued)'] to a table header if the table spans
	multiple pages. These tables are part of the content and can start
	anywhere in the page.</li>
	<li>Separate page number display for a subsection. ie. - master document
	is page 4 of 7, but subsection is page 2 of 3.</li>
	</ul>
	</section>
	<section>
	<title>Examples</title>
	<p>
	Plan - The plan extension is a simple SVG graphic extension.
	Given a plan document either inside an InstreamForeignObject
	or as an external graphic, it converts the plan document into
	an svg graphic. The svg graphic is then passed through the
	Area Tree to the Renderer. The Renderer then renders the svg
	graphic as normal.
	</p>
	<p>
	PDF Outline - This is output document extension. If rendering to
	pdf and this extensionis used then the bookmark information is
	passed to the pdf document. This information is then set on the
	document.
	</p>
	<p>
	PDF Additions - This can be done with an XML Document extension.
	A simple xml document is defined that provides the appropriate
	information. When the document is rendered a handler converts the
	document into PDF markup.
	</p>
	<p>
	For example:</p>
	<source><![CDATA[<my:script-link script="app.execMenuItem('AcroSrch:Query');">
	Search
	</my:script-link>]]></source>
	<p>
	to result in a text box referencing the following PDF action:</p>
	<source><![CDATA[<<
	/S /JavaScript
	/JS (app.execMenuItem("AcroSrch:Query");)
	>>]]></source>

	</section>
	<section id="status">
	<title>Status</title>
	<section id="status-todo">
	<title>To Do</title>
	</section>
	<section id="status-wip">
	<title>Work In Progress</title>
	<ul>
	<li>mathml extension</li>
	<li>another xml -> svg extension</li>
	<li>svg text normal text if that can be handled otherwise stroked this is done automatically</li>
	</ul>
	</section>
	<section id="status-complete">
	<title>Completed</title>
	<ul>
	<li>svg now in an xml handler, FOP can be used without batik</li>
	<li>bookmark extension improved a bit - changed bookmark extension, now requires a wrapping element bookmark</li>
	</ul>
	</section>
	</section>
	</body>
	</document>