[ofbiz-framework] branch trunk updated: Documented: Themes documentation migration from md to asciidoc (OFBIZ-11311)
Locked
 
|
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 <[hidden email]> 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> + |
«
Return to OFBiz - Commits
|
1 view|%1 views
| Free forum by Nabble | Edit this page |