Mailing List Archive: svn commit: r1068306 [11/22] - in /forrest/site: docs_0_100/ docs_0_100/howto/ docs_0_100/howto/cvs-ssh/ docs_0_100/howto/multi/ docs_0_100/images/ pluginDocs/plugins_0_100/ trash/ trash/docs_0_50/ trash/docs_0

Added: forrest/site/docs_0_100/howto/howto-buildPlugin.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/howto/howto-buildPlugin.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/howto/howto-buildPlugin.html (added)
+++ forrest/site/docs_0_100/howto/howto-buildPlugin.html Tue Feb 8 09:44:46 2011
@@ -0,0 +1,1091 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>How to Build a Plugin (v0.10-dev)</title>
+<link type="text/css" href="../../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../../skin/profile.css" rel="stylesheet">
+<script src="../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<ul id="tabs">
+<li>
+<a class="unselected" href="../../index.html">Welcome</a>
+</li>
+<li>
+<a class="unselected" href="../../contrib.html">Developers</a>
+</li>
+<li class="current">
+<a class="selected" href="../../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="unselected" href="../../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="unselected" href="../../tools/index.html">Tools</a>
+</li>
+</ul>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<div id="level2tabs">
+<a class="unselected" href="../../docs_0_90/index.html">0.90 (current)</a><a class="selected" href="../../docs_0_100/index.html">0.100-dev (under development)</a><a class="unselected" href="../../docs_0_80/index.html">0.80 (past)</a>
+</div>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">0.100-dev</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_100/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/your-project.html">Using Forrest</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.3', '../../skin/')" id="menu_selected_1.1.3Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">How-To</div>
+<div id="menu_selected_1.1.3" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_100/howto/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.2', '../../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div>
+<div id="menu_1.1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/upgrading_010.html">Upgrading to 0.10-dev</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.4', '../../skin/')" id="menu_1.1.3.4Title" class="menutitle">Customize Forrest</div>
+<div id="menu_1.1.3.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/sitemap-explain.html">Sitemaps explained</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-custom-html-source.html">Custom html source</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-corner-images.html">CSS corner SVG</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.5', '../../skin/')" id="menu_1.1.3.5Title" class="menutitle">Integrate Forrest with tools</div>
+<div id="menu_1.1.3.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/catalog.html">Using DTD Catalogs</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.3.6', '../../skin/')" id="menu_selected_1.1.3.6Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">Extend Forrest</div>
+<div id="menu_selected_1.1.3.6" class="selectedmenuitemgroup" style="display: block;">
+<div class="menupage">
+<div class="menupagetitle">Build a Plugin</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/skin-package.html">Package new Skins</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8', '../../skin/')" id="menu_1.1.3.8Title" class="menutitle">Adding Documentation</div>
+<div id="menu_1.1.3.8" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8.2', '../../skin/')" id="menu_1.1.3.8.2Title" class="menutitle">Multipage HowTo</div>
+<div id="menu_1.1.3.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/howto/multi/howto-multi.html">Introduction</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/faq.html">FAQs</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.5', '../../skin/')" id="menu_1.1.5Title" class="menutitle">Background</div>
+<div id="menu_1.1.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/searching.html">Search Options in Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/locationmap.html">Locationmap</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/properties.html">Properties system</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/skins.html" title="About default skins, their naming and features">Skins</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/status-themes.html">Dispatcher versus Skins</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/cap.html">Sourcetype Action</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/validation.html">XML validation and entity resolution</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/glossary.html">Glossary</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8', '../../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.8" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.8.1', '../../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.8.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8.2', '../../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.9', '../../skin/')" id="menu_1.1.9Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.9" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/dreams.html">Dream list</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for development version v0.10-dev
+ (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+
+<div id="credit2">
+<a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>How to Build a Plugin</h1>
+<div id="front-matter">
+<div id="motd-area">
+ This is documentation for development version v0.10-dev
+ (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div class="abstract">
+ This How-To describes the steps necessary to build a plugin for Forrest.
+ Forrest uses plugins to add new input formats, output formats and to
+ change its default behaviour. Since plugins are downloaded when needed and
+ can be hosted at any location, plugin code can be developed independently
+ of Apache Forrest. This how-to describes each of the major steps in
+ creating a plugin and then works through some examples of plugin creation
+ in order to illustrate the materials.
+ </div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Intended-Audience">Intended Audience</a>
+</li>
+<li>
+<a href="#Purpose">Purpose</a>
+</li>
+<li>
+<a href="#Prerequisites">Prerequisites</a>
+</li>
+<li>
+<a href="#Steps">Steps</a>
+<ul class="minitoc">
+<li>
+<a href="#typeOfPlugin">Type of Plugin</a>
+</li>
+<li>
+<a href="#ant">Make ant available on the command-line</a>
+</li>
+<li>
+<a href="#seed">Seed a New Plugin</a>
+<ul class="minitoc">
+<li>
+<a href="#edit-template">Edit the Plugin Template</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#edit-sitemap">Edit the Plugin sitemap file(s)</a>
+<ul class="minitoc">
+<li>
+<a href="#components">Components, Actions and Resources</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#resources">Create the Necessary Resource Files</a>
+<ul class="minitoc">
+<li>
+<a href="#dtd-catalog">Entity catalog for DTDs and other resources</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#samples">Create Samples in the Documentation</a>
+</li>
+<li>
+<a href="#test">Testing a Plugin</a>
+<ul class="minitoc">
+<li>
+<a href="#Testing+During+Development">Testing During Development</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#descriptor">Managing the plugins descriptors</a>
+<ul class="minitoc">
+<li>
+<a href="#explain-descriptor">Explanation</a>
+</li>
+<li>
+<a href="#register">Register the Plugin with Apache Forrest</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#release">Deploying and Releasing a Plugin</a>
+<ul class="minitoc">
+<li>
+<a href="#explain-deploy">Explanation</a>
+</li>
+<li>
+<a href="#deploy">Deploying the Plugin</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#experimental">Experimental Functionality</a>
+<ul class="minitoc">
+<li>
+<a href="#Locationmap">Locationmap</a>
+</li>
+<li>
+<a href="#Dispatcher">Dispatcher</a>
+</li>
+<li>
+<a href="#Plugin+Properties">Plugin Properties</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#examples">Examples</a>
+<ul class="minitoc">
+<li>
+<a href="#input">Input Plugin</a>
+</li>
+<li>
+<a href="#output">Output Plugin</a>
+</li>
+<li>
+<a href="#internal">Internal Plugin</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#extension">Further Reading</a>
+</li>
+<li>
+<a href="#summarise">Summarise the Entire Process</a>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<a name="Intended-Audience"></a>
+<h2 class="underlined_10">Intended Audience</h2>
+<div class="section">
+<p>
+ Users needing to add additional input formats or output formats or to
+ change the operation of the Forrest internals.
+ </p>
+<div class="warning">
+<div class="label">Warning</div>
+<div class="content">
+ Please make sure that you are using forrest 0.8 or above if you want use
+ plugins. Forrest 0.6 will not work!!!
+ </div>
+</div>
+</div>
+<a name="Purpose"></a>
+<h2 class="underlined_10">Purpose</h2>
+<div class="section">
+<p>
+ This How-To will illustrate how to build a plugin, publish a plugin and
+ configure a Forrest project to use their plugin.
+ </p>
+</div>
+<a name="Prerequisites"></a>
+<h2 class="underlined_10">Prerequisites</h2>
+<div class="section">
+<p>
+ Plugin developers should have:
+ </p>
+<ul>
+
+<li>a basic knowledge of XML, XSLT and Cocoon pipelines</li>
+
+<li>a clear use-case for extending Forrest</li>
+
+<li>read
+ <a href="../../pluginDocs/plugins_0_100/pluginInfrastructure.html">Plugin Infrastructure</a>
+</li>
+
+<li>verified with the Apache Forrest developer community that the
+ required functionality does not already exist</li>
+
+</ul>
+</div>
+<a name="Steps"></a>
+<h2 class="underlined_10">Steps</h2>
+<div class="section">
+<p>
+ Here is how to proceed.
+ </p>
+<a name="typeOfPlugin"></a>
+<h3 class="underlined_5">Type of Plugin</h3>
+<p>
+ There are three types of plugin, each with a clear purpose, you must
+ first decide which <a href="../../pluginDocs/plugins_0_100/pluginInfrastructure.html">type of
+ plugin</a> you need to build.
+ </p>
+<a name="ant"></a>
+<h3 class="underlined_5">Make ant available on the command-line</h3>
+<p>
+ The following instructions rely heavily on
+ <a href="http://ant.apache.org/">Apache Ant</a> to automate some steps
+ in the process. Since ant is distributed as part of Forrest, all you
+ need to do is add Forrest's 'ant' executable directory to your system
+ path. The name of this directory is <span class="codefrag">tools/ant/bin</span> in your
+ Forrest program directory. Alternatively you can prefix all calls to ant
+ in the following instructions with the full path of the ant binary
+ directory, i.e. $FORREST_HOME/tools/ant/bin/ant
+ </p>
+<p>
+ If instead you really want to use your own version of Ant, then you will
+ need to copy forrest/lib/core/xml-commons-resolver.jar to $ANT_HOME/lib
+ directory, otherwise the building of your plugins will go across the
+ network to get the DTDs on every xml parse. Be aware that Forrest might
+ be relying on some Ant features in its version.
+ </p>
+<a name="seed"></a>
+<h3 class="underlined_5">Seed a New Plugin</h3>
+<p>
+ Regardless of the type of plugin you are building, the directory
+ structure is almost identical, as are most of the required configuration
+ files. In this How-To we will assume that you are creating a plugin in
+ the Forrest source tree. All plugins are developed in the
+ <span class="codefrag">forrest/plugins</span> directory or the
+ <span class="codefrag">forrest/whiteboard/plugins</span> directory.
+ </p>
+<p class="instruction">
+ Run the following set of commands:
+ </p>
+<pre class="code">
+ cd [path_to_forrest]/whiteboard/plugins
+ ant seedPlugin
+ </pre>
+<p>
+ The above ant target will ask you the name of the plugin and some
+ additional information such as a brief description and will build a
+ minimal plugin directory structure and configuration. You will need to
+ customise these files to build your plugin.
+ </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ Although you can name your project anything you like we do have some
+ <a href="../../pluginDocs/plugins_0_100/pluginInfrastructure.html">naming conventions</a> that we
+ recommend you follow. Plugins intended to be held at forrest.apache.org
+ must follow the naming convention.
+ </div>
+</div>
+<p>
+ You can also build your plugins from a location outside of the Forrest
+ directory structure, for example from within your own project. If you
+ don't already have one, create a plugins directory, for example:
+ </p>
+<pre class="code">
+ cd $PROJECT_HOME
+ mkdir plugins
+ </pre>
+<p>
+ Then copy $FORREST_HOME/whiteboard/plugins/build.xml to
+ $PROJECT_HOME/plugins. There are a couple of changes you now need to
+ make to the newly copied build.xml file. Open up 'build.xml' for
+ editing. You can change the project name value to something more
+ suitable.Find the property name for forrest.plugins.dir and change the
+ location to read
+ </p>
+<pre class="code">location="."</pre>
+<p class="instruction">
+ So, revised commands for $PROJECT_HOME/plugins:
+ </p>
+<pre class="code">
+ cd [path_to_project_home]/plugins
+ ant seedPlugin
+ </pre>
+<p>
+ See <a href="../../pluginDocs/plugins_0_100/pluginInfrastructure.html">Plugin Infrastructure</a> for
+ more information about the plugin directory structure and configuration
+ files.
+ </p>
+<a name="edit-template"></a>
+<h4>Edit the Plugin Template</h4>
+<p>
+ You now have a skeleton plugin project. However, it doesn't do
+ anything useful yet. Now is a good time to edit some of the files
+ provided.
+ </p>
+<p>
+ Here are some general notes:
+ </p>
+<a name="status"></a>
+<h5>status.xml</h5>
+<p>
+ This file is used to track changes to the plugin project and to
+ manage lists of things that still need to be done. At this stage you
+ should correct the <span class="codefrag">person</span> entry near the top of the
+ file. It is also a good idea to add a few key milestones in the task
+ list towards the bottom of the file.
+ </p>
+<p>
+ As you work on the plugin you should record all major changes in
+ this file so that it can then be used as a changelog for your
+ plugin.
+ </p>
+<a name="forrest-properties"></a>
+<h5>forrest.properties</h5>
+<p>
+ This file defines many configuration parameters for Forrest. It does
+ not need to be customised in most cases. However, see for more
+ details.
+ </p>
+<a name="build-xml"></a>
+<h5>build.xml</h5>
+<p>
+ If the plugin uses Java, then set the "requires-java" property to true.
+ </p>
+<a name="skinconf"></a>
+<h5>src/documentation/skinconf.xml</h5>
+<p>
+ This configures the skin for your plugins documentation.
+ Note that it is a minimal file, as most content is centrally configured for all ASF plugins.
+ Over-ride some elements if needed, e.g. see the PDF output plugin.
+ </p>
+<p>
+ If this is not and ASF-hosted plugin, then copy the skinconf.xml from a fresh
+ 'forrest seed-sample' site instead.
+ </p>
+<a name="doc"></a>
+<h5>Documentation</h5>
+<p>
+ It is also a good idea to start writing the documentation at this
+ stage. The above process created a very simple plugin documentation
+ site for you. All you have to do is add the content.
+ </p>
+<a name="hosted"></a>
+<h5>Style notes for plugins hosted at forrest.apache.org</h5>
+<p>
+ After seeding a new plugin, copy some configuration from an existing
+ plugin (e.g. org.apache.forrest.plugin.input.projectInfo). Copy
+ src/documentation/content/xdocs/images/project-logo.gif
+ and
+ src/documentation/content/xdocs/favicon.ico
+ </p>
+<a name="edit-sitemap"></a>
+<h3 class="underlined_5">Edit the Plugin sitemap file(s)</h3>
+<p>
+ The plugin <span class="codefrag">xmap</span> file is a Cocoon sitemap that is mounted at
+ a strategic place in the Forrest pipeline. It is in this file that you
+ will instruct Forrest how to operate. An input plugin must provide a
+ <span class="codefrag">input.xmap</span> file, an output plugin must provide a
+ <span class="codefrag">output.xmap</span> file, whilst an internal plugin provides a
+ <span class="codefrag">internal.xmap</span> file. In addition, an input plugin may
+ provide a <span class="codefrag">resources.xmap</span> file to allow the plugin to handle
+ items such as JavaScript files.
+ </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ All input plugins should allow the original source to be retrieved by
+ requesting the document with a <span class="codefrag">*.source.xml</span> extension. So
+ you should ensure that you provide such a match.
+ </div>
+</div>
+<p>
+ It is beyond the scope of this How-To to give details about how to build
+ your plugins XMap. See the <a href="../../docs_0_100/sitemap-ref.html">Sitemap
+ Reference</a> for general information. See also
+ <a href="../../pluginDocs/plugins_0_100/pluginInfrastructure.html">Plugin Infrastructure</a> for some
+ hints and tips on creating plugin sitemaps. In addition, as with all
+ development work on Forrest, you will find the
+ <a href="../../mail-lists.html#forrest-dev">developer mailing list</a> a very
+ good resource (check the archives before posting, please).
+ </p>
+<a name="components"></a>
+<h4>Components, Actions and Resources</h4>
+<p>
+ If your plugin uses any components (i.e. generators, transformers or
+ serializers), actions or resources they must be defined in either the
+ xmap for this plugin or one of its parents. The parents of an
+ <span class="codefrag">input.xmap</span> are <span class="codefrag">sitemap.xmap</span> and
+ <span class="codefrag">forrest.xmap</span>, whilst the parent of both
+ <span class="codefrag">output.xmap</span> and <span class="codefrag">internal.xmap</span> are
+ <span class="codefrag">sitemap.xmap</span>
+
+</p>
+<p>
+ If you want to use the realpath where the sitemap.xmap of your plugin
+ resides then you need to use
+ <span class="codefrag">{forrest:forrest.plugins}/PLUGIN_NAME</span> instead of
+ <span class="codefrag">{realpath:/}</span>.
+ </p>
+<p>
+ See the examples below for more details.
+ </p>
+<a name="resources"></a>
+<h3 class="underlined_5">Create the Necessary Resource Files</h3>
+<div class="fixme">
+<div class="label">Fixme (open)</div>
+<div class="content">
+ Discuss the XSL files and other such resources
+ </div>
+</div>
+<a name="dtd-catalog"></a>
+<h4>Entity catalog for DTDs and other resources</h4>
+<p>
+ If the plugin uses non-core DTDs and other entities, then add them to
+ the <span class="codefrag">resources/schema</span> directory and configure a
+ catalog.xcat file. The best way to do this is to copy an example from
+ another plugin (e.g. "listLocations" has a simple example; "glossary"
+ has a more complex example) and edit it to suit.
+ </p>
+<a name="samples"></a>
+<h3 class="underlined_5">Create Samples in the Documentation</h3>
+<p>
+ Plugin documentation should provide (as a minimum) an index page that
+ provides an overview and a set of samples that demonstrate the
+ functionality of the plugin. Typically these samples will be provided in
+ a <span class="codefrag">samples</span> subdirectory in the plugin documentation and will
+ be referenced from both <span class="codefrag">site.xml</span> and <span class="codefrag">tabs.xml</span>
+ configuration files.
+ </p>
+<p>
+ Try to provide a sample for all the major functions of your plugin and
+ document any configuration that is available.
+ </p>
+<a name="test"></a>
+<h3 class="underlined_5">Testing a Plugin</h3>
+<p>
+ Since your documentation for the plugin illustrates all of its
+ functionality, you can use that site for testing the plugin. However,
+ you must first deploy in your local install of Forrest. Each plugin
+ contains a buildfile that includes a <span class="codefrag">test</span> target. This
+ target, by default, builds the documentation for your plugin.
+ </p>
+<p class="instruction">
+ Run the command <span class="codefrag">ant test</span> in the plugins directory.
+ </p>
+<p>
+ Of course, the build should complete without errors.
+ </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ You can also use <span class="codefrag">forrest run</span> to interactively examine your
+ documentation (point your browser at
+ <a href="http://localhost:8888">http://localhost:8888</a>).
+ </div>
+</div>
+<p>
+ It is also a really good idea to build proper tests for your plugins
+ using a suitable testing framework, for example,
+ <a href="http://webtest.canoo.com/" rel="nofollow">WebTest</a>. We recommend that you
+ extend the <span class="codefrag">test</span> target in your plugins build file because
+ this target is also used when performing integration tests on Forrest.
+ In addition, we recommend that you use the samples in your documentation
+ for your tests, this way you are documenting your plugin at the same
+ time as writing your tests.
+ </p>
+<p>
+ Ensure that your sitemaps are robust and handle matches for files in
+ sub-directories, as well as those at the root level.
+ </p>
+<a name="Testing+During+Development"></a>
+<h4>Testing During Development</h4>
+<p>
+ In the current plugin system plugins are not used from their src
+ directories, they must first be deployed locally. To do this run the
+ command <span class="codefrag">$FORREST_HOME/tools/ant/bin/ant local-deploy</span>
+
+</p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ The "test" target will do this deployment automatically for you. You
+ need only run it manually if you wish to test the plugin whilst
+ editing content in a live Forrest instance.
+ </div>
+</div>
+<p>
+ When you make changes to the plugin while doing its development, then
+ you need to do the local-deploy again for those changes to have
+ effect.
+ </p>
+<p>
+ In most cases you can locally deploy a plugin without having to
+ restart Forrest. However, if your plugin changes any configuration
+ files in the <span class="codefrag">conf</span> directory you will, most likely, have
+ to restart Forrest to see these changes.
+ </p>
+<a name="descriptor"></a>
+<h3 class="underlined_5">Managing the plugins descriptors</h3>
+<a name="explain-descriptor"></a>
+<h4>Explanation</h4>
+<p>
+ The files plugins/plugins.xml and
+ whiteboard/plugins/whiteboard-plugins.xml are the "Plugins Descriptor"
+ files. Each plugin is described with its name, purpose, location, and
+ version information. These descriptors are deployed to the forrest
+ website.
+ </p>
+<p>
+ Each plugin has a build.xml file which defines its version
+ information. Please keep that synchronised with the plugins.xml files.
+ Later
+ <a href="http://issues.apache.org/jira/browse/FOR-533">FOR-533</a>
+ will generate this from the various build.xml files.
+ </p>
+<p>
+ The Apache Forrest committers manage these files in SVN and publish
+ them as needed. Here are some notes.
+ </p>
+<p>
+ When a plugin gains new functionality, then it will be dependent on a
+ more recent version of Forrest. Deploy the plugin one final time
+ before implementing the new work. For example, if current Forrest release is
+ 0.7 then ...
+ </p>
+<ul>
+
+<li>Review the docs and ensure any version numbers in text are "0.7"</li>
+
+<li>Edit the plugin's descriptors and build.xml file to ensure that the "forrestVersion" is 0.7 and that the "version" is appropriate. </li>
+
+<li>Ensure that the "website" parameter includes "pluginDocs/plugins_0_70"</li>
+
+<li>Edit status.xml to ensure that the changes notes are complete.</li>
+
+<li>Do <span class="codefrag">'ant deploy'</span> and <span class="codefrag">'ant release'</span> again
+ to get any final minor changes deployed.</li>
+
+</ul>
+<p>
+ Now the plugin gains functionality that binds it to 0.8-dev (e.g.
+ converted to use locationmap) so ...
+ </p>
+<ul>
+
+<li>Review the docs and ensure any version numbers in text are
+ "0.8"</li>
+
+<li>Edit the plugin's descriptors and build.xml file to ensure that the "forrestVersion" is
+ 0.8 and that the "version" is incremented. </li>
+
+<li>Ensure that the "website" parameter includes "pluginDocs/plugins_0_80"</li>
+
+<li>Edit status.xml to add a new section and set the release date to "not-yet-released".
+ Start adding changes notes and the new functionality.</li>
+
+<li>When ready do the plugin release process, and do <span class="codefrag">'ant deploy'</span> and <span class="codefrag">'ant release'</span> etc.</li>
+
+</ul>
+<a name="register"></a>
+<h4>Register the Plugin with Apache Forrest</h4>
+<div class="fixme">
+<div class="label">Fixme (open)</div>
+<div class="content">
+ Describe making a request of Forrest devs for inclusion.
+ In the meantime just ask on the dev mail list.
+ </div>
+</div>
+<a name="release"></a>
+<h3 class="underlined_5">Deploying and Releasing a Plugin</h3>
+<a name="explain-deploy"></a>
+<h4>Explanation</h4>
+<div class="fixme">
+<div class="label">Fixme (open)</div>
+<div class="content">
+ Describe "deploy" and "release" and when/how to use each.
+ In the meantime, there are some other useful mail threads and notes:
+ </div>
+</div>
+<ul>
+
+<li>
+
+<a href="http://s.apache.org/ou">Re: plugins deployment problem</a>
+ which has a good description of how the system works.
+ </li>
+
+<li>a text document at $FORREST_HOME/plugins/RELEASE_PROCESS.txt</li>
+
+</ul>
+<a name="deploy"></a>
+<h4>Deploying the Plugin</h4>
+<p>
+ To deploy the plugin so that others can use it, it must be made
+ available as a zip from the URL indicated in the
+ <span class="codefrag">plugins.xml</span> file. The plugins build file provides targets
+ to assist with this task.
+ </p>
+<p class="instruction">
+ To deploy a plugin simply run the command <span class="codefrag">ant deploy</span> from
+ within the plugin directory.
+ </p>
+<p>
+ This command will, by default, deploy to the Apache Forrest web site.
+ In order to do this you need commit access to Forrest. If you want to
+ deploy your plugin to a different location you can build the zip of
+ your plugin with <span class="codefrag">ant dist</span> and then copy the zip file from
+ <span class="codefrag">build/dist</span> to wherever you intend to host the plugin.
+ </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ Running this command on any plugin will also deploy any changes to the
+ <span class="codefrag">plugins.xml</span> file. If you are deploying to your own
+ website you will have to request changes to the
+ <span class="codefrag">plugins.xml</span> and ask the Forrest committers to publish the
+ new document.
+ </div>
+</div>
+<div class="warning">
+<div class="label">Warning</div>
+<div class="content">
+ Running the <span class="codefrag">deploy</span> or <span class="codefrag">dist</span> targets will
+ always run the <span class="codefrag">test</span> target first. This is to ensure that
+ you only deploy working plugins. This adds a little time to the deploy
+ cycle, but we feel the peace of mind is worth it.
+ </div>
+</div>
+<a name="experimental"></a>
+<h3 class="underlined_5">Experimental Functionality</h3>
+<div class="warning">
+<div class="label">Warning</div>
+<div class="content">
+ This section describes functionality that is considered experimental.
+ This functionality may be defective and is not part of the official
+ release at this time, use at your own risk. If you do choose to use this
+ functionality then we recomend that you join the Forrest dev list in
+ order to keep abreast of the changes as they occur.
+ </div>
+</div>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ For an example of each of these features in use see the
+ <span class="codefrag">org.apache.forrest.internal.NoteTaking</span> plugin.
+ </div>
+</div>
+<a name="Locationmap"></a>
+<h4>Locationmap</h4>
+<p>
+ Plugins can use the Forrest locationmap to expose resources to your
+ project and other plgins. To use this functionality add your
+ <span class="codefrag">locationmap.xml</span> file to the root of the plugin directory.
+ </p>
+<p>
+ We have an
+ <a href="http://issues.apache.org/jira/browse/FOR-200">issue</a> for
+ the status of locationmap development.
+ </p>
+<a name="Dispatcher"></a>
+<h4>Dispatcher</h4>
+<p>
+ Dispatcher (previous codename Forrest Views) is the collective name
+ for the various pieces of functionality that are intended to replace
+ skins in the future. They allow for a much more configurable system of
+ defining the contents and look and feel of a site.
+ </p>
+<p>
+ Plugins can expose contracts, resources and panels for use in
+ structurer files used within Dispatcher-based sites. In order to do
+ this you should develop your contracts as normal and place them in
+ <span class="codefrag">PLUGIN_HOME/resources/themes</span>. However, this, by itself,
+ is not sufficient to export your contracts. You will also need to add
+ the following match to your plugin's <span class="codefrag">locationmap.xml</span>
+ file:
+ </p>
+<pre class="code">
+
+ <match pattern="resolvePluginContract.*.**">
+ <select type="exists">
+ <location src="{forrest:forrest.plugins}/PLUGIN_NAME/resources/themes/{properties:dispatcher.theme}/{1}/{2}.ft" />
+ <location src="{forrest:forrest.plugins}/PLUGIN_NAME/resources/themes/{properties:dispatcher.fallback.theme}/{1}/{2}.ft" />
+ </select>
+ </match>
+ <match pattern="resolvePluginThemes.*.**">
+ <select type="exists">
+ <location src="{forrest:forrest.plugins}/PLUGIN_NAME/resources/themes/{properties:dispatcher.theme}/{1}/{2}.{1}" />
+ <location src="{forrest:forrest.plugins}/PLUGIN_NAME/resources/themes/{properties:dispatcher.fallback.theme}/{1}/{2}.{1}" />
+ </select>
+ </match>
+ <match pattern="resolvePluginPanels.**">
+ <select type="exists">
+ <location src="{forrest:forrest.plugins}/PLUGIN_NAME/resources/themes/{properties:dispatcher.theme}/panels/{1}.panel.xml" />
+ <location src="{forrest:forrest.plugins}/PLUGIN_NAME/resources/themes/{properties:dispatcher.fallback.theme}/panels/{1}.panel.xml" />
+ </select>
+ </match>
+ </pre>
+<p>
+ Of course, you should replace <span class="codefrag">PLUGIN_NAME</span> with the name
+ of your plugin.
+ </p>
+<p>
+ Once Dispatcher becomes stable we will add this matches to the default
+ locationmap which is generated when you seed a new plugin, but for now
+ it must be done manually.
+ </p>
+<a name="Plugin+Properties"></a>
+<h4>Plugin Properties</h4>
+<p>
+ Plugins can define properties that each project can over-ride. For
+ more information see the issue below.
+ </p>
+<p>
+ We have an
+ <a href="http://issues.apache.org/jira/browse/FOR-588">issue</a> for
+ the status of this new configuration system.
+ </p>
+<a name="examples"></a>
+<h3 class="underlined_5">Examples</h3>
+<p>
+ This section will provide some example plugins to help illustrate the
+ steps discussed above.
+ </p>
+<a name="input"></a>
+<h4>Input Plugin</h4>
+<div class="fixme">
+<div class="label">Fixme (open)</div>
+<div class="content">
+ Discuss a simple example of an "input" plugin here.
+ </div>
+</div>
+<a name="output"></a>
+<h4>Output Plugin</h4>
+<div class="fixme">
+<div class="label">Fixme (open)</div>
+<div class="content">
+ Discuss a simple example of an "output" plugin here.
+ </div>
+</div>
+<a name="internal"></a>
+<h4>Internal Plugin</h4>
+<div class="fixme">
+<div class="label">Fixme (open)</div>
+<div class="content">
+ Discuss a simple example of an "internal" plugin here.
+ </div>
+</div>
+<a name="extension"></a>
+<h3 class="underlined_5">Further Reading</h3>
+<ul>
+
+<li>
+<a href="../../pluginDocs/plugins_0_100/pluginInfrastructure.html">Plugin Infrastructure Documentation</a> for Developers</li>
+
+<li>
+<a href="../../pluginDocs/plugins_0_100/">Plugins Documentation</a> for users</li>
+
+</ul>
+<a name="summarise"></a>
+<h3 class="underlined_5">Summarise the Entire Process</h3>
+<div class="fixme">
+<div class="label">Fixme (open)</div>
+<div class="content">
+ In a few sentences, remind the reader what they have just learned. This
+ helps to reinforce the main points of your How-To.
+ </div>
+</div>
+</div>
+<span class="version">0.4.0</span>
+</div>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+ Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+ logos are trademarks of The Apache Software Foundation.
+ </div>
+
+</div>
+</body>
+</html>

Propchange: forrest/site/docs_0_100/howto/howto-buildPlugin.html
------------------------------------------------------------------------------
svn:eol-style = native

Added: forrest/site/docs_0_100/howto/howto-corner-images.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/howto/howto-corner-images.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/howto/howto-corner-images.html (added)
+++ forrest/site/docs_0_100/howto/howto-corner-images.html Tue Feb 8 09:44:46 2011
@@ -0,0 +1,699 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>How to modify the color of generated corner images (v0.10-dev)</title>
+<link type="text/css" href="../../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../../skin/profile.css" rel="stylesheet">
+<script src="../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<ul id="tabs">
+<li>
+<a class="unselected" href="../../index.html">Welcome</a>
+</li>
+<li>
+<a class="unselected" href="../../contrib.html">Developers</a>
+</li>
+<li class="current">
+<a class="selected" href="../../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="unselected" href="../../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="unselected" href="../../tools/index.html">Tools</a>
+</li>
+</ul>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<div id="level2tabs">
+<a class="unselected" href="../../docs_0_90/index.html">0.90 (current)</a><a class="selected" href="../../docs_0_100/index.html">0.100-dev (under development)</a><a class="unselected" href="../../docs_0_80/index.html">0.80 (past)</a>
+</div>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">0.100-dev</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_100/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/your-project.html">Using Forrest</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.3', '../../skin/')" id="menu_selected_1.1.3Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">How-To</div>
+<div id="menu_selected_1.1.3" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_100/howto/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.2', '../../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div>
+<div id="menu_1.1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/upgrading_010.html">Upgrading to 0.10-dev</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.3.4', '../../skin/')" id="menu_selected_1.1.3.4Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">Customize Forrest</div>
+<div id="menu_selected_1.1.3.4" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_100/sitemap-explain.html">Sitemaps explained</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-custom-html-source.html">Custom html source</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">CSS corner SVG</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.5', '../../skin/')" id="menu_1.1.3.5Title" class="menutitle">Integrate Forrest with tools</div>
+<div id="menu_1.1.3.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/catalog.html">Using DTD Catalogs</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.6', '../../skin/')" id="menu_1.1.3.6Title" class="menutitle">Extend Forrest</div>
+<div id="menu_1.1.3.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-buildPlugin.html">Build a Plugin</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/skin-package.html">Package new Skins</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8', '../../skin/')" id="menu_1.1.3.8Title" class="menutitle">Adding Documentation</div>
+<div id="menu_1.1.3.8" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8.2', '../../skin/')" id="menu_1.1.3.8.2Title" class="menutitle">Multipage HowTo</div>
+<div id="menu_1.1.3.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/howto/multi/howto-multi.html">Introduction</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/faq.html">FAQs</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.5', '../../skin/')" id="menu_1.1.5Title" class="menutitle">Background</div>
+<div id="menu_1.1.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/searching.html">Search Options in Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/locationmap.html">Locationmap</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/properties.html">Properties system</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/skins.html" title="About default skins, their naming and features">Skins</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/status-themes.html">Dispatcher versus Skins</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/cap.html">Sourcetype Action</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/validation.html">XML validation and entity resolution</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/glossary.html">Glossary</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8', '../../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.8" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.8.1', '../../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.8.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8.2', '../../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.9', '../../skin/')" id="menu_1.1.9Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.9" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_100/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/dreams.html">Dream list</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_100/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for development version v0.10-dev
+ (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+
+<div id="credit2">
+<a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>How to modify the color of generated corner images</h1>
+<div id="front-matter">
+<div id="motd-area">
+ This is documentation for development version v0.10-dev
+ (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div class="abstract">
+ This How-To describes how to modify the corner images that appear in the
+ menu and tabs of the skins.
+ </div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Intended-Audience">Intended Audience</a>
+</li>
+<li>
+<a href="#Purpose">Purpose</a>
+</li>
+<li>
+<a href="#Prerequisites">Prerequisites</a>
+</li>
+<li>
+<a href="#Steps">Steps</a>
+<ul class="minitoc">
+<li>
+<a href="#css-files">Understand how corner images are named (the contract)</a>
+</li>
+<li>
+<a href="#skinconfig">Modifying the skinconf.xml of your project</a>
+</li>
+<li>
+<a href="#css_modify">Modifying .css files</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Feedback">Feedback</a>
+</li>
+</ul>
+</div>
+</div>
+<a name="Intended-Audience"></a>
+<h2 class="underlined_10">Intended Audience</h2>
+<div class="section">
+<p>
+ Users who want to change the colors of the corner images in the output
+ html documents.
+ </p>
+<p>
+ This explanation is also useful for skin developers to understand the
+ corner image generation process.
+ </p>
+</div>
+<a name="Purpose"></a>
+<h2 class="underlined_10">Purpose</h2>
+<div class="section">
+<p>
+ Forrest renders the corner images through
+ <a href="http://www.w3.org/TR/SVG/" rel="nofollow">Scalable Vector Graphics (SVG)</a>. It
+ may be necessary to change the color of the corner images to be suitable
+ for your own skin colors.
+ </p>
+</div>
+<a name="Prerequisites"></a>
+<h2 class="underlined_10">Prerequisites</h2>
+<div class="section">
+<ul>
+
+<li>Understand how to use the skinconf.xml file to change the appearance
+ of the output documents.</li>
+
+<li>Understand how to create or modify skins by following the
+ <a href="../../docs_0_100/your-project.html">Using Forrest</a> document
+ (topic "<a href="../../docs_0_100/your-project.html#skins">Forrest skins</a>").</li>
+
+</ul>
+</div>
+<a name="Steps"></a>
+<h2 class="underlined_10">Steps</h2>
+<div class="section">
+<p>
+ The procedure outlined below provides an understanding of how corner
+ images are named (the contract) and then shows how to define new colors
+ for these images by modifying the
+ <span class="codefrag">src/documentation/skinconf.xml</span> of a project.
+ </p>
+<a name="css-files"></a>
+<h3 class="underlined_5">Understand how corner images are named (the contract)</h3>
+<p>
+ The corner images are referenced in some .css files of the above-named
+ skins; for example, in screen.css of the pelt skin:
+ </p>
+<pre class="code">
+/*Example from screen.css of pelt*/
+...
+/**
+* Round corner
+*/
+#roundtop {
+ background-image: url(images/rc-t-r-15-1body-2menu-3menu.png);
+ background-repeat: no-repeat;
+ background-position: top right;
+}
+...
+ </pre>
+<p>
+ The naming follows a contract which is described below. In general, the
+ naming looks like:
+ </p>
+<pre class="code">
+images/{$name}-{$v-orientation}-{$h-orientation}-{$size}-1{$backgroundColor}-2{$strokeColor}-3{$foregroundColor}
+ </pre>
+<p>
+ The first part
+ (<span class="codefrag">images/{$name}-{$v-orientation}-{$h-orientation}-{$size}</span>)
+ identifies which images is used and how big (width x height) it should
+ be. The second part\
+ (<span class="codefrag">-1{$backgroundColor}-2{$strokeColor}-3{$foregroundColor}</span>)
+ identifies the coloring of each portion of the image. The input
+ parameter for the second part comes from the color profile of
+ <span class="codefrag">src/documentation/skinconf.xml</span>. The second part is easily
+ identifiable through the numbering 1-2-3.
+ </p>
+<p>
+ Let us get into details:
+ </p>
+<dl>
+
+<dt>
+<span class="codefrag">images</span>
+</dt>
+
+<dd>
+ Path to the xslt that creates the corner.
+ <br>
+<span class="codefrag">images/ = {$FORREST_HOME}/main/webapp/skins/common/images/</span>
+</dd>
+
+<dt>
+<span class="codefrag">{$name}</span>
+</dt>
+
+<dd>
+ In the common skin there are two XSLT files ready for use:
+ <ul>
+
+<li>
+<span class="codefrag">rc.svg.xslt</span>: handles rounded corners
+ </li>
+
+<li>
+<span class="codefrag">dc.svg.xslt</span>: handles diagonal 45-degree corners
+ </li>
+
+</ul>
+<span class="codefrag">name = [rc|dc]</span>
+
+<br>
+<em>e.g.</em><span class="codefrag">rc</span>
+</dd>
+
+<dt>
+<span class="codefrag">{$v-orientation}</span>
+</dt>
+
+<dd>
+ Vertical orientation of the corner images (top or bottom).
+ <br>
+<span class="codefrag">v-orientation = [t|b]</span>
+
+<br>
+<em>e.g.</em><span class="codefrag">t</span>
+</dd>
+
+<dt>
+<span class="codefrag">{$h-orientation}</span>
+</dt>
+
+<dd>
+ Horizontal orientation of the corner images (left or right).
+ <br>
+<span class="codefrag">h-orientation = [l|r]</span>
+
+<br>
+<em>e.g.</em><span class="codefrag">r</span>
+</dd>
+
+<dt>
+<span class="codefrag">{$size}</span>
+</dt>
+
+<dd>
+ Pixels size of the width <strong>and</strong> height of the corner image.
+ <br>
+<span class="codefrag">size=x</span>
+
+<br>
+<em>e.g.</em><span class="codefrag">5</span>
+</dd>
+
+<dt>
+<span class="codefrag">{$backgroundColor}</span>
+</dt>
+
+<dd>
+ Any <span class="codefrag"><color name=""/></span> element in the <span class="codefrag">skinconf.xml</span> (the <span class="codefrag">value="{$color}"</span>
+ attribute will be applied).
+ <br>
+<em>e.g.</em><span class="codefrag">header</span>
+</dd>
+
+<dt>
+<span class="codefrag">{$strokeColor}</span>
+</dt>
+
+<dd>
+ Any <span class="codefrag"><color name=""/></span> element in the <span class="codefrag">skinconf.xml</span> (the <span class="codefrag">value="{$color}"</span>
+ attribute will be applied).
+ <br>
+<em>e.g.</em><span class="codefrag">searchbox</span>
+</dd>
+
+<dt>
+<span class="codefrag">{$foregroundColor}</span>
+</dt>
+
+<dd>
+ Any <span class="codefrag"><color name=""/></span> element in the <span class="codefrag">skinconf.xml</span> (the <span class="codefrag">value="{$color}"</span>
+ attribute will be applied).
+ <br>
+<em>e.g.</em><span class="codefrag">searchbox</span>
+</dd>
+
+</dl>
+<p>
+ The corner images are made by generating a dymanic
+ <a href="/skin/images/rc-t-r-50-1body-2menu-3menu.svg">svg
+ image</a> to add the colors and size. Then this svg is serialize to
+ <a href="/skin/images/rc-t-r-50-1body-2menu-3menu.png">the png
+ image</a> via the
+ <a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/serialization/SVGSerializer.html">org.apache.cocoon.serialization.SVGSerializer</a>
+ (see
+ <a href="http://cocoon.apache.org/2.1/userdocs/svg-serializer.html">docs</a>).
+ </p>
+<div class="fixme">
+<div class="label">Fixme (thorsten)</div>
+<div class="content">
+ The following link is for pure debugging reason.
+ <a href="/skin/images/rc-t-r-50-1body-2menu-3menu.test.png">test
+ png image</a> - this image is taken from the svg pipe instead of
+ directly generating it.
+ </div>
+</div>
+<a name="skinconfig"></a>
+<h3 class="underlined_5">Modifying the skinconf.xml of your project</h3>
+<p>
+ modifying the <span class="codefrag">skinconf.xml</span> of your project (by default you
+ find it at <span class="codefrag">[project-dir]/src/documentation/</span>).
+ </p>
+<p>
+ Starting about line 155 you find a <span class="codefrag"><colors></span> ...
+ <span class="codefrag"></colors></span> element with content commented-out:
+ </p>
+<pre class="code">
+<colors>
+
+
+
+
+
+</colors>
+ </pre>
+<p>
+ To modify the colors of the corner images, you can either define your
+ own <span class="codefrag"><color name=.../></span> elements or uncomment one of
+ the existing <span class="codefrag"><color name=.../></span> elements and adjust
+ the color value to your needs.
+ </p>
+<p>
+
+<em>e.g.</em>
+
+</p>
+<pre class="code">
+<color name="tab-selected" value="#FF0000"/>
+ </pre>
+<p>
+ This affects all corner images whose <span class="codefrag">{$backgroundColor}</span>,
+ <span class="codefrag">{$strokeColor}</span> or <span class="codefrag">{$foregroundColor}</span> is set to
+ <span class="codefrag">tab-selected</span>.
+ <br>
+ For example, in <span class="codefrag">screen.css</span> (of the "pelt" skin) you find:
+ </p>
+<pre class="code">
+#roundbottomsmall {
+ background-image: url(images/rc-b-r-5-1header-2tab-selected-3tab-selected.png);
+ background-repeat: no-repeat;
+ background-position: top right;
+}
+ </pre>
+<p>
+ Now the stroke color (<span class="codefrag">-2tab-selected</span>) and the foreground
+ color (<span class="codefrag">-3tab-selected</span>) are set to red (remember: we defined
+ <span class="codefrag">#FF0000</span> as the "color" value of <span class="codefrag">tab-selected</span>).
+ </p>
+<a name="css_modify"></a>
+<h3 class="underlined_5">Modifying .css files</h3>
+<p>
+ In addition to the modification of <span class="codefrag">skinconf.xml</span> you can
+ also modify the respective .css file of your skin.
+ </p>
+<p>
+ Here's another example:
+ </p>
+<pre class="code">
+/*your .css file*/
+...
+#roundbottomsmall {
+ background-image: url(images/rc-b-r-5-1<em>foo</em>-2<em>secondfoo</em>-3<em>thirdfoo</em>.png);
+ background-repeat: no-repeat;
+ background-position: top right;
+}
+...
+ </pre>
+<pre class="code">
+
+...
+<colors>
+ <color name="<em>foo</em>" value="#FF0000"/>
+ <color name="<em>secondfoo</em>" value="#00FF00"/>
+ <color name="<em>thirdfoo</em>" value="##00FF00"/>
+</colors>
+ </pre>
+<p>
+ Here we have created our own color tags (in the .css file) and defined
+ the respective values for them (in <span class="codefrag">skinconf.xml</span>). Now you
+ have color images with a red background and a green foreground.
+ Horrible, isn't it?
+ </p>
+</div>
+<a name="Feedback"></a>
+<h2 class="underlined_10">Feedback</h2>
+<div class="section">
+<p>
+ Please provide feedback about this document via the
+ <a href="../../mail-lists.html">mailing lists</a>.
+ </p>
+</div>
+</div>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+ Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+ logos are trademarks of The Apache Software Foundation.
+ </div>
+
+</div>
+</body>
+</html>

Propchange: forrest/site/docs_0_100/howto/howto-corner-images.html
------------------------------------------------------------------------------
svn:eol-style = native