Introduction
The purpose of this article is to provide the basics for operating with styles in WebRatio.
Defining a style means creating the visual identity of a Web application, choosing all of the graphic widgets in order to make the Web application usable and visually pleasing.
WebRatio introduced the concept of a Style Project to let you create personalized styles for a Web application.
A Style Project contains the layout templates needed to generate the graphical elements of your Web application.
A layout template is a file specifying the graphical appearance of a specific model element (page, view component, attribute, field, or flow).
This article starts by introducing the main concepts related to Style Projects and then explains the layout templates using the Page Layout Template.
Style Project Structure
The Style Project is organized in a modular way so that each aspect of the page presentation can be specified and changed independently.
Creating a Style Project means addressing several independent objects, which are all layout items of the Web Project (pages, frames, cells, attributes, flows and so on).
The type of a layout is determined according to which object is going to be rendered.
The Project on the workspace is organized in folders.
The Project has one predefined folder named like the Style Project itself in which you can put custom folders and manage your own resources. As long as you add templates, elements you will see a dedicated folder for each new category of layout.
Style Hierarchy
The application of style properties to model elements inside the Web Project uses a hierarchical approach.
Starting from the top, the Project node, you can set properties at a high level and let all the sub-elements inherit properties from the high level.
Or, you can explicitly set properties at a certain level to overwrite those defined at a higher level.
Inherited properties will be shown in gray while properties explicitly set on the element are shown in black in the Layout Properties View.
Style Project Configuration
The Style Project can be configured using the Layout.xml file. This file lets you define style defaults and can be found in the root folder of every Style Project.
A style “default” is a style rule automatically set when the Style Project is applied to any Web Project. For example, consider a WebRatio Style Project where the default choice for the Page Template is ‘WebRatio/Basic’. Any time this Style Project is applied to a Web Project, each page of the Web Project will have the ‘WebRatio/Basic’ Page Template.
The Layout.xml file is divided into sections (General, Components, Resources), each covering different aspects of a style project.
General
The General Section defines the default layout templates for Pages, Grids, Frames, Cells, Attributes, Field and Flows.
If a default is not specified, the one considered is what corresponds to the default of the WRDefault Style Project.
Components
The Component section defines the default layout templates for each of the View Components already defined in WebRatio.
If a default is not specified, the one considered is the corresponding default of the WRDefault Style Project.
Resources
The Resources section defines the layout resources included and used by the Style Project (mainly CSS and JavaScript).
Each resource is declared through a name, type and file, and can eventually also refer to a remote URL.
Resources might always be needed by the Style Project and for this purpose, there is a dedicated section called ‘Always Required Resources’.
The Declared Resources list contains a set of default resources, shown in gray and inherited from the WRDefault Style Project.
Layout Template
To introduce the Layout Templates, let’s consider the most important and significant layout template file: the Page Layout Template.
Let’s consider this page containing a catalogue of products, modeled as Master & Details pattern for the Product Entity.
XML Structure
By analyzing the page modeled above, and its related outline view, you can see that elements are nested one into the other, much like a tree structure.
The IFML Model corresponds to an XML structure, where each model element always corresponds to an XML node reflecting the model structure.
For each model element, if the model element itself is supposed to be shown in the page (for example, a component, a flow, an attribute), the XML structure also contains the corresponding layout node.
The structure can be accessed using the XML tab of the properties view of each model element. Here you will find two options: the ‘Show XML’ button, which opens the XML structure, and the ‘Show Layout XML’ button that opens only the layout XML.
Layout Hierarchy
The page template, responsible for the page rendering on the browser, must consider layout elements that participate in the page structure, as defined by the Layout XML.
The layout hierarchy for a page includes the following levels:
- Page
- Grid
- Cell
- Frame
- Component
- Attribute
- Field
- Flow
Each of these levels has a specific template that manages the rendering of the element.
Layout Code
Each layout template is written using different languages: HTML, JavaScript, WebRatio Generation Tags, Groovy and JSTL.
Each of the languages used to express a layout template belongs to one of two categories: Generation Time Languages or Runtime Languages.
The first category, Generation Time Languages, is used to obtain the JSP page. It includes Groovy Scripts and WebRatio Generation Tags.
Each Layout Template contains an implicit Groovy variable that takes the name of the element for which the layout is made. This variable contains the XML structure of the item and it is used by Groovy and WebRatio Generation Tags to assign all of the element properties. In the page layout, the variable Page of type Element will contain all of the page XML structure.
- Groovy Scripts are used to retrieve model information from the XML structure of the model. Lines of Groovy are shown in brown.
def detailsId = unit["id"];
- WebRatio Generation Tags are shortcuts to retrieve the most common model information; they encapsulate Groovy Scripts lines. They are shown in blue.
<wr:Id context="unit"/>
The other category, the Runtime Languages is used to get the HTML page to serve to the user. It includes HTML, JavaScript, JSP and JSTL.
- HTML is used to create the skeleton of the page. HTML lines of code are shown in black.
<div id="details">
</div>
- JavaScript is used to interact with the page structure defined in HTML. Lines of JavaScript are shown in black.
var detailsDiv = document.getElementById(‘details’);
- JSP is used to create dynamic content inside the page. Lines of JSP code are shown in black.
<% JSP %>
- JSTL is a tag set to dynamically create JSP code. JSTL lines of code are shown in orange.
<c:when test=”${dataSize gt 0}”
Here is an example of code for a page layout, where you can see highlights with different colors for all the languages.
Layout Generation
All the pages generated by WebRatio are standard JSP pages and are obtained through a specific process, involving the following generation and compiling steps:
- Starting from the highest item in the outline hierarchy, each template is executed.
- WebRatio tags are expanded into the corresponding Groovy code.
- Groovy scripts and expressions are executed and replaced by the corresponding JSP and JSTL code.
- Whenever the template calls another template belonging to the layout hierarchy you begin again from step 2.
- When all of the code of the highest item of the layout hierarchy is executed, and also for the recalled templates, a JSP page is generated into the deploy folder.
- At run time, the JSP code and JSTL tags are evaluated and substituted with data contained in the component beans.
Component Example
All of the things explained here apply to each element of the layout hierarchy.
Consider, for instance, the Component Layout Template, and more specifically the Details Component Layout.
This Details Component, based on the Product Entity, shows the code, description, highlighted, name, price and thumbnail, and has no outgoing flows.
The settings for this component and all of the properties are mapped to an XML structure where also all the layout elements are listed.
The Layout Hierarchy, starting from the Details Component, is:
The layout templates for these three model elements can be configured directly from the Layout Properties View.
Here is an basic example of Details Component Layout Template.
To learn more about each single WebRatio Generation Tag, please review the WebRatio product documentation included with WebRatio Platform.