(r2) XvwTemplates < WebXEO

WebXEO Web>UnidadeEngenharia>XvwTemplates (revision 2) (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 added to (some) existing components and the creation of new "templatable" components is also allowed. This document explains all you need to know in order to use and create 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>

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 component). With component 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)

The component template cound be something like

<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 "variables" which will be replaced by theri 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
<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 Freemarker manual for a full list)).

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

_

The following is a sample of the ActionButton template component. Notice the use of the _&lt;#if&gt;_ directive to choose whether or not the component shoud render the HTML, the use of the clientId, id, width and label properties to generate the HTML divs/buttons

<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 components) you can see the use of lists and a special directive (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 Javascript (explained later in this document) and generate Javascript dinamically (this examples generates a JQuery call to create a panel). This

<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 an XEO 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.visible}_ or _${this.title}_

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.customValue} (even if customValue is not a property of the component)

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 component. In order to suppor that situation, the *Template* component was created. The component 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:
<verbatim><xvw:template template='myCustomTemplate' customProperty='Word' fruit='#{viewBean.myValue}'/></verbatim>

And a template like the following:
<verbatim><div>
	Hello ${this.properties.customProperties} 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 Word my favorite fruit is Orange!
</div></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.
   * The source code root directory

Imagine a component like the following:
<pre><verbatim>
<xvw:actionButton template='vanilla/myTemplate.ftl' /></verbatim>
</pre>

The loader will search for the template in _"webapps/default/templates/vanilla/myTemplate.ftl"_ and, if it does not find the template, 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 base 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 rendering of the component by it's location (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 viewer bean a pass it to the component. You need to generate a compliant with the Freemarker template engine and return as a String to the component, like the following:

(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)*

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 do a Javascript function, you need the XVW_Script 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>
&gt;</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

_<br />If you need to include a CSS file for use in a template, or add a CSS style inline you need the XVW_CSS 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>
&gt;</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>
&gt;</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 directive /&gt;

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

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

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

<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

_

_

Adhoc Template Processing

_

XEOObject / XEOList / Lov

_

Error in Template Processing

_

Wrapper for XVWScripts

_

New Components
Topic revision: r2 - 2012-10-12 - PedroRio
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar