OFBiz › OFBiz - Commits

[ofbiz-plugins] branch trunk updated: Documented: ofbiz-plugins / Example, migration of docbook help files to asciidoc (OFBIZ-11587)

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

1 message

holivier

[ofbiz-plugins] branch trunk updated: Documented: ofbiz-plugins / Example, migration of docbook help files to asciidoc (OFBIZ-11587)

This is an automated email from the ASF dual-hosted git repository.

holivier pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/ofbiz-plugins.git

The following commit(s) were added to refs/heads/trunk by this push:
new 66070a6 Documented: ofbiz-plugins / Example, migration of docbook help files to asciidoc (OFBIZ-11587)
66070a6 is described below

commit 66070a6bc1731b13f03ca3b11066a706764e993b
Author: holivier <[hidden email]>
AuthorDate: Thu Sep 24 18:09:10 2020 +0200

Documented: ofbiz-plugins / Example, migration of docbook help files
to asciidoc
(OFBIZ-11587)

example.adoc and example_main.adoc created
Help link now point to the html file generated from the asciidoc files

In the global Help Docbook index tree, change Example help page to a
short page with a link to the new help

Remove docbook help files for example
HELP_EXAMPLE_docbook.xml has not been migrate because it's replace by
the existing documentation_guidelines.adoc
---
birt/data/example/ExampleHelpData.xml | 48 ---------------
example/data/ExampleHelpData.xml | 25 +-------
.../HELP_EXAMPLE_main.xml => HELP_EXAMPLE.xml} | 13 ++--
example/data/helpdata/HELP_EXAMPLE.xml | 55 -----------------
example/data/helpdata/HELP_EXAMPLE_docbook.xml | 72 ----------------------
.../src/docs/asciidoc/_include/example_main.adoc | 22 +++++++
example/src/docs/asciidoc/example.adoc | 53 ++++++++++++++++
example/widget/example/CommonScreens.xml | 1 +
example/widget/example/ExampleScreens.xml | 3 +-
9 files changed, 89 insertions(+), 203 deletions(-)

diff --git a/birt/data/example/ExampleHelpData.xml b/birt/data/example/ExampleHelpData.xml
deleted file mode 100644
index ac85929..0000000
--- a/birt/data/example/ExampleHelpData.xml
+++ /dev/null
@@ -1,48 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<entity-engine-xml>
-
- <DataResource dataResourceId="HELP_EXAMPLE" localeString="en" dataResourceTypeId="OFBIZ_FILE"
- objectInfo="plugins/example/data/helpdata/HELP_EXAMPLE.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS"
- dataResourceName="Framework Example" mimeTypeId="text/xml" isPublic="Y" />
- <Content contentId="HELP_EXAMPLE" contentTypeId="DOCUMENT" contentName="Framework Example" templateDataResourceId="HELP_TEMPL"
- dataResourceId="HELP_EXAMPLE" statusId="CTNT_IN_PROGRESS" mimeTypeId="text/html"/>
- <ContentAssoc contentId="HELP_ROOT" contentIdTo="HELP_EXAMPLE" contentAssocTypeId="TREE_CHILD" fromDate="2006-01-12 01:01:01" sequenceNum="000"/>
-
- <DataResource dataResourceId="HELP_EXAMPLE_FR" localeString="fr" dataResourceTypeId="OFBIZ_FILE"
- objectInfo="plugins/example/data/helpdata/HELP_EXAMPLE_FR.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS"
- dataResourceName="Exemple pour le développement" mimeTypeId="text/xml" isPublic="Y" />
- <Content contentId="HELP_EXAMPLE_FR" contentTypeId="DOCUMENT" contentName="Exemple pour le développement" templateDataResourceId="HELP_TEMPL"
- dataResourceId="HELP_EXAMPLE_FR" statusId="CTNT_IN_PROGRESS" mimeTypeId="text/html" localeString="fr" />
- <ContentAssoc contentId="HELP_EXAMPLE" contentIdTo="HELP_EXAMPLE_FR" contentAssocTypeId="ALTERNATE_LOCALE" fromDate="2006-01-12 01:01:01"/>
-
- <DataResource dataResourceId="EXAMPLE_main" localeString="en" dataResourceTypeId="OFBIZ_FILE"
- objectInfo="plugins/example/data/helpdata/HELP_EXAMPLE_main.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS" dataResourceName="Example help main page" mimeTypeId="text/xml" isPublic="Y" />
- <Content contentId="EXAMPLE_main" contentTypeId="DOCUMENT" contentName="Example main menu." templateDataResourceId="HELP_TEMPL" dataResourceId="EXAMPLE_main" statusId="CTNT_IN_PROGRESS" mimeTypeId="text/html"/>
- <ContentAssoc contentId="HELP_EXAMPLE" contentIdTo="EXAMPLE_main" mapKey="EXAMPLE_main" fromDate="2006-01-12 01:01:01" contentAssocTypeId="TREE_CHILD" sequenceNum="000"/>
- <ContentAssoc contentId="HELP_EXAMPLE" contentIdTo="EXAMPLE_main" mapKey="EXAMPLE_FindExample" fromDate="2006-01-12 01:01:02" sequenceNum="000" contentAssocTypeId="INSTANCE"/>
-
- <DataResource dataResourceId="EXAMPLE_docbook" localeString="en" dataResourceTypeId="OFBIZ_FILE"
- objectInfo="plugins/example/data/helpdata/HELP_EXAMPLE_docbook.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS" dataResourceName="Example docBook usage" mimeTypeId="text/xml" isPublic="Y" />
- <Content contentId="EXAMPLE_docbook" contentTypeId="DOCUMENT" contentName="Example Docbook usage" templateDataResourceId="HELP_TEMPL" dataResourceId="EXAMPLE_docbook" statusId="CTNT_IN_PROGRESS" mimeTypeId="text/html"/>
- <ContentAssoc contentId="HELP_EXAMPLE" contentIdTo="EXAMPLE_docbook" contentAssocTypeId="TREE_CHILD" fromDate="2006-01-12 01:01:01" sequenceNum="000" mapKey="EXAMPLE_docbook"/>
-
-
-</entity-engine-xml>
diff --git a/example/data/ExampleHelpData.xml b/example/data/ExampleHelpData.xml
index ac85929..0e03d1f 100644
--- a/example/data/ExampleHelpData.xml
+++ b/example/data/ExampleHelpData.xml
@@ -19,30 +19,11 @@ under the License.
-->
<entity-engine-xml>

- <DataResource dataResourceId="HELP_EXAMPLE" localeString="en" dataResourceTypeId="OFBIZ_FILE"
- objectInfo="plugins/example/data/helpdata/HELP_EXAMPLE.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS"
+ <DataResource dataResourceId="HELP_EXAMPLE" localeString="en" dataResourceTypeId="OFBIZ_FILE"
+ objectInfo="plugins/example/data/HELP_EXAMPLE.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS"
dataResourceName="Framework Example" mimeTypeId="text/xml" isPublic="Y" />
- <Content contentId="HELP_EXAMPLE" contentTypeId="DOCUMENT" contentName="Framework Example" templateDataResourceId="HELP_TEMPL"
+ <Content contentId="HELP_EXAMPLE" contentTypeId="DOCUMENT" contentName="Framework Example" templateDataResourceId="HELP_TEMPL"
dataResourceId="HELP_EXAMPLE" statusId="CTNT_IN_PROGRESS" mimeTypeId="text/html"/>
<ContentAssoc contentId="HELP_ROOT" contentIdTo="HELP_EXAMPLE" contentAssocTypeId="TREE_CHILD" fromDate="2006-01-12 01:01:01" sequenceNum="000"/>

- <DataResource dataResourceId="HELP_EXAMPLE_FR" localeString="fr" dataResourceTypeId="OFBIZ_FILE"
- objectInfo="plugins/example/data/helpdata/HELP_EXAMPLE_FR.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS"
- dataResourceName="Exemple pour le développement" mimeTypeId="text/xml" isPublic="Y" />
- <Content contentId="HELP_EXAMPLE_FR" contentTypeId="DOCUMENT" contentName="Exemple pour le développement" templateDataResourceId="HELP_TEMPL"
- dataResourceId="HELP_EXAMPLE_FR" statusId="CTNT_IN_PROGRESS" mimeTypeId="text/html" localeString="fr" />
- <ContentAssoc contentId="HELP_EXAMPLE" contentIdTo="HELP_EXAMPLE_FR" contentAssocTypeId="ALTERNATE_LOCALE" fromDate="2006-01-12 01:01:01"/>
-
- <DataResource dataResourceId="EXAMPLE_main" localeString="en" dataResourceTypeId="OFBIZ_FILE"
- objectInfo="plugins/example/data/helpdata/HELP_EXAMPLE_main.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS" dataResourceName="Example help main page" mimeTypeId="text/xml" isPublic="Y" />
- <Content contentId="EXAMPLE_main" contentTypeId="DOCUMENT" contentName="Example main menu." templateDataResourceId="HELP_TEMPL" dataResourceId="EXAMPLE_main" statusId="CTNT_IN_PROGRESS" mimeTypeId="text/html"/>
- <ContentAssoc contentId="HELP_EXAMPLE" contentIdTo="EXAMPLE_main" mapKey="EXAMPLE_main" fromDate="2006-01-12 01:01:01" contentAssocTypeId="TREE_CHILD" sequenceNum="000"/>
- <ContentAssoc contentId="HELP_EXAMPLE" contentIdTo="EXAMPLE_main" mapKey="EXAMPLE_FindExample" fromDate="2006-01-12 01:01:02" sequenceNum="000" contentAssocTypeId="INSTANCE"/>
-
- <DataResource dataResourceId="EXAMPLE_docbook" localeString="en" dataResourceTypeId="OFBIZ_FILE"
- objectInfo="plugins/example/data/helpdata/HELP_EXAMPLE_docbook.xml" dataTemplateTypeId="NONE" statusId="CTNT_IN_PROGRESS" dataResourceName="Example docBook usage" mimeTypeId="text/xml" isPublic="Y" />
- <Content contentId="EXAMPLE_docbook" contentTypeId="DOCUMENT" contentName="Example Docbook usage" templateDataResourceId="HELP_TEMPL" dataResourceId="EXAMPLE_docbook" statusId="CTNT_IN_PROGRESS" mimeTypeId="text/html"/>
- <ContentAssoc contentId="HELP_EXAMPLE" contentIdTo="EXAMPLE_docbook" contentAssocTypeId="TREE_CHILD" fromDate="2006-01-12 01:01:01" sequenceNum="000" mapKey="EXAMPLE_docbook"/>
-
-
</entity-engine-xml>
diff --git a/example/data/helpdata/HELP_EXAMPLE_main.xml b/example/data/HELP_EXAMPLE.xml
similarity index 70%
rename from example/data/helpdata/HELP_EXAMPLE_main.xml
rename to example/data/HELP_EXAMPLE.xml
index a421dfc..dbb8f1f 100644
--- a/example/data/helpdata/HELP_EXAMPLE_main.xml
+++ b/example/data/HELP_EXAMPLE.xml
@@ -17,9 +17,12 @@ License.
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 ../../../../applications/content/dtd/docbook.xsd"
xmlns="http://docbook.org/ns/docbook">
- <title>The Example Main page.</title>
- <para><link xl:href="showHelp?helpTopic=EXAMPLE">About the Example application</link></para>
- <para>
- In this page, you can create or search an example
- </para>
+ <title>Example Help redirection.</title>
+ <para>
+ The Example application will allow you to discover the possibilities to create an application, with a lot of search boxes, lists and many more.</para>
+
+ <para>Example Help has been migrated to a new system, you can access it by using
+ <link xl:href="https://ci.apache.org/projects/ofbiz/site/trunk/ofbizdoc/html5/user-manual.html#_example">OFBiz user documentation site / Example</link>
+ </para>
+
</section>
diff --git a/example/data/helpdata/HELP_EXAMPLE.xml b/example/data/helpdata/HELP_EXAMPLE.xml
deleted file mode 100644
index ae4fb90..0000000
--- a/example/data/helpdata/HELP_EXAMPLE.xml
+++ /dev/null
@@ -1,55 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<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 ../../../../applications/content/dtd/docbook.xsd"
- xmlns="http://docbook.org/ns/docbook">
- <title>The Example Main Help page.</title>
- <para>
- The Example application will allow you to discover the possibilities to create an application, with a lot of search boxes, lists and many more.</para>
- <para>This application could be used to have an example of the bests practices in user interface development in Apache - OFBiz.</para>
- <para>Look help for each example screen, help will explain which part of development is used in this case.</para>
- <para>For example, if you want to see how you should do to add some help you can look to help files in data/helpdata directory in example
- component and data/ExempleHelpData.xml in content component.</para>
-
- <section>
- <title>Help file organization</title>
- <para>Help is managed by using content component functionality.</para>
- <para>Help can be for :
- <itemizedlist>
- <listitem><para>one component or sub-component, access is possible by navigation in help index tree and select it, contentId is associated to
- HELP_ROOT with contentAssocTypeId="TREE_CHILD" ;</para></listitem>
- <listitem><para>one screen, access is done by help icon in screen (most of time on top), contentId is search on ContentAssoc.mapKey with
- a value (helpTopic) build with component webSite and uri used to show this screen ;</para></listitem>
- <listitem><para>one portlet, access is done by a link on the portalPages (which contain this portlet) help, link is a showHelp (like
- for a screen) with helpTopic build with "HELP_" and portletId</para></listitem>
- <listitem><para>one portal page, access is done by help icon if parameters.portalPageId is not empty, contentId is read on PortalPage
- (or originalPortalPage if exist) and is show on top of portlet list contain on it.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section>
- <title>Development help sub-subject</title>
- <para>To have the complete list you should click on index button and look to example tree option, but here is a list of
- main shortcut :
- <itemizedlist>
- <listitem><para>How is organize <link xl:href="showHelp?helpTopic=DOCUMENTATION_SYSTEM">The Apache OFBiz documentation system</link></para></listitem>
- <listitem><para><link xl:href="showHelp?helpTopic=EXAMPLE_docbook">What it's possible to do in help file</link></para></listitem>
- </itemizedlist>
- </para>
- </section>
-</section>
diff --git a/example/data/helpdata/HELP_EXAMPLE_docbook.xml b/example/data/helpdata/HELP_EXAMPLE_docbook.xml
deleted file mode 100644
index 21dbb54..0000000
--- a/example/data/helpdata/HELP_EXAMPLE_docbook.xml
+++ /dev/null
@@ -1,72 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<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 ../../../../applications/content/dtd/docbook.xsd"
- xmlns="http://docbook.org/ns/docbook">
-
- <title>Help on writing docBook documents</title>
- <section>
- <title>Example of an ordered list</title>
- <para>The orderedlist will put numbers in front of each item.</para>
- <orderedlist>
- <listitem><para>First item of my list</para></listitem>
- <listitem><para>Second item</para></listitem>
- <listitem><para>Third...</para></listitem>
- <listitem><para>4th...</para></listitem>
- <listitem><para>and this can go longer...</para></listitem>
- </orderedlist>
- </section>
- <section>
- <title>Example of an itemized list</title>
- <para>The itemizedlist will put a bullet in front of each item.</para>
- <itemizedlist>
- <listitem><para>First item of my list</para></listitem>
- <listitem><para>Second item</para></listitem>
- <listitem><para>Third...</para></listitem>
- <listitem><para>4th...</para></listitem>
- <listitem><para>and this can go longer...</para></listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Examples of text formatting</title>
- <caution>
- <title>Caution title</title>
- <para>Here is a caution text</para>
- </caution>
- <important>
- <title>Important title</title>
- <para>Here is an important text</para>
- </important>
- <note>
- <title>Note title</title>
- <para>Here is a note</para>
- </note>
- <tip>
- <title>Tip title</title>
- <para>Here is a tip</para>
- </tip>
- <warning>
- <para>Here is a warning</para>
- </warning>
- </section>
-</section>
diff --git a/example/src/docs/asciidoc/_include/example_main.adoc b/example/src/docs/asciidoc/_include/example_main.adoc
new file mode 100644
index 0000000..5b94a56
--- /dev/null
+++ b/example/src/docs/asciidoc/_include/example_main.adoc
@@ -0,0 +1,22 @@
+////
+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.
+////
+
+= The Example Main page
+
+In this page, you can create or search an example
\ No newline at end of file
diff --git a/example/src/docs/asciidoc/example.adoc b/example/src/docs/asciidoc/example.adoc
new file mode 100644
index 0000000..a03d059
--- /dev/null
+++ b/example/src/docs/asciidoc/example.adoc
@@ -0,0 +1,53 @@
+////
+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.
+////
+= Example Plugin
+The Example application will allow you to discover the possibilities to create an application, with a lot of search boxes,
+lists and many more.
+
+This application could be used to have an example of the bests practices in user interface development in Apache - OFBiz.
+
+Look help for each example screen, help will explain which part of development is used in this case.
+
+For example, if you want to see how you should do to add some help you can look to help files in src/docs/asciisoc/_include/
+directory and src/docs/asciisoc/example.adoc both in example component.
+
+== Help file organization
+Help is managed by using content component functionality.
+
+Help can be for :
+
+* one component or sub-component, access is possible by navigation in help index tree and select it, contentId is associated to
+ HELP_ROOT with contentAssocTypeId="TREE_CHILD" ;
+* one screen, access is done by help icon in screen (most of time on top), contentId is search on ContentAssoc.mapKey with
+ a value (helpTopic) build with component webSite and uri used to show this screen ;
+* one portlet, access is done by a link on the portalPages (which contain this portlet) help, link is a showHelp (like
+ for a screen) with helpTopic build with "HELP_" and portletId
+* one portal page, access is done by help icon if parameters.portalPageId is not empty, contentId is read on PortalPage
+ (or originalPortalPage if exist) and is show on top of portlet list contain on it.
+
+== Development help sub-subject
+To have the complete list you should click on index button and look to example tree option, but here is a list of
+main shortcut :
+
+* How is organize The Apache OFBiz documentation system documentation is coming soon.
+* link:documentation_guidelines.html[Documentation / asciidoc guidelines]
+
+== UI help for Example
+
+include::_include/example_main.adoc[leveloffset=+2]
diff --git a/example/widget/example/CommonScreens.xml b/example/widget/example/CommonScreens.xml
index 3a0f94a..c966254 100644
--- a/example/widget/example/CommonScreens.xml
+++ b/example/widget/example/CommonScreens.xml
@@ -43,6 +43,7 @@ under the License.
<set field="applicationMenuName" value="ExampleAppBar" global="true"/>
<set field="applicationMenuLocation" value="component://example/widget/example/ExampleMenus.xml" global="true"/>
<set field="applicationTitle" from-field="uiLabelMap.ExampleApplication" global="true"/>
+ <set field="helpAnchor" from-field="helpAnchor" default-value="_example"/>
</actions>
<widgets>
<section>
diff --git a/example/widget/example/ExampleScreens.xml b/example/widget/example/ExampleScreens.xml
index eec35b1..2ad3ec9 100644
--- a/example/widget/example/ExampleScreens.xml
+++ b/example/widget/example/ExampleScreens.xml
@@ -26,9 +26,10 @@ under the License.
<section>
<actions>
<set field="headerItem" value="ExampleMenuItem"/>
+ <set field="helpAnchor" value="_the_example_main_page"/>
<set field="titleProperty" value="PageTitleFindExample"/>
<set field="exampleCtx" from-field="parameters"/>
- <set field="formExampleListName" value="${groovy:
+ <set field="formExampleListName" value="${groovy:
if (parameters.listOtherElements == 'items') return 'ListExamplesWithItems';
else if (parameters.listOtherElements == 'features') return 'ListExamplesWithFeatures';
else if (parameters.listOtherElements == 'status') return 'ListExamplesWithStatus';