applications/commonext/data/helpdata/HELP_OFBizDocumentationSystem.xml
<?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.
-->
<section xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
version="5.0" xmlns:xl="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"
xsi:schemaLocation="http://docbook.org/ns/docbook"
xmlns="http://docbook.org/ns/docbook">
<title>The Apache OFBiz documentation system</title>
<section>
<title>Overview</title>
<para>
The OFBiz documentation system consist out of a number of DocBook xml
files. In general the files are stored within the subject
component either in the 'documents' or data/helpdata
directories.
The docbook schemas are stored in the applications/content/dtd
directory and the stylesheets are
stored in the applications/content/templates/docbook directory.
</para>
<para>
The definition of the content and dataresource records can be found in
the application/content/data/ContentType.xml file at the
bottom. They are in this file because the documentation and
helpfile are considered 'seed' data: essential for the operation of OFBiz.
</para>
<para>
If you are looking for docbook files format examples, please
look at the following files:
<orderedlist>
<listitem><para>An example for a chapter of a component at:
applications/accounting/documents/Accounting.xml</para></listitem>
<listitem><para>An example of a help screen:
applications/accounting/data/helpdata/HELP_ACCOUNTING_main.xml</para></listitem>
<listitem><para>An example of content creation:
applications/accounting/data/AccountingHelpData.xml</para></listitem>
</orderedlist>
</para>
</section>
<section>
<title>Contributing a new help screen, a few steps.</title>
<para>
There is a difference between portlets and 'normal' screens. If a
page contains a portlet, the general help of the myportal component is shown with
at the bottom a list of the portlets used at that page. Help can be obtained by clicking on
the relevant portlet.
</para>
<section>
<title>Normal pages.</title>
<para>
So if you would like to create a new help menu for a certain
screen, you need to do the following:
<orderedlist>
<listitem>
<para>In the helplink.ftl un-comment the ${helpTopic} variable so it will appear at the
top right hand of your screen.
</para>
</listitem>
<listitem>
<para>
In the specific component data/helpData create the HELP_${helpTopic}.xml file. you can find an
example in the HELP_ACCOUNTING_main.xml file.
</para>
</listitem>
<listitem>
<para>
Update/create the data/${componentName}HelpData.xml, an example can be found in the
AccountingHelpData.xml. If new make also an entry in the scipio-component.xml
</para>
</listitem>
<listitem>
<para>
Load the HelpDataFile and the file should show up when you click on the help button.
</para>
</listitem>
<listitem>
<para>
Submit the change to the svn repository or create a diff file and attach it to a jira issue.
</para>
</listitem>
<listitem>
<para>
If the help text is useful in the ofbiz document include it in the files in the document directory.
</para>
</listitem>
</orderedlist>
</para>
</section>
<section>
<title>Contributing a new Portlet help screen.</title>
<para>
Portlets are normally defined and explained in the ${component name}PortletData.xml files. An example
of an portlet with an existing help screen have a look at WorkEffortPortletData.xml
</para>
<para>
The content records for the help file is defined together with the portlet definition and the actual help
file is store in the related component /data/helpdata directory with the name HELP_PORTLET_${portletId}.xml.
</para>
</section>
</section>
<section>
<title><anchor xml:id="helpInternationalization"/>Internationalization of the help system</title>
<para>
Because the help system is making use of the content component, internationalization of the help files is very easy because
it is a basic function of the content component. If you want to make a translation of an existing help file, make a copy in the same directory
and make it unique by attaching the "_languageCode" at the end.
</para>
<para>
Create, as also was done for the english version a dataresource and content record in the data/${componentName}HelpData.xml file.
Then create an ContentAssoc record in data/${componentName}HelpData.xml file to associate this new file with the english file with the type
ALTERNATE_LOCALE. Please find below an example from the ContentHelpData.xml for a Dutch version of the root help file.
<programlisting>
&lt;!-- how to create alternative locales -->
&lt;DataResource dataResourceId="HELP_ROOT_NL" localeString="nl" dataResourceTypeId="OFBIZ_FILE"
objectInfo="applications/content/data/helpdata/HELP_ROOT_NL.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS"
dataResourceName="Help system root" mimeTypeId="text/xml" isPublic="Y" />
&lt;Content contentId="HELP_ROOT_NL" contentTypeId="DOCUMENT" templateDataResourceId="HELP_TEMPL"
dataResourceId="HELP_ROOT_NL" localeString="nl" statusId="CTNT_IN_PROGRESS"
contentName="Help system root in dutch" mimeTypeId="text/html"/>
&lt;ContentAssoc contentId="HELP_ROOT" contentIdTo="HELP_ROOT_NL"
contentAssocTypeId="ALTERNATE_LOCALE" fromDate="2006-01-12 01:01:01"/>
</programlisting>
The switching between locales is from then on completely automatic.
</para>
</section>
</section>