144 lines
7.1 KiB
XML
144 lines
7.1 KiB
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 ofbiz-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 git 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>
|