For Magnolia pages to be useful in the context of an OFBiz application, one must map OFBiz webapp controller views to pages to be rendered using the CMS (instead of the usual OFBiz screen handler).
When an OFBiz webapp controller request reaches the rendering stage and the view-handler is invoked, SCIPIO ERP checks whether the current request or view matches a known CMS page mapping in its database. If such a mapping exists and all conditions for its use pass, SCIPIO ERP invokes the CMS to handle the rendering rather than the OFBiz screen view handler.
The following sections describes the mechanism(s) through which a page author define mappings using SCIPIO ERP.
Request and View Page Mapping
SCIPIO ERP can map Webapp controller requests and views to CMS pages using either simple view mapping or more complex process/view mapping.
Ultimately, for a given request, the OFBiz control servlet selects one view to render. SCIPIO ERP tries to match the current request and view information against its database of process and view mappings, and if a successful match is found, dispatches to the CMS for rendering rather than the regular OFBiz screen.
There may be more than one SCIPIO ERP mapping that matches for a given request. In this case, in general SCIPIO ERP uses specificity to select the highest-priority match and render the page it points to. The more specific a mapping is when matching against the current/target request and target view, the higher its priority and its chance of being selected. For example, process mappings trump simple view mappings; view mappings that match against a specific target request URI trump those that match any target request URI; etc.
Simple View Mapping
This type of mapping simply associates a controller view (name) to a SCIPIO ERP CMS page to be rendered. This is the simplest, standard mapping mechanism.
When a controller request runs into a response which is a view, SCIPIO ERP looks up if any CMS pages are hooked into this view, and if so, invokes CMS rendering.
From a developer’s perspective, this is the mechanism to use if the page author is merely responsible for rendering concerns but is not responsible for decisions relating to the selection of event business logic. Essentially, all control-level webapp logic and public webapp interface is left to the OFBiz webapp developer. This follows from model-view-controller pattern design.
Process Mapping
This type of mapping essentially defines a new webapp request, mapped to a CMS page to be rendered, that reuses an existing controller request/event, which we dub “process”.
A process mapping starts when a webapp request which matches a request URI defined by a process mapping. This is essentially a new URI outside the ones recognized by the controller and may or may not follow their conventions. SCIPIO ERP then forwards the request to another existing controller (or other) URI. During the lifetime of this forward, SCIPIO ERP intercepts any controller view responses and checks if they match any process view mappings for this process mapping. If so, SCIPIO ERP triggers a render invocation for the page that the process view mapping designates.
So in process mappings a page is still ultimately mapped from a view, but only under certain conditions and time frames, notably that it matched the process’s request URI. But the end result is the ability to reuse chains of controller requests and events.
From a developer’s perspective, this is the mechanism to use if one has controller event logic already written and the page author wishes to reuse that logic when rendering the page, for a specific page. Essentially, the page author gains some influence over control-level webapp logic and public webapp interface, or perhaps more accurately, control-level webapp logic and public webapp interface becomes partially possible to administer from backend applications with no static code changes.
View Parameters
When SCIPIO ERP maps an OFBiz controller view to a page for rendering, it also passes over a certain number of request/session/application attributes from the OFBiz context to the Magnolia context that the page template and model can use. We call these SCIPIO ERP view parameters. Very often, screens and pages need access to the results of controller events and to contextual information stored in request/session/application attributes.
SCIPIO ERP itself passes a good deal of standard OFBiz system-level attributes and variables and makes them available to CMS code. These include the delegator, dispatcher, userLogin, request locale, and much more. It also provides some common application-level variables such as the ShoppingCart. These become available through the CatoRenderContext and are provided as attributes in the mock OFBiz request/session/application servlet objects (with similar to their OFBiz screen widget counterparts as they would be used in OFBiz groovy files or OFBiz templates; e.g. CatoRenderContext.getOFbizSession().getAttribute(“userLogin”)).
However due to the complex nature of the system, SCIPIO ERP can only pass attributes to the CMS that are Serializable, and all attributes passed are serialized and deserialized. So by itself SCIPIO ERP must limit the request/session/application attributes that are passed using their types and for others to well-known variables. In some cases, for simplicitly and assuming convention it does allow passing some types which could potentially be dangerous but are usually are not in a standard OFbiz-derived store.
Note: These limitations apply mostly to request/session/application attributes; in general all GET request parameters from the original request can be accessed through the SCIPIO ERP context.
Default View Parameters
By default, SCIPIO ERP passes to the CMS all/only request, session and application (servlet context) attributes that have the following types:
- Java primitives and their boxed versions (Integer, int, etc.)
- String
- Class
- Locale
- Number
- TimeZone
- util.Date
SCIPIO ERP then makes exceptions for some well-known OFBiz attributes such as userLogin, _EVENT_MESSAGE_, etc. In some cases, well-known OFBiz types cannot even be passed as-is and SCIPIO ERP must recreate them on the CMS side, but for all intents and purposes this is transparent to client code. Such attributes are (but are not limited to):
- userLogin
- autoUserLogin
- visit
- visitor
- shoppingCart
- delegator
- dispatcher
- _EVENT_MESSAGE_LIST_ (Note: This one does not appear available to model; it becomes ofbizCtx.eventMessageList instead)
- _ERROR_MESSAGE_LIST_ (Note: This one does not appear available to model; it becomes ofbizCtx.errorMessageList instead)
User-Defined View Parameters
The default view parameters do not include the passing of containers and collections or complex types in attributes, even if defined as implementing Serializable. This is because it is impossible to automatically determine whether a container or complex class is safe or serializable without scanning it in-depth, which is slow and potentially dangerous and still makes assumptions.
For example one should be able to safely pass across to the CMS a ArrayList<HashMap<String, Object>> whose Object entries are only Strings and numbers. But this list could contain hundreds of entries and its implementation may be alien, so this cannot be well-determined or inferred by the system.
As a result, SCIPIO ERP will only pass over complex request/session/application attributes that are specifically requested by name by the Magnolia developer or page author, on a per-view basis.
This can be done using the SCIPIO ERP Request Maps Magnolia app, easiest through the View Mappings editor. Simply find a view and select “Edit View Parameters” from the action bar. In the edit screen can be define a list of request, session, and application attribute names of attributes to always pass over to the CMS page when rendering is invoked.
Note: Despite the use of the View Mappings application to edit them, these View Parameters are tied to views, not view mappings.
The page author (in combination with the OFBiz event programmer) is responsible for only specifying attributes that are Serializable and don’t have a recursive structure. If the page author attempts to specify an attribute that cannot be serialized, the rendering will fail with a serialization error. A recursive structure will appear to lock up and likely eventually cause a stack exception.