<?xml version="1.0" encoding="UTF-8"?>
<!--
  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: extensions.xml 1298724 2012-03-09 07:55:31Z cbowditch $ -->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">

<document>
  <header>
    <title>Apache™ FOP Development: Adding an Extension</title>
    <version>$Revision: 1298724 $</version>
  </header>
  <body>
    <section id="overview">
      <title>Overview</title>
      <p>For documentation of standard Apache™ FOP extensions, see the <link href="../trunk/extensions.html">User FOP Extensions</link> document.</p>
      <p>
If the default funtionality of FOP needs to be extended for
some reason then you can write an extension.
            </p>
            <p>There are three types of extensions possible:</p>
            <ul>
              <li>An output document extension such as the PDF bookmarks</li>
              <li>an instream-foreign-object extensions such as SVG</li>
              <li>an fo extension that creates an area in the area tree where normal xsl:fo is not possible</li>
            </ul>
          </section>
          <section id="adding">
            <title>Adding Your Own</title>
            <p>
To add your own extension you need to do the following things.
</p>
        <ol>
          <li>Write code that implements your extension functionality. The easiest place to
start is by looking at the code in org.apache.fop.fo.extensions, and by looking at the examples in the <code>examples</code> directory.</li>
          <li>Create a class that extends the abstract org.apache.fop.fo.ElementMapping class. ElementMapping is a hashmap of all of the elements in a particular namespace, which makes it easier for FOP to create a different object for each element.
ElementMapping objects are static to save on memory.
They are loaded by FOP when parsing starts to validate input.</li>
          <li>Create the following file: "/META-INF/services/org.apache.fop.fo.ElementMapping", which should contain the fully qualified classname of your ElementMapping implementation class.</li>
          <li>Create a jar file containing all of the above files.</li>
          <li>Create your XSL-FO file with the extra XML data embedded in the file with the
correct name space.
The examples for SVG and pdfoutline.fo show how this can be done.
The pdf documents on the FOP site use this extension.
See also <link href="../examples.html">Examples</link> for more examples.</li>
          <li>Put your jar file in the classpath</li>
          <li>Run FOP using your XSL-FO file as input.</li>
        </ol>
    </section>
  </body>
</document>