release14.12/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 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>
    &amp;lt;!-- how to create alternative locales -->
    &amp;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" />
    &amp;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"/>
    &amp;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>