| <?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 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> |