Using Templates, Articles and Resources

Change log:

Date:

Author:

Version:

Changes:

Completed

Ext.

Int.

Is in Core

Jira Ref.

Unknown macro: {page-info}

1.0

Doc. created

Yes

x

N/A

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.

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 /wiki/spaces/zk/pages/107874148 first.

3 - Developing a Web Page

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)

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:
```
<?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>
```
  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.

Figure 2. Zone setup window

Remember that for HTML activities to become available as zones they have to be configured as MENU in the layout tab.

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.

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:

<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>

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 /wiki/spaces/zk/pages/107874148 and in much more detail in the ZKoss Specification.

In the following sections we will focus on using resources from the Resource Library.

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:

<?component name="cmsCss" macroURI="~./com/CDRator/components/cms/css.zul" inline="true"?>

Using the above declared component, images can be loaded as follows:

<cmsCss resourcePath="path_to_css_resource/css_resource_name"/>

where: path_to_css_resource is the path to an existing css resource in Resource Library, starting from Resources/<WEBAPP> folder

Example:

<cmsCss resourceId="css/default/style.css"/>

Tip: It is recommended for CSS resources to be loaded in the template, to be rendered as soon as possible

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:

<?component name="cmsImage" macroURI="~./com/CDRator/components/cms/image.zul" inline="true"?>

Using the above declared component, images can be loaded as follows:

<cmsImage resourcePath="path_to_image_resource/image_resource_name"/>

where: path_to_image_resource is the path to an existing resource in Resource Library, starting from Resources/<WEBAPP> folder

Example:

<cmsImage resourcePath="jpg/memorystick_small.jpg"/>

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:

<?component name="cmsArticle" macroURI="~./com/CDRator/components/cms/article.zul" inline="true"?>

Using the above declared component, articles can be loaded as follows:

<cmsArticle resourceId="article_name"/>

where: article_name is the exact name of the article in the Resource Library

Example:

<cmsArticle resourceId="SELFCARE-WEB-Open-Center-FAQ"/>

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.

<style src="servlet/RetrieveResource?resourceId=path_to_resource" />

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:

<style src="servlet/RetrieveResource?resourceId=css/default/style.css" /> <!-- Example of loading a css from the resource library-->

#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;
}

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

Changing ZKoss Theme/Colours

The procedure is explained here.

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:

<grid id="detailsGrid" zclass="none" class="myCustomCSSClass"/>

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.

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:

<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>

Styling CDRator Custom Components

CDRator framework has defined some custom components like: /wiki/spaces/zk/pages/107874141, /wiki/spaces/zk/pages/107874172, /wiki/spaces/zk/pages/107874068, /wiki/spaces/zk/pages/107874057. 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).