(r18) XvwTemplates < WebXEO

WebXEO Web>UnidadeEngenharia>XvwTemplates (revision 18) (raw view)~~EditAttach~~
-- Main.PedroRio - 11 Oct 2012
---+ XEO Components and Templating

*Introduction*

In order to improve the layout customization of existing applications, the concept of "templating" was introduced. This document explains all you need to know in order to use the new "templating" system.

In order to create a component (the old way) you need two classes:
   * The component class
   * The renderer class
The component class holds the properties of the component and the renderer is responsible for the HTML output. The rendering of a component is usually something like this:

_
<verbatim>w.startElement( DIV );
w.startElement( UL );
Iterator<UIComponent> it = component.getChildren().iterator();
while (it.hasNext()){
    Menu m = (Menu) it.next();
    w.startElement (LI);
      w.write (m.getText());
    w.endElement(LI);

}
w.endElement(UL);
w.endElement(DIV);
</verbatim> <div id="_mcePaste">_</div>

Apart from being cumbersome this meant that you had absolutely no chance of customizing the look and feel of a given component (apart from creating a new renderer for the said component). With templating the following scenario is possible when building a component:

   * Component class (with properties)
   * Component Renderer (can be optional)
   * *Component Template* (a file declaring how the component is rendered, HTML + CSS + Javascript)
A template could be something like this:
<verbatim><div>
   <ul>
      <#list this.children as menu>
           <li>${menu.text}</li>
      </#list> 	
   </ul>
</div></verbatim>

The template now declares how the component is rendered and can be switched at runtime by defining a new template for same component. The template has access to "<strong>variables</strong>" which *will be replaced by their values at runtime*. Modern components require some help of javascript and css, as such it's possible to include that type of content in your templates. You can find more information in the Javascript Section.
---+++++ Template Engine

_

The template system used in XEO builds upon the [[http://freemarker.org/][Freemaker]] Library which has its own template language. The manual for creating Freemarker [[http://freemarker.org/docs/index.html][templates can be found here]]. If you're not familiar with template systems we recommend checking the [[http://en.wikipedia.org/wiki/Template_engine_(web)][wikipedia page]] for a more general approach and the [[http://www.freemarker.org][Freemarker]] page for a more specific one. The main ideia behind templating engines is rendering content using a variable-replacing system, meaning that if you want to render a "Hello" message followed by a username, you would create a template like the following:
<verbatim>Hello ${username}</verbatim>

And pass the variable "<strong>username</strong>" to the template engine to get something like "Hello John" or "Hello Bill". There are a lot more things you can do inside a template (like iterating through a list, using if/else statements and a lot more (check the [[http://freemarker.org/docs/index.html][Freemarker]] manual for a full list)).

_
---+++++ Template Syntax Examples

_

The following template is a sample of the ActionButton template component. Notice the use of the _&lt;#if&gt;_ directive to choose whether or not the component should render the HTML. Notice the use of the _clientId_, _id_, _width_ and _label_ properties to generate the HTML div and button with the correct attributes.

<verbatim><#if !this.renderedOnClient>
	<div id='${this.clientId}'>
		<button id='${this.id}_btn' class='xwc-actionbutton' style='min-width;${this.width}px'>
			${this.label}
		</button>
	</div>
</#if></verbatim>

_

In the following example (extracted from the Tabs component) you can see the use of lists and a special directive( _@xvw_facet_ - explained later in this document)

<verbatim><#list this.children as tab>
   <div id='${tab.id}' class='xwc-tab-content'>
   </div>
</#list>    
<@xvw_facet /></verbatim>

You can also use/include Javascript and generate Javascript dinamically (this example generates a JQuery call to create a panel).

<verbatim><@xvw_script position='footer'>
	$(function() {
		$( '#${this.id}' )
		<#if this.collapsible>
			.collapsiblePanel(true);
		<#else>
			.collapsiblePanel(false);	
		</#if>
	});
</@xvw_script></verbatim>

_
---+++++ Template Variables - What's available

_

At the heart of the template engine there are the variables. When using a template combined with a component you have access to all the properties available in the component. Each component is exported (into its own template) as the __this__ variable and the properties of the component can be accessed like the following:

_${this.propertyName}_

For the _Section_ component which has properties like __visible__ and __title__ you can do:

_${this.<strong>visible</strong>}_ or _${this.<strong>title</strong>}_

You also have access to any method the component has that follows Java Beans convention. If the component has *getCustomValue()* method, you can use ${this.<strong>customValue</strong>} (with the getCustomValue method not being related with any instance of a XUIBaseProperty).

When you're creating a new template for an existing component refer to the component's API to check which variables are available.

_
---+++++ Generic Template Component

_

You may need to create a view and "use" a specific template inside that view, but not necessarily associated with a specific component. In order to support that situation, the *Template* component was created. *Template* has no properties other than the standard ones provided by XUIComponentBase, but it has an interesting feature: *Any* property that is declared in the XML definition, will be passed to the template as *${this.properties.PROPERTY_NAME}* . The properties can be *literals* or *expressions,* meaning you could have the following in the viewer:
<verbatim><xvw:template template='myCustomTemplate.ftl' customProperty='World' fruit='#{viewBean.myValue}'/></verbatim>

And a template like the following:
<verbatim><div>
	Hello ${this.properties.customProperty} my favorite fruit is ${this.properties.fruit}!
</div></verbatim>

And a bean with:
<verbatim>public String getMyValue(){
	return "Orange";
}</verbatim>

Which would render the following:
<verbatim><div>
	Hello World my favorite fruit is Orange!
</div></verbatim>

---+++++ Using an XEO Object / List / Lov in a generic Template

If you need to pass an XEO Object / List to a template, you need two things:

Declare a property in the template that retrieved the object from the Bean

&lt;xvw:teamplate template='test.ftl' someName='#{beanId.propName}'&gt;

In the bean do the following:
<verbatim>import netgest.bo.xwc.components.template.wrappers.*;
public XeoWrapper getPropName(){
	boObject obj = load(); OR boObjectList list = loadList();
	return WrapperFactory.wrapObject(obj); or return WrapperFactory.wrapList(list);
}</verbatim>

_
---+++++ Where to place your templates:

When you create a template for a component and reference the template by its name using the __template__ property (now available in *every* component), XEO will search for the template in the following places:
   * A directory named "templates" inside your default web app (i.e. will start searching in _webapps/default/templates/_ + _pathToTemplate_).
   * The source code root directory
Imagine a component declaration like the following:
<pre><verbatim><xvw:actionButton template='vanilla/myTemplate.ftl' /></verbatim>
</pre>

The _template loader_ will search for the template in _"webapps/default/templates/vanilla/myTemplate.ftl"_ and, if it does not find the template, searches in _"src/vanilla/myTemplate.ftl"_, if the template is not found in any of the locations, an error is thrown.

_
---+++++ Component Properties (regarding Templates)

The XUIComponentBase class (the class from which all components derive) was added two new properties (both *binding* properties *whose value can be retrieved from the bean*):
   * _template_
   * _templateContent_
The __template__ property allows you to reference the template to be used in the component's rendering by it's location (i.e. the location of the file with the template content). See the previous section for more detail on how template loading is done.

The __templateContent__ property allows you to dinamically generate the template's content in the bean and pass it to the component. You need to generate a template compliant with the Freemarker engine and return it as a String to the component: The following example depicts this situation:

(In the Viewer)
<pre><verbatim><xvw:actionButton templateContent='#{viewBean.content}' /></verbatim>
</pre>

(In the Bean)
<verbatim>public String getContent(){
   return "Hello ${username}"
}</verbatim>

_

_
---+++++ Special Directive Processing

There are special intructions that are available for use in a template. There instructions are:
   * *xvw_script (Javascript inclusion)*
   * *xvw_css (CSS inclusion)*
   * *xvw_header (Page Header manipulation)*
   * *xvw_facet (Children rendering)*
   * *XUICommand (Dynamic creation of Command components)*
   * *XUIInput (Dynamic creation of Input Components)*
The following sections explain each directive in detail.

_
---+++++ XVW_Script : Including Javascript

_

If you need to include a Javascript file for use in a template, or add an inline call to a Javascript function, you need the _&lt;@xvw_script&gt;_ directive. It allows you to include files and inline calls at the header or footer of the page. The XVW_Script directive has the following properties:

   * position ( _footer / header / inline_ ) : The position where the script will be added (relative to the page, defaults to _header_)
   * id : The id of the script (optional, defaults to a dinamically generated id). If two scripts share the same ID only the last one will be added to the page
   * src : The path to the script to include relative to the root of the web application (if it's an inline call to a script, use the body of the directive)
Example of how to include a script in a template:
<pre><verbatim>
<@xvw_script position='header' id='jquery' src='javascript/jquery/jquery.min.1.8.2.js' /></verbatim>
</pre>

Example of how to add a call to a javascript function in a template
<pre><verbatim>
<@xvw_script position='footer'>
     alert(${this.id});
</@xvw_script></verbatim>
</pre>

_
---+++++ XVW_CSS : Including CSS

<em><br />If you need to include a CSS file for use in a template, or add a CSS style inline you need the _&lt;@xvw_css&gt;</em> directive. It allows you to include files and inline styles at the header or footer of the page. The XVW_CSS directive has the following properties:

   * position ( _footer / header / inline_ ) : The position where the css will be added (relative to the page, defaults to _header_)
   * id : The id of the script (optional, defaults to a dinamically generated id). If two CSS share the same ID only the last one will be added to the page
   * src : The path to the CSS to include relative to the root of the web application (if it's an inline style, use the body of the directive)
Example of how to include a CSS file in a template
<pre><verbatim>
<@xvw_css position='header' src='path/to/myStyles.css' /></verbatim>
</pre>

Example of how to add inline styles in a template

<pre><verbatim><@xvw_css position='header'>
    .myStyle{
        color:red;
        font-size:13px;
     }
</@xvw_css></verbatim>
</pre>

_
---+++++ XVW_Header : Writting to the page header

If there's the need to add a special header to the page (like adding a meta tag to a page, or something like that) you can use the _&lt;@xvw_header&gt;_ directive

Example of adding a meta tag
<verbatim><@xvw_header>
    <meta name="description" content="Awesome Description Here">
</@xvw_header></verbatim>

Or adding Google Chrome Frame
<verbatim><@xvw_header>
	<meta http-equiv="X-UA-Compatible" content="chrome=1">
</@xvw_header></verbatim>

_
---+++++ XVW_Facet : Processing Component Children, integrally or partially

The _&lt;@xvw_facet&gt;_ directive is related to the processing of child elements in templates. Several components are "childless", meaning they don't have children to be rendered. While other components can have children and may require that their children be rendered in a special place inside their own template. The _&lt;@xvw_facet&gt;_ directive allows you to specify exactly where children are rendered. Lets see an example with the Section component's template:

<verbatim><fieldset id='${this.id}' class='ui-widget ui-widget-content xwc-section'>
    <legend style='ui-widget-header ui-corner-all xwc-legend'>
    ${this.label}
    </legend>
    <@xvw_facet />
</fieldset></verbatim>

The section component is basically a fieldset wrapping the content of its children. As such, the template draws the _fieldset_ and _legend_ tags, and then instructs the template (through the _&lt;@xvw_facet&gt;_ directive) to render its children *inside* the fieldset. If a section component has as children a set of rows, they'll be rendered inside the fieldset.

*But what if you know you have only a specific set of children and you want to render them individually in certain places?* Well The _&lt;@xvw_facet&gt;_ directive is able to help you again. If you need a component (let's assume the generic "template" component) with two children and in the template of that component you need to render those children in specific places then you need to declare each children wrapped in a _f:facet_ component and give the _facet_ a name. That name will be used in the template (with the _&lt;@xvw_facet&gt;_ directive), see the following viewer example:
<verbatim><xvw:template template='myTemplate.ftl'>
       <f:facet name='button'>
             <xvw:actionButton>
       </f:facet>
	<f:facet name='grid'>
             <xvw:gridPanel >
        </f:facet>
</xvw:template></verbatim>

And a template like the following (see the use of the _&lt;@xvw_facet&gt;_ directive with the _name_ property to render the specific child in that position) :
<verbatim><div id=${this.id}>
    <fieldset>
       <@xvw_facet name='button' />
    </fieldset> 
    <ul>
	<li>TESTE </li>
    </ul>
<@xvw_facet name='grid' />
</div></verbatim>

Each child must have a unique id when wrapped inside a _f:facet_ component.

---+++++ XUICommand : Dynamic creation of Command Components

In order for you to invoke an action of the server side. This typically requires you to declare a xvw:menu component in the viewer that registers the action available in the bean, and after that in th template you need to invoke something like ${xvw.js.ajaxCommand('formId','commandId')} which can be a dificult task if that template is container in a viewer which is container in another viewer. The formId and commandId in these situations may be unknown. To help with that, we created a command create mechanism right in the template. This is best show with an example:

&lt;@XUICommand id="login" serverAction='!{viewBean.login}'&gt;

&lt;button name='${login.clientId}' onclick='${xvw.js.ajaxCommand(login)}' /&gt;

Using the &lt;@XUICommand&gt; directive (with the approriate, required, _id_ and _serverAction_ properties set) you can dynamically create a command that can be passed to the xvw.js.ajaxCommand function (which in turn will generate the javascript invocation and finding the approriate id's for form and command). What are the restrictions? Well, when you set the _id_ in the &lt;@XUICommand&gt; directive that _id_ will be available in template's context as a variable (much like the _xvw_ and _this_ variables). The biggest restriction at the moment is when declaring the serverAction, you need to declare it like _!{beanId.method}_ much like what you use in a viewer with _#{beanId.method}_. The main issue is that since the # character is special to the template language.

This makes the creation of commands to invoke server-side actions very simple.
---+++++ XUIInput : Dynamic creation of Input Components

In the same way, you can create dynamic input fields to help with from creation. See the following example:

&lt;@XUIInput name='username' valueExpression="!{viewBean.username}" /&gt;

&lt;input name='${username.clientId}' value='${username.value}' /&gt;

The &lt;@XUIInput&gt; directive is used to create an input command and assign it a name (which makes it available in the context as a variable) and a binding expression. The binding expression has the same issue as the XUICommand directive (must start with a '!' instead of a '#'). The value submited by the use will be placed in the "username" variable in the bean using the necessary setUsername method that must exist)

_
---+++++ Adhoc Template Processing

_

If for some reason you need to process a template within your code you use can the class _netgest.bo.xwc.components.template.util.CustomTemplateRenderer_, which has two methods:

<verbatim>public static String processTemplateFile(String templateName, Map<String,Object> context);
public static String processTemplate(String templateContent, Map<String,Object> context);</verbatim>

The _processTemplateFile_ method receives the name of a template (same rules defined earlier apply to finding templates) and a Map with the mappings between variables and their values to be applied in the template.

The _processTemplate_ method receives the content of the template as a String and a Map with the variables, for instance you could have the following code in your application:
<verbatim>public String processCustomActionAndGenerateHtml(){
	// Business logic  
	String template = "Hello ${user} ";
	Map<String,Object> map = new HashMap<String,Object>();
	map.put( "user" , "John" );
	String result = CustomTemplateRenderer.renderTemplate( template , map );
	return result;
}</verbatim>

And the result would be:
<verbatim>Hello John</verbatim>

_
---++++ XEO Components:

Several components were created to integrate individual objects, object lists and lovs with templates. The details for each component is in the following sections:
---++++++ Xeo Objects Syntax inside templates:

If you're familiar with XEO's Java API you know that to get the value of an instance attribute you need to do instance.getAttribute("name").getValueString() and to get a bridge/collection instance.getBridge("bridgename").

Inside the templates we've made things simpler and if you you're rendering an object (using xeoobject component) using a template you could do:
   * *${this.xeoobject.name.value} or ${this.xeoobject.name$}* - render the value of an attribute
   * *${this.xeoobject.name.label}* - render the label of an attribute
   * *${this.xeoobject.name.disabled}* - check if the attribute it's disabled
   * *${this.xeoobject.name.required}* - check if the attribute it's required
   * *${this.xeoobject.name.visible}* - check if the attribute it's visible
   * *${this.xeoobject.name.islov}* - check if the attribute it's based on a lov
   * *${this.xeoobject.name.lovlabel}* - if the attribute it's based on a lov render the label associated with the value
   * *${this.xeoobject.name.syscardid}* - if the attribute it's an object render's the cardid
   * *${this.xeoobject.name.syscardidimg}* - if the attribute it's an object render's the cardid with an icon
If you're rendering a list or a bridge (using xeolist component) the same rules apply, but you need to iterate over the list in order to render it's itens:

example:
<pre><verbatim><ul>
  <#list this.list as item>
	<li><a href="none.html">${item.username.value}</a></li>
  </#list>
</ul></verbatim>
</pre>

XEO it's an OOP platform, so you could have complex structures described in you're objects. Using the templates you could easily navigate in those structures and render all the information that relates to them. For instance if you have and object person that has a relation to an object address and that address has an attribute called city, in order to render the city value you can do:

*${this.xeoobject.address.value.city.value} or ${this.xeoobject.address$.city$}* (if you end an attribute name with the '$' char<br />to the template processor it's the same as getting it's value)

In the previous example if the same person object as a bridge/collection called friends, and this friends are also persons. To render the city of each person friends you have to write a template like this:
<pre><verbatim><ul>
  <#list this.list as person>
    <#list person.friends as friend> 
       <li><a href="none.html">${friend.address$.city$}</a></li>
    <#/list>
  </#list>
</ul></verbatim>
</pre>

<span style="color: #630000; font-size: 12px; font-weight: bold; line-height: 1em;">Xeolist (xeo:xeolist)</span>

The Xeolist component allows you to display a list of objects using a template. The component has the following properties:
   * *boql* : The boql expression to execute and retrieve the list of objects
   * *name* : The name of the component (required to do pagination)
   * *dataSource*: The dataSource of the list (XEOObjectListConnector), if this attribute is present it will be used instead of the boql
   * *page*: The page you want to retrieve. Default is 1
   * *pagesize*: The size of each page. Default is 30
   * *navigation*: The type of navigation/pagination you want to do (default, ajax). Default do pagination using GET and Ajax does an Ajax Request. Default is default
You can use the component as follows:
<pre><verbatim><xeo:xeolist name='UserNameList' boql='select Ebo_Perf' template='list.ftl' /></verbatim>
</pre>

And the template list.ftl:
<pre><verbatim><ul>
<#list this.list as item>
	<li><a href="none.html">${item.username}</a></li>
</#list>
</ul></verbatim>
</pre>

This will generate a list with a link for the first 30 username's in the application

If you want to do Pagination in the previous example you could change the template do be:
<verbatim><ul>
<#list this.list as item>
	<li><a href="none.html">${item.username}</a></li>
</#list>
</ul> 
<a href="${this.first}">First</a>
<a href="${this.previous}">Previous</a>
<a href="${this.next}">Next</a>
<a href="${this.last}">Last</a> Page ${this.page} of ${this.pages}</verbatim>

In the previous example the pagination uses the default GET navigation type. If you want to use ajax as the navigation type, you're xeo:list component needs to be inside a form (ex: xvw:form) and in the template you need to change the &lt;a href... to button's or use javascript: in the href property. Please note that you've have to do your own validations inside the template if you want to hide the "next" option when you're in the last page or the "previous" option when you're in the first page. This can be done using the variables <em>${this.page} </em>and<em> ${this.pages} </em>and freemarker conditional operators<em>. </em>
<verbatim><ul>
<#list this.list as item>
	<li><a href="none.html">${item.username}</a></li>
</#list>
</ul>
<#if (this.page?number>1)> 
   <a href="${this.first}">First</a>
</#if>
<#if (this.page?number<this.pages)>
   <a href="${this.previous}">Previous</a>
</#if>
<a href="${this.next}">Next</a>
<a href="${this.last}">Last</a> Page ${this.page} of ${this.pages}</verbatim>

Inside the template of a xeolist the properties and functions you can use are:
   * *${this.list}* - list of XEO Objects passed in the datasource or boql of the component (see <span style="color: #630000; font-size: 12px; font-weight: bold; line-height: 12.34375px;">Xeo Objects Syntax inside templates</span>)
   * *${this.first}* - renders the URL or Ajax request to get the first page
   * *${this.previous}* - renders the URL or Ajax request to get the previous page
   * *${this.next}* - renders the URL or Ajax request to get the next page
   * *${this.last}* - renders the URL or Ajax request to get the last page
   * *${this.page}* - the number of the current page (returns a String)
   * *${this.pages}* - total number of pages available in the list
   * *${this.recordCount}* - total number of records/rows available in the list
   * *${this.gotopage(int pagenumber)}* - renders the URL or Ajax request to go to the page specified in pagenumber
   * *${this.applypagesize(int pagesize)}* - renders the URL or Ajax request to apply the pagesize specified to the current list
---++++++ Xeoobject (xeo:xeoobject)

The Xeoobject component allows you to associate a single instance with a template. It has the following properties
   * *boui* : The boui of the object to be used
   * *object* : a boObject instance that has to be evaluated in runtime in a Bean, if this attribute is present it will be used instead of boui
   * *name* : The name of the component
You can use the component like the following:
<pre><verbatim><xeo:xeoobject boui="56677" name="var" template='site/menus.ftl' /></verbatim>
</pre>

And use a template like:
<verbatim><div>
    <span>${this.xeoobject.name.value}</span>
    <span>${this.xeoobject.age$}</span>
    <ul>
	<#list this.xeoobject.bridge.value as menu>
 		<li>${menu.name}</li>
	</#list>
    </ul>
</div></verbatim>

---++++++ Sqllist (xeo:sqllist)

The Sqllist component allows you to display the rows/fields of an SQL query using a template, it works similar to xeolist but instead of displaying XEOObjects it's used to display database records . It has the following properties:
   * *sql* : The sql expression to execute and retrieve the list of database records
   * *name* : The name of the component (required to do pagination)
   * *dataSource*: The dataSource of the list (SQLDataListConnector), if this attribute is present it will be used instead of the sql
   * *page*: The page you want to retrieve. Default is 1
   * *pagesize*: The size of each page. Default is 30
   * *navigation*: The type of navigation/pagination you want to do (default, ajax). Default do pagination using GET and Ajax does an Ajax Request. Default is default
You can use the component like the following:
<pre><verbatim><xeo:sqllist sql="select name,age from person" name="ListPerson" template='site/sqllist.ftl' /></verbatim>
</pre>

And use a template like:
<verbatim><div>
    <ul>
	<#list this.list as item>
 		<li>${item.name.value}</li>
                <li>${item.age.value}</li>
	</#list>
    </ul>
</div></verbatim>

In a Sqllist inside a template you've access to the same properties used in a Xeolist. In the fields you only have access to <em>field.value </em>and<em> field.label </em>(if the database supports it), the other properties (visible, enabled, etc...) are only available to XEOObjects.
---++++++ Genericlist (xeo:genericlist)

The Genericlist component allows you to display a list of any type of information. You have to use a GenericDataListConnector and wrapp your data inside of it, or you could implement a new DataListConnector. Like the Sqllist it works similar to xeolist but instead of displaying XEOObjects it's used to display information from any source wrapped in a record/field manner . It has the following properties:
   * *name* : The name of the component (required to do pagination)
   * *dataSource*: The dataSource of the list (DataListConnector)
   * *page*: The page you want to retrieve. Default is 1
   * *pagesize*: The size of each page. Default is 30
   * *navigation*: The type of navigation/pagination you want to do (default, ajax). Default do pagination using GET and Ajax does an Ajax Request. Default is default
You can use the component like the following:
<pre><verbatim><xeo:genericlist dataSource="#{viewBean.connector}" name="ListGeneric" template='site/genericlist.ftl' /></verbatim>
<p><span style="color: #000000; font-size: small; white-space: normal;">Bean:</span></p>
<p><span style="font-family: 'Courier New', courier, monaco, monospace; font-size: 12pt;"> public GenericDataListConnector getConnector() { </span></p>
<verbatim>		ArrayList<Person> arr= new ArrayList<Person>();
		arr.add(new Person("Antonio","Cruz","34"));
		arr.add(new Person("Antonio2","Cruz2","35"));
		arr.add(new Person("Antonio3","Cruz3","36"));
		connector.createColumn("name","Name");
		connector.createColumn("lastname","Last Name");
		connector.createColumn("age","Age");
		Iterator<Person> it = arr.iterator();
		while (it.hasNext()) {
			Person currPerson=it.next();
			connector.createRow();
			connector.createRowAttribute("name", currPerson.getName());
			connector.createRowAttribute("lastname", currPerson.getLastname());
			connector.createRowAttribute("age", currPerson.getAge());						
		}
		return connector;
	}</verbatim>
</pre>

And use a template like:
<verbatim><div>
    <ul>
	<#list this.list as item>
 		<li>${item.name.label} - ${item.name.value}</li>
                <li>${item.age.label} - ${item.age.value}</li>
                <li>${item.lastname.label} - ${item.lastname.value}</li>
	</#list>
    </ul></verbatim>

<span style="color: #7a4707; font-family: 'Courier New', courier, monaco, monospace; font-size: 12pt;">&lt;/div&gt;</span>
---++++++ Arraylist (xeo:arraylist)

The Arraylist component allows you to display a list of java Objects wrapped inside an ArrayList. It doesn't use Connectors , so the rules for rendering fields and pagination do not apply to this component. It has the following properties:
   * *dataSource*: The dataSource of the list (ArrayList&lt;Object&gt;)
You can use the component like the following:
<pre><verbatim><xeo:arraylist dataSource="#{viewBean.persons}"  template='site/arraylist.ftl' /></verbatim>
<p>Bean (Person is a object with the properties Name, Age and Lastname):</p>
<verbatim>public ArrayList<Object> getPersons() { 
		ArrayList<Person> persons= new ArrayList<Person>();
		persons.add(new Person("Antonio","Cruz","34"));
		persons.add(new Person("Antonio2","Cruz2","35"));
		persons.add(new Person("Antonio3","Cruz3","36"));
		return persons;
	}

And use a template like:</verbatim>
</pre> <verbatim><div>
    <ul>
	<#list this.list as item>
 		<li>${item.name}</li>
                <li>${item.age}</li>
                <li>${item.lastname}</li> 
	</#list>
    </ul></verbatim>

<span style="color: #7a4707; font-family: 'Courier New', courier, monaco, monospace; font-size: 12pt;">&lt;/div&gt;</span>
---+++++ Error in Template Processing

Errors in template processing should be printed directly in the output stream as well as in the console (with a stack trace) for easy problem detection (it may not render very nicelly in all situations but you'll get to notice the problem)

_
---+++++ Context Variables

_

There a number of context variables which can be used in a template, namely:

   1 Message Bundles, declared in the viewer
   1 A Wrapper to invoke the javascript API
   1 Values stored in the bean/beans associated to the various viewers
If in a given viewer you declared the property localizationClasses='path.to.a.localization.Class,path.to.another.localization.Class' and that viewer has a template in it. You can use those message bundles in the template like the following (let's assume inside one of the bundles there's a MESSAGE key)

${xvw.bundles.MESSAGE}

And it will render the MESSAGE inside the template. Notice the "<em>xvw.bundles</em>". Everything provided by the framework is inside the xvw variable/namespace. As you'll see in the following examples.

If you are creating a component that needs to make Ajax calls and don't want to hardcode the reference to the Javacript function you can use the provided variable name XVWScripts and call the getAjaxCommand(Component) method, like in the following example (extracted from the template of the ActionButton component):
<verbatim>$( '#${this.id}_btn' ).button().click( function () { ${xvw.js.ajaxCommand(this)}; return false; })</verbatim>

In this situation we're generating the Ajax call for the "this" component. The following functions are available

   * xvw.js.ajaxCommand(component)
   * xvw.js.ajaxCommand(component,value)
   * xvw.js.ajaxCommand(component,value,type)
   * xvw.js.command(target,component)
   * xvw.js.command(target,component,value,type)
   * xvw.js.ajaxCommand(containerId,commandId)
   * xvw.js.ajaxCommand(containerId,commandId,value)
   * xvw.js.command(containerId,commandId)
   * xvw.js.command(containerId,commandId,value)
The parameter component is of type XUIComponentBase, specifically it must be a command). Parameter "value" is a string. Parameter "type" is a string with either "VAR" or "LITERAL" (to mark if you want to pass a literal value (LITERAL) or a javascript variable (VAR). An example:

*${xvw.js.ajaxCommand(component,'x','LITERAL')}* will invoke the command with value 'x', while:

var x = 99;

<strong>${xvw.js.ajaxCommand(component,'x','VAR')} </strong>will invoke the command with value '99'

---++ Template Examples

Here you can find some template examples:
---++++++ Adding a javascript file

_
<verbatim><@xvw_script src='jquery-xeo/xwc-panel.js' /></verbatim>

_
---++++++ Adding an inline javascript function

_
<verbatim><@xvw_script position='header' id='xvw-flattree' >
XVW.showHideMenu = function (elemParent){
	var elem = $(elemParent).next();
	elem.toggle();
	if (elem.hasClass('xwc-tree-panel-highlighted'))
		elem.removeClass('xwc-tree-panel-highlighted');
	else
		elem.addClass('xwc-tree-panel-highlighted');		
}
</@xvw_script></verbatim>

_
---++++++ Rendering HTML only if the component is not rendered. Also, telling the location of where children should be rendered

_
<verbatim><#if !this.renderedOnClient>
	<div id="${this.clientId}">
		<div id="${this.id}" class='xwc-panel' title='${this.title!}'>	
			<@xvw_facet />
		</div>
	</div>	
</#if></verbatim>

_
---++++++ Adding a script to initialize a jQuery component (with rendering logic)

_
<verbatim><@xvw_script position='footer'>
	$(function() {
		$( '#${this.id}' )
		<#if this.collapsible>
			.collapsiblePanel(true);
		<#else>
			.collapsiblePanel(false);	
		</#if>
	});
</@xvw_script></verbatim>

_
---++++++ Creating a list (Html select ) from a map (with a selected value on the "select" element)
<verbatim><select style='width:100%' id='${this.id}' name='${this.clientId}'>
	<#list this.lovMap?keys as item> <#-- Iterate through the keys of the map -->
		<#if (this.lovMap[item] == this.value!)> <#-- Get the value from the map -->
			<option value='${item}' selected='selected'>${this.lovMap[item]}</option>
		<#else>
			<option value='${item}'>${this.lovMap[item]}</option>	
		</#if>
	</#list>	
</select></verbatim>

_
---++++++ Using the "switch" expression on an Enum value

_
<verbatim><span style='float:left; margin:0 7px 20px 0' 
	<#switch this.messageBoxType>
		<#case "ERROR">
			class='xwc-messagebox-icon ui-icon ui-icon-alert'>
		<#break>	
		<#case "INFO">
			class='xwc-messagebox-icon ui-icon ui-icon-info'>
		<#break>
		<#case "QUESTIOn">
			class='xwc-messagebox-icon ui-icon ui-icon-help'>
		<#break>
		<#case "WARNING">
			class='xwc-messagebox-icon ui-icon ui-icon-notice'>
		<#break>
	</#switch>
</span></verbatim>

_
---++++++ Checking if variable has a value

_
<verbatim><#if menu.actionExpression??> <#-- If menu.getActionExpression has a value then execute what's inside the if --></verbatim>

_
---++++++ Generating jQuery options

_

<verbatim><@xvw_script position='footer'>
$(function() { $( '#${this.id}' )
	.dialog(
		{ 'modal' : ${this.modal?string}
		  ,'width' : ${this.width}
		  ,'height' : ${this.height}
		  ,'title' : '${this.title}' }); });
</@xvw_script></verbatim>

_
---++++++ Comments inside templates:

_
<verbatim><#-- This is a comment --></verbatim>

_

---+ Bean Annotations

There are three new types of annotations that you can use in a XEO Bean. They are

   * XUIWebCommand
   * XUIWebDefaultCommand
   * XUIWebParameter
*XUIWebCommand*

A XUIWebCommand is an annotation you can put in a given method of a bean, like the following:

<verbatim>@XUIWebCommand(name='name',value='test')
public void exampleMethod1(){}</verbatim>

This means that when a viewer (that is associated with this bean) is request with a parameter 'name' and value 'test' it will execute the _exampleMethod1_. Meaning if the browser requests the following _viewers/Viewer?name=test_ the exampleMethod1 method will be invoked

*XUIWebDefaultCommand*

Like the XUIWebCommand but it's a command that will be executed by default when you open a viewer (unless another command was executed)

*XUIWebParameter*

Allows you to set the value of a parameter directly in the bean, for example:
<verbatim>@XUIWebParameter(name = 'paramInUrl', defaultValue='empty' )
public void setSomeParam(String name){
	//Do whatever you want with the value
}</verbatim>

if you call this viewer having this bean with a parameter ?paramInUrl=someValue the String "someValue" will be passed to the setSomeParam method as an argument, if the parameter does not exist in the url, the default value will be passed.

---++ Including resources and XUITheme

In order to control what scripts and CSS are included in each viewer we're now providing the possibility of registering a Theme for each renderkit. By default XEO uses an instance of the _netgest.bo.xwc.frarmework.XUITheme_ interface. Now you can register your own implementation to include whatever scripts and css files in each viewer. In order to do that you need the following:

In the boconfig.xml file, register the renderKit and themeClass you want to use (there are 4 renderKits available in XEO - XEOHTML, XEOJQUERY, XEOXML and XEOV2(@Deprecated)) like the following:

_(by default the XEOHTML rendeKit is used)_
<verbatim><renderKits default='XEOJQUERY/XEOHTML'>
	<renderKit id='XEOJQUERY' themeClass='path.to.class.implementing.XUITheme' />
</renderKits></verbatim>

XUITheme has the following interface

<pre>  <verbatim>public String getResourceBaseUri();
    public void addStyle( XUIStyleContext styleContext );
    public void addScripts( XUIScriptContext styleContext );
    public String getBodyStyle();
    public String getHtmlStyle();</verbatim>
</pre>

The most important methods are the addStyle and addScripts which allow you to decide which scripts will be included (you can check the existing ExtJsTheme and JQueryTheme for reference of included files)

---+ Viewer as A Template and Area Replacing

We've introduced a new feature that allows you to use the viewers much like facelets and templates (http://www.mkyong.com/jsf2/jsf-2-templating-with-facelets-example/). You can create a "Template Viewer" where you define certain areas that can be replaced, like the following example:

<verbatim><xvw:root xmlns:xeo="http://www.netgest.net/xeo/xeo" xmlns:xvw="http://www.netgest.net/xeo/xvw">
    <xvw:viewer beanClass="pt.itds.ams.beans.ToolBarBean" beanId="viewBean">
    <xvw:form>
    	<table>
    		<tr>
	    		<td>
	    			<xvw:insert src='header.xvw' name='header'/>
	    		</td>
    		</tr>
    		<tr>
	    		<td>
	    			<xvw:insert src='default.xvw' name='content'></xvw:insert>
	    		</td>
    		</tr>
    		<tr>
	    		<td>
	    			<xvw:insert src='footer.xvw' name='footer'></xvw:insert>
	    		</td>
    		</tr>
    	</table>
        </xvw:form>
    </xvw:viewer>
</xvw:root></verbatim>

Everything is like it was before, but notice the existance of the xvw:insert components. These components allow you to define "substitutable areas" when using this viewer as a template. These areas can be substituted by other content while providing a default one when a substitution does not occurs. In order to use these components you have to set two attributes:
   * src - Path to the default content to include (a viewer)
   * name - Name of the area (this value will be used to reference this area later on)
A note on the includes of default content, much like the xvw:include component you need to set the content inside a container, in this case use the xvw:container component (see the example bellow for the header.xvw viewer)

&lt;xvw:root xmlns:xeo="http://www.netgest.net/xeo/xeo" xmlns:xvw="http://www.netgest.net/xeo/xvw"&gt;

&lt;xvw:viewer&gt;

*&lt;xvw:container&gt;*

&lt;xvw:outputHtml valueExpression='HEADER'&gt;&lt;/xvw:outputHtml&gt;

*&lt;/xvw:container&gt;*

&lt;/xvw:viewer&gt;

&lt;/xvw:root&gt;

In order for a page to use the template you need to create the viewer with the following declaration:

&lt;?xml version="1.0" encoding="UTF-8"?&gt;

&lt;xvw:root xmlns:xeo="http://www.netgest.net/xeo/xeo" xmlns:xvw="http://www.netgest.net/xeo/xvw"&gt;

&lt;xvw:viewer beanClass="path.to.some.Bean" beanId="viewBean"&gt;

*&lt;xvw:composition template='Template.xvw'&gt;*

*&lt;xvw:define name='content' &gt;*

*&lt;!-- Content to include, can be html or components --&gt;*

*&lt;/xvw:define&gt;*

*&lt;xvw:define name='footer' &gt;*

*&lt;!-- Content to include, can be html or components --&gt;*

*&lt;/xvw:define&gt;*

*&lt;/xvw:composition&gt;*

&lt;/xvw:viewer&gt;

&lt;/xvw:root&gt;

The *first child of the xvw:viewer* component must be a *xvw:composition* with an attribute <strong>template </strong>pointing to the template file (the one with the xvw:insert components). The children of the xvw:composition component *must be xvw:define components*. Each xvw:define component must have a *name* attribute whose value must match the name found in one of the xvw:insert components in the template file. When you do this, the content of each of those xvw:insert components that have a matching name attribute, will be replaced with the xvw:define component's children.
Topic revision: r18 - 2013-06-18 - PedroRio
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar