You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ofbiz.apache.org by mb...@apache.org on 2020/02/22 18:37:57 UTC
[ofbiz-framework] branch trunk updated: Documented: Themes
documentation migration from md to asciidoc (OFBIZ-11311)
This is an automated email from the ASF dual-hosted git repository.
mbrohl pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/ofbiz-framework.git
The following commit(s) were added to refs/heads/trunk by this push:
new 241d49d Documented: Themes documentation migration from md to asciidoc (OFBIZ-11311)
241d49d is described below
commit 241d49d903eab5d8076a66b003abe2b4d0442ef6
Author: Michael Brohl <mb...@apache.org>
AuthorDate: Sat Feb 22 19:37:37 2020 +0100
Documented: Themes documentation migration from md to asciidoc
(OFBIZ-11311)
Thanks Olivier Heintz for reporting and providing the patch.
---
docs/asciidoc/developer-manual.adoc | 2 +
themes/docs/themes.adoc | 346 ++++++++++++++++++++++++++++++++++++
2 files changed, 348 insertions(+)
diff --git a/docs/asciidoc/developer-manual.adoc b/docs/asciidoc/developer-manual.adoc
index f0df08c..740fd97 100644
--- a/docs/asciidoc/developer-manual.adoc
+++ b/docs/asciidoc/developer-manual.adoc
@@ -243,6 +243,8 @@ include::../../framework/webapp/src/docs/asciidoc/webapp.adoc[leveloffset=+1]
=== Platform Specific Code
+include::../../themes/docs/themes.adoc[leveloffset=+2]
+
== Core APIs
== Development environment
diff --git a/themes/docs/themes.adoc b/themes/docs/themes.adoc
new file mode 100644
index 0000000..a9242a6
--- /dev/null
+++ b/themes/docs/themes.adoc
@@ -0,0 +1,346 @@
+////
+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.
+////
+= Apache OFBiz Themes
+The Apache OFBiz Project
+Release 17.12
+
+== What is a theme
+A Theme is an ofbiz component that defines all elements necessary to render all information generated by the screen engine through
+an embedded technology.
+Currently themes presents in Apache OFBiz use html5/jquery/css to do that.
+
+To realize that, a theme can define some properties, among them some can be necessary.
+It can define its own ftl macro to render the different modelScreen elements and can define its own screen decorator
+to prepare the final user screen structure for the technology used by the theme.
+
+== How to define it
+A theme is a standard component, present in the directory themes or plugins with a file definition present on widget/Theme.xml
+and support the http://ofbiz.apache.org/dtds/widget-theme.xsd[widget-theme.xsd]
+
+To offer the possibility for end users to select the theme through the "Select Theme Screen",
+the theme need to load the entity VisualTheme and one or more entries related to this theme.
+
+== Structure of Theme.xml
+The theme definition file help OFBiz to know what specific rendering the Theme want to use. +
+It's composed by two definition elements and four optional blocks
+
+=== Main definition
+The First mandatory element is one or several visualThemeId related to the theme +
+Defined like that
+```xml
+ <visual-themes>
+ <visual-theme id="MY_THEME"/>
+ </visual-themes>
+```
+You need to define in the database an entry in VisualTheme Entity for each visual-theme id defined.
+```xml
+<entity-engine-xml>
+ <VisualTheme visualThemeId="MY_THEME" visualThemeSetId="BACKOFFICE" description="My theme - Example (based on flatgrey)"/>
+</entity-engine-xml>
+```
+[NOTE]
+a theme component can load one or more visual theme id. Usually only one is present.
+
+The second important (but not mandatory) element is **implements**
+```xml
+ <extends location="component://common-theme/widget/Theme.xml"/>
+```
+This element indicates that your theme copies from the extend theme all information not present in its file definition. +
+If this element isn't present in your theme, you will need to define all information present in common-theme to be sure that OFBiz
+misses nothing for a correct run. Otherwise some functionnalities can be broken...
+
+[NOTE]
+It's highly recommended to extend the common-theme to be sure that your theme works correctly and to surcharge only what
+you need.
+
+The four following blocks are optionnal if you define an extends theme
+
+=== General properties
+This block contains all properties that the screen engine can use to prepare the rendering and that the theme can implement
+```xml
+ <widget-properties><!--Transversal properties relative to ofbiz widget component-->
+ <default-view-size value="20"/>
+ <autocompleter
+ default-view-size="10"
+ default-min-lenght="2"
+ default-delay="300"
+ display-return-field="true"/>
+ <lookup
+ position="topleft"
+ width="640"
+ height="500"/>
+ <layered-modal
+ width="800"
+ height="600"/>
+ </widget-properties>
+```
+
+=== Theme's specific properties
+This block contains all properties specific to this theme. In general these are some properties present on ftl template,
+that are initialized by the theme and can be surchaged by another theme through the extends elements.
+```xml
+ <property name="jgrowlPosition" value="center" type="String"/><!--possible value: top-left, top-right, bottom-left, bottom-right, center-->
+ <property name="jgrowlWidth" value="800" type="Integer"/>
+ <property name="jgrowlHeight" value="" type="Integer"/>
+ <property name="jgrowlSpeed" value="100" type="Integer"/>
+```
+=== Ftl macro library
+This block defines for each technology implemented by the screen engine where it can find the macro library for each model
+(Screen, Form, Tree, Menu)
+```xml
+ <templates><!-- Freemarker template use by this theme to render widget model-->
+ <template name="screen" type="html" content-type="UTF-8" encoding="none" encoder="html" compress="false">
+ <template-file widget="screen" location="component://common-theme/template/macro/HtmlScreenMacroLibrary.ftl"/>
+ <template-file widget="form" location="component://common-theme/template/macro/HtmlFormMacroLibrary.ftl"/>
+ <template-file widget="tree" location="component://common-theme/template/macro/HtmlTreeMacroLibrary.ftl"/>
+ <template-file widget="menu" location="component://common-theme/template/macro/HtmlMenuMacroLibrary.ftl"/>
+ </template>
+ ...
+ </templates>
+```
+
+[NOTE]
+If you want surcharge some macros, you can just create the desired macros and import the others from common-theme
+(at the top of file) like that : +
+ ```<#include "component://common-theme/template/macro/HtmlFormMacroLibrary.ftl"/>```
+
+=== Screen library
+This block defines where OFBiz can find all official screens definitions in framework/common
+
+Normally, you don't need to change this file except if you need to define a default screen style that doesn't exist OOTB.
+If you need to extend an existing one, you have to do it in the theme directory.
+
+To define a new default screen style, you have to add it in this file, and point to the screen decorator in common-theme
+to define your default screen style as the default one.
+
+```xml
+ <common-screens><!--list all common screen and decorator global to each application that each theme can be surcharge or not and use the screen present on common theme-->
+ <structural-decorator default-location="component://common-theme/widget/CommonScreens.xml">
+ <screen name="GlobalDecorator"/>
+ ...
+ </structural-decorator>
+ <embed-decorator default-location="component://common-theme/widget/CommonScreens.xml">
+ <screen name="FindScreenDecorator"/>
+ </embed-decorator>
+ <general-screen default-location="component://common-theme/widget/CommonScreens.xml">
+ <screen name="geoChart"/>
+ ...
+ </general-screen>
+ </common-screens>
+```
+Screens are separated in three types :
+
+* structural-decorator : contains all decorators that organise the screens structures
+* embed-decorator : decorator used only on sub screens
+* general-screen : list all generic inter applications screens
+
+== The common-theme
+This is the root theme that contains all information to ensure a good basic theme for OFBiz. +
+Currently it keeps all old themes system for backward compatibility with ftl template managed by the entity **VisualThemeResource**
+
+== Create your own theme
+As a theme is a component, you can create a new theme like a plugin.
+
+After creating a component, you can add the two minimal information :
+
+* Theme.xml file in **plugins/my-theme/widget/** with minimal information :
+```xml
+<theme name="my-theme"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="http://ofbiz.apache.org/dtds/widget-theme.xsd">
+ <visual-themes>
+ <visual-theme id="MY_THEME" display-name="My Theme"/>
+ </visual-themes>
+</theme>
+```
+
+
+* your data file to add your visual theme in **plugins/my-theme/data/**
+```xml
+<entity-engine-xml>
+ <VisualTheme visualThemeId="MY_THEME" visualThemeSetId="BACKOFFICE"/>
+</entity-engine-xml>
+```
+The presence of VisualTheme entity helps to indicate which theme is available in your instance, specially helpful for
+tenant installations.
+
+To display your theme in OFBiz theme library, you can complete the information on each visual theme like
+```XML
+<theme name="my-theme"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="http://ofbiz.apache.org/dtds/widget-theme.xsd">
+ <visual-themes>
+ <visual-theme id="MY_THEME" display-name="My Theme">
+ <description>My new funny theme under nice tecnno</description>
+ <screenshot location="/mytheme/screenshot1.png"/>
+ <screenshot location="/mytheme/screenshot2.png"/>
+ </visual-theme>
+ </visual-themes>
+</theme>
+```
+
+[NOTE]
+**display-name** and **description** support the flexibleStringExpander syntax
+
+=== extends common-theme
+This is a first step to understand how the theme system works. With your new theme, you can try to surchage different elements. +
+To start, extends the common-theme :
+```xml
+<theme name="my-theme"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="http://ofbiz.apache.org/dtds/widget-theme.xsd">
+ <visual-themes>
+ <visual-theme id="MY_THEME" display-name="My Theme">
+ <description>My new funny theme under nice tecnno</description>
+ <screenshot location="/mytheme/screenshot1.png"/>
+ </visual-theme>
+ </visual-themes>
+ <extends location="component://common-theme/widget/Theme.xml"/>
+</theme>
+```
+Now your theme should be operational, but without particularity.
+
+You can surcharge a ftl macro, to do this create your own ftl macro file in
+**plugins/my-theme/templates/macro/HtmlFormMacroLibrary.ftl** with
+
+```ftl
+<#include "component://common-theme/template/macro/HtmlFormMacroLibrary.ftl"/>
+
+<#macro renderDisplayField type imageLocation idName description title class alert inPlaceEditorUrl="" inPlaceEditorParams="">
+ <#if description?has_content>
+ *###*${description?replace("\n", "<br />")}**<#t/>
+ <#else>
+ *# #*<#t/>
+ </#if>
+</#macro>
+```
+Now indicate to your theme that you want use this library
+```xml
+<theme name="my-theme"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="http://ofbiz.apache.org/dtds/widget-theme.xsd">
+ <visual-themes>
+ <visual-theme id="MY_THEME" display-name="My Theme">
+ <description>My new funny theme under nice tecnno</description>
+ <screenshot location="/mytheme/screenshot1.png"/>
+ </visual-theme>
+ </visual-themes>
+ <extends location="component://common-theme/widget/Theme.xml"/>
+ <templates>
+ <template name="screen" type="html" content-type="UTF-8" encoding="none" encoder="html" compress="false">
+ <template-file widget="form" location="component://my-theme/template/macro/HtmlFormMacroLibrary.ftl"/>
+ </template>
+ </templates>
+</theme>
+```
+and check the result when you select your theme. The result isn't really interesting but it's to understand how it works.
+
+=== create from scratch
+TODO...
+
+== Backware compatibility with OFBiz 16.11 and above
+=== How themes worked before
+Before the theme management by model definition, all configurations have been present in the database through entity
+**VisualTheme** and **VisualThemeRessource**. +
+These ressources were loaded in a **layoutProperties** variable and used directly by decorator screens and ftl templates.
+
+=== Now with the common-theme
+All this logic is still present in the common-theme template to keep backward compatibility, but the VisualThemeRessource
+is now useless and properties have been migrated to the Theme definition in the part **theme-properties**
+
+==== Example with BlueLight
+The blue light theme has been these properties in VisualThemeRessource :
+
+```xml
+ <VisualTheme visualThemeId="BLUELIGHT" visualThemeSetId="BACKOFFICE" description="BlueLight Theme: breadcrumbs, drop-down menus and rounded corners"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_NAME" resourceValue="BLUELIGHT" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_IMAGE_URL" resourceValue="/images/ofbiz_logo.png" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_SHORTCUT_ICON" resourceValue="/images/ofbiz.ico" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_SCREENSHOT" resourceValue="/bluelight/screenshot.jpg" sequenceId="01"/>
+
+ <!-- CSS references -->
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_STYLESHEET" resourceValue="/bluelight/style.css" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HELPSTYLESHEET" resourceValue="/bluelight/help.css" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_DOCBOOKSTYLESHEET" resourceValue="/bluelight/webapp/bluelight/docbook.css" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_STYLESHEET" resourceValue="/common/js/jquery/plugins/asmselect/jquery.asmselect-1.0.4a-beta.css" sequenceId="02"/>
+
+ <!-- Javascript references -->
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/jquery/jquery-1.11.0.min.js" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/jquery/jquery-migrate-1.2.1.js" sequenceId="02"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/jquery/ui/js/jquery-ui-1.10.3.min.js" sequenceId="03"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/jquery/plugins/asmselect/jquery.asmselect-1.0.4a-beta.js" sequenceId="05"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/jquery/plugins/datetimepicker/jquery-ui-timepicker-addon.min-1.4.3.js" sequenceId="07"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/jquery/plugins/fjTimer/jquerytimer-min.js" sequenceId="09"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/jquery/plugins/mask/jquery.mask-1.14.13.min.js" sequenceId="10"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/jquery/plugins/jeditable/jquery.jeditable-1.7.3.js" sequenceId="11"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/jquery/plugins/validate/jquery.validate.min.js" sequenceId="12"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/plugins/OpenLayers-2.13.1.js" sequenceId="13"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/util/OfbizUtil.js" sequenceId="15"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/util/fieldlookup.js" sequenceId="16"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/plugins/date/date.format-1.2.3-min.js" sequenceId="17"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/plugins/date/date.timezone-min.js" sequenceId="18"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/util/miscAjaxFunctions.js" sequenceId="19"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/util/selectMultipleRelatedValues.js" sequenceId="20"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/util/util.js" sequenceId="21"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/common/js/plugins/date/FromThruDateCheck.js" sequenceId="22"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_JAVASCRIPT" resourceValue="/bluelight/dropdown.js" sequenceId="30"/>
+
+ <!-- ftl references -->
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_HDR_TMPLT_LOC" resourceValue="component://bluelight/template/Header.ftl" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_FTR_TMPLT_LOC" resourceValue="component://bluelight/template/Footer.ftl" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_NAV_OPEN_TMPLT" resourceValue="component://bluelight/template/AppBarOpen.ftl" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_NAV_CLOSE_TMPLT" resourceValue="component://bluelight/template/AppBarClose.ftl" sequenceId="01"/>
+ <VisualThemeResource visualThemeId="BLUELIGHT" resourceTypeEnumId="VT_MSG_TMPLT_LOC" resourceValue="component://bluelight/template/Messages.ftl" sequenceId="01"/>
+```
+Now it's just
+```xml
+ <VisualTheme visualThemeId="BLUELIGHT" visualThemeSetId="BACKOFFICE"/>
+```
+And on theme definition
+
+```xml
+ <theme-properties>
+ <!--javascript lib-->
+ <property name="VT_HDR_JAVASCRIPT['add']" value="/bluelight/dropdown.js" sequenceId="30"/>
+ <!--Css style-->
+ <property name="VT_STYLESHEET['add']" value="/bluelight/style.css"/>
+ <property name="VT_HELPSTYLESHEET['add']" value="/bluelight/help.css"/>
+ <property name="VT_DOCBOOKSTYLESHEET['add']" value="/bluelight/webapp/bluelight/docbook.css"/>
+ <!--template location-->
+ <property name="VT_HDR_TMPLT_LOC" value="component://bluelight/template/Header.ftl"/>
+ <property name="VT_FTR_TMPLT_LOC" value="component://bluelight/template/Footer.ftl"/>
+ <property name="VT_NAV_OPEN_TMPLT" value="component://bluelight/template/AppBarOpen.ftl"/>
+ <property name="VT_NAV_CLOSE_TMPLT" value="component://bluelight/template/AppBarClose.ftl"/>
+ <property name="VT_MSG_TMPLT_LOC" value="component://bluelight/template/Messages.ftl"/>
+ </theme-properties>
+```
+Values with **/images/...** have been moved to the common-theme that bluelight extends, the theme definition keeps only what the theme adds to the extended theme.
+
+[NOTE]
+property name supports the FlexibleMapAccessor syntax, so you can continue to populate a list (VT_STYLESHEET['add']),
+reset a list (VT_STYLESHEET[]) or add an element on the top list (VT_STYLESHEET[+0]) because some time the order libraries
+loading is important
+
+==== Migrate you own theme
+Easily, create you Theme.xml and move your VisualThemeResource in **theme-properties** like in the BlueLight example above. +
+Maybe you will need to update your template because the modelTheme return ressources not always as list. So : +
+`<property name="VT_HDR_TMPLT_LOC" value="component://bluelight/template/Header.ftl"/>` -> return a String
+with `component://bluelight/template/Header.ftl` +
+`<property name="VT_STYLESHEET['add'] value="..."` -> return a List<String>
+