| Wiki Markup |
|---|
{noprint}{float:right|width=300px|background=lightgrey|border=solid blue 2px|margin=10px|padding=8px}
*Contents*
{toc:all=true|depth=4|excerpt=true|indent=14px}
{float}{noprint}
*Change log:*
|| *Date:* || *Author:* || *Version:* || *Changes:* || Completed || *Ext.* || *Int.* || *Is in Core* || Jira Ref. ||
| {page-info:created-date|dateFormat=dd MMMM yyyy} | {page-info:created-user} | 1.0.1 | Doc. created | Yes/No | x | | N/A | |
h2. 1 - Purpose of Document
This document provides the overall technical details and design of implementing and using the functionality as specified in section 2 - Introduction. This document will not cover implementation details -- for this the code base should be inspected.
h2. 2 - Introduction
Using the workflow builder we will cover all the steps and aspects of creating, designing and styling of a web page. The following sections require an existing web workflow with at least an Html Activity so it is recommended to go through this [section|zk:2 Creating the Web Workflow] first.
h2. 3 - Developing a Web Page
h3. 3.1 - Setting Up the Web Page
# Open an existing web workflow or create a new one.
# Open an existing HTML activity from the web workflow at step 1 by double clicking on it.
This will open a dialog window with multiple tabs, *Layout* being the focus in this step (Figure 1)
\\
\\ !wf-builder-html-page-layout.jpg|border=1!
*Figure 1.* The Layout tab of an HTML activity
\\
\\
The window has two fields:
\\
#* layout type - has three options:
#** MAIN - the page will be used as a layout page
#** NORMAL - this is the default selection if nothing is chosen from the list
#** MENU - the page can be used as <zone> activity
#* layout main page - contains the name of the template that defines the layout
\\
\\
An example of zul coding of the 4-zones template is listed below:
\\
\\
{code}
<?page title="new page title" contentType="text/html;charset=UTF-8"?>
<zk>
<div height="100%" width="100%">
<grid width="100%" height="100%">
<rows>
<row>
<cell colspan="2" width="100%">
<zone id="NORTH" />
</cell>
</row>
<row>
<cell>
<zone id="WEST" />
</cell>
<cell height="100%">
<zone id="CENTER" />
</cell>
</row>
<row>
<cell colspan="2" width="100%">
<zone id="SOUTH" />
</cell>
</row>
</rows>
</grid>
</div>
</zk>
{code}
After selecting the layout, the zones(tiles) that fill the layout must be configured.
\\
\\
# Double click the activity and navigate to *General* tab.
The General tab will display placeholders for all the zones that are in the template selected in step 2. A zone can be filled either with static content from an Article or with dynamic content from another HTML activity. When a zone is configured as an *Article* type, the list of articles is loaded from the Resource Library. When a Zone is configured as *Activities*, the list is populated with the HTML Activities in the current workflow that *are defined as MENU in the Layout tab*. Figure 2 shows how to select the zones.
\\
\\ !wf-builder-zone-setup.jpg|border=1!
*Figure 2.* Zone setup window
{note}Remember that for HTML activities to become available as zones they have to be configured as MENU in the layout tab.{note}
As you may have noticed, even if we have defined four zones in the template, the zone with the id *CENTER* is not configured in the General tab. By (framework) convention the _<zone id="CENTER" />_ will always be opened and handled in the *Setup HTML* tab.
h3. 3.2 - Coding the Web Page
This can be done either from Resource Library by editing articles/templates/resources or directly from the workflow builder, in the Setup HTML tab. A short example of ZKoss web page is shown below:
{code}
<zk>
<panel width="100%">
<panelchildren>
<div>
<grid if="${showOrderTime}" zclass="none" width="600px;">
<columns>
<column></column>
<column></column>
</columns>
<rows>
<row>
<label value="Order time" style="font-weight:bold"/>
<label value="@{orderedTime}"/>
</row>
</rows>
</grid>
</div>
</panelchildren>
</panel>
</zk>
{code}
In this case, we assume that the boolean _showOrderTime_ and the string _orderedTime_ have already been defined. The use of attributes to handle data is briefly described in the ZKoss example [here|zk:2 Creating the Web Workflow] and in much more detail in the ZKoss Specification.
In the following sections we will focus on using resources from the Resource Library.
h4. Loading CSS Files
This can be done by using a custom ZKoss component that has to be defined at the top of the script. The syntax is:
{code}
<?component name="cmsCss" macroURI="~./com/CDRator/components/cms/css.zul" inline="true"?>
{code}
Using the above declared component, images can be loaded as follows:
{code}
<cmsCss resourcePath="path_to_css_resource/css_resource_name"/>
{code}
where: _path_to_css_resource_ is the path to an existing css resource in Resource Library, starting from Resources/<WEBAPP> folder
Example:
{code}
<cmsCss resourceId="css/default/style.css"/>
{code}
_Tip: It is recommended for CSS resources to be loaded in the template, to be rendered as soon as possible_
h4. Loading/Using Images
This can be done by using a custom CDRator component that has to be defined at the top of the script. The syntax is:
{code}
<?component name="cmsImage" macroURI="~./com/CDRator/components/cms/image.zul" inline="true"?>
{code}
Using the above declared component, images can be loaded as follows:
{code}
<cmsImage resourcePath="path_to_image_resource/image_resource_name"/>
{code}
where: _path_to_image_resource_ is the path to an existing resource in Resource Library, starting from Resources/<WEBAPP> folder
Example:
{code}
<cmsImage resourcePath="jpg/memorystick_small.jpg"/>
{code}
h4. Including other Articles from the Resource Library
This can be done by using a custom CDRator component that has to be defined at the top of the script. The syntax is:
{code}
<?component name="cmsArticle" macroURI="~./com/CDRator/components/cms/article.zul" inline="true"?>
{code}
Using the above declared component, articles can be loaded as follows:
{code}
<cmsArticle resourceId="article_name"/>
{code}
where: _article_name_ is the exact name of the article in the Resource Library
Example:
{code}
<cmsArticle resourceId="SELFCARE-WEB-Open-Center-FAQ"/>
{code}
h4. Generic Loading of Resources
There are some places where custom CDRator components cannot be used to load a resource, e.g. _src_ attributes on images or background images in CSS files. For this purpose the user has to use the standard servlet that loads resources.
{code}
<style src="servlet/RetrieveResource?resourceId=path_to_resource" />
{code}
where: _servlet/RetrieveResource?resourceId=_ is the standard string of accessing resources from the resource library and
_path_to_resource_ is the path to an existing resource in Resource Library, starting from Resources/<WEBAPP> folder
Example:
{code}
<style src="servlet/RetrieveResource?resourceId=css/default/style.css" /> <!-- Example of loading a css from the resource library-->
{code}
{code}
#topmenu{
width:980px;
height:60px;
/*Example of setting the background image*/
background-image:url("RetrieveResource?resourceId=png/menu_back_01.png");
position:relative;
top:60px;
z-index:200;
font-family:Helvetica,Arial;
font-size:14px;
}
{code}
h3. 3.3 - Styling Web Pages
When it comes to styles the ZKoss framework uses the concept of themes and comes with its own set of default themes and styles. So styling can be done at multiple levels. In the next sections we will describe a few approaches on changing the way components and pages look. A complete reference on working with ZKoss styles can be found at [http://books.zkoss.org/wiki/ZK%20Developer's%20Reference/Theming%20and%20Styling]
h4. Changing ZKoss Theme/Colours
The procedure is explained [here|Customers:How to Build and Change ZKoss Theme].
h4. Using Custom Client Defined Styles
It is possible to remove the default CSS class that is applied to a Zkoss tag by disabling the Zkoss CSS class and adding your own. The syntax to do this is:
{code}
<grid id="detailsGrid" zclass="none" class="myCustomCSSClass"/>
{code}
_Note: The_ *{_}none{_}* _Zkoss class is a predefined CSS class so do not try to override it in the customized client CSS file. Also, for this to work,_ *{_}myCustomCSSClass{_}* _has to be defined in the custom CSS and loaded from the Resource Library before using it._
*{_}Tip:_* _Inline styles can be used also but this is not recommended as good practise, because it reduces the code reuse. So it is recommended that all styles should be centralized in CSS files and loaded into Resource Library._
h4. Using Html Tags over ZKoss Tags
Using html tags to design the web page is allowed but is not good practise because:
* the power of Zkoss framework is lost
* the code becomes hard to read and debug
Below is a sample of code that is working but should be avoided in practise:
{code}
<script>
<![CDATA[
function goToURL(url){
document.location.href=url;
}
function gotoSignup(productCode, packageCode){
window.location = "go_to_some_URL";
}
]]>
</script>
<zk>
<html>
<![CDATA[
<div id="topline">
<div id="topline_inner">
<div id="om"><a href="state.zul?***OUTCOME@open_page***&TRANSITION=tran">My Web Page</a></div>
</div>
</div>
<div id="topmenu">
<div id="logo"><a href="http://www.mywebpage.com"><img src="servlet/RetrieveResource?resourceId=png/logo_01.png" alt="mywebpage"/></a></div>
<div id="menuwrap">
<ul id="menu">
<li class="menu_right" id="page"><a href="state.zul?***OUTCOME@open_page***&TRANSITION=tran">My Web Page</a></li>
</ul>
</div>
</div>
]]></html>
</zk>
{code}
h4. Styling CDRator Custom Components
CDRator framework has defined some custom components like: [Invoices|zk:Invoices], [Usage|zk:Usage Grid], [Options|zk:ProductOptionSelection], [Payments|zk:Payments]. To change the styles on those custom components it is a matter of overriding the class in the custom CSS file (the class names can be found by using an html inspection tool). |
Page Comparison
General
Content
Integrations