Chapter 3 : promoting decorator

[Gil Portenseigne]

Hello devs,

This mail introduce the last Chapter of our story that describe in
which context we created some new decorators.

First, we want to recall the common-theme effort objectives :

The common-theme component is the default theme that define every
screens that are available for theme surcharge, without technology
information (css/html, vuejs or something like that).

Every theme is based onto this common-theme that structure the
application. Any theme can empower this structure its way, using it’s
one technology.

The idea is simple, isolating screen definition from technology syntax, let the
technology implementation to the theme.

Xml Screen and form definition must only be description of the
structure. The “how it is render” is defined by default by the
common-theme, and might be overloaded by a chosen theme.

From these objectives arise the need to list structural descriptive
decorator that exists or are added by our effort :

The *FindScreenDecorator* : is the existing search screen decorator in
OFBiz, it is composed in three sections :
* A menu (party creation for instance : menu-bar)
* Search criteria (search-option)
* Results (search-results)

The new *DetailsScreenDecorator* : is a new decorator to show a sum up of
an object and its related data. Composed in five sections :
* A menu (menu-bar)
* A tab menu : to give access to related data into details section
  (tab-bar)
* A summary that display main data of the object (summary)
* An action menu (object modification, duplicate or specific actions :
  actions)
* The detail : area that will display related data (details)

This structure, in addition to give the display control to the theme,
offer the developer not to think about the area to use when he wants to
display more data concerning the object.

Moreover, when performing actions, the developer do not need to know
about the area to refresh, since the screen-engine has been improved to
manage it for him.

The new *EmbeddedScreenDecorator* : is a new decorator used to inject in
an structure page area a specific screen.

Its goal is to define what kind of data the screen will have to render
to allow the theme to adapt the technology for data rendering.
The sections are :
* A menu (menu-bar)
* An action menu (search filtering, history display…)
* single : display of a single form
* content : display a content (Image or document)
* list : display a list of data

Those can be loaded by functional decorator that take charge of basic
data retrieval :

As an example :
*EmbeddedProductCategoryScreenDecorator*
That is a specific decorator that implements the
*EmbeddedScreenDecorator* and do the data retrieval of productCategory
object :

<screen name="EmbeddedProductCategoryScreenDecorator">
    <section>
        <actions>
            <entity-one entity-name="ProductCategory" value-field="productCategory"/>
            <set field="productCategory" from-field="productCategory" global="true"/>
            <property-map resource="ProductUiLabels" map-name="uiLabelMap" global="true"/>
            <property-map resource="CommonUiLabels" map-name="uiLabelMap" global="true"/>
        </actions>
        <widgets>
            <include-screen name="EmbeddedScreenDecorator"
            location="component://common/widget/CommonScreens.xml"/>
        </widgets>
    </section>
</screen>

This avoid for every embedded screen using productCategory code
duplication in data retrieval.  The same logic can be applied to
*DetailsScreenDecorator*.

To see all that in action we are working into a simple demo, in a
classical theme and an simple improved theme, we currently are creating
a sum-up presentation with illustration and more details like
code/video.

I hope we will be able to share it with you soon enough.

Best Regards