Customize the User Interface with Templates and Snippets

The HTML that is sent to the browser is dependant on the templates and snippets used by the rendering engine. To change the HTML that is generated, you can change the template and snippets that produce the HTML.

Topics

Writing a Custom Snippet
Example of Snippet Customization
Using your Custom Snippet
Do I have to restart the GAS to see the result of changes in my template or snippet files?

We assume that you have read the section How the GWC Uses Web Technologies and understand the principles. This section describes how you modify the default GWC rendering to customize your Web application. Understanding this chapter requires knowledge of CSS and JavaScript. Refer to the tutorials at http://www.w3schools.com to get an overview of these technologies.

Writing a Custom Snippet

To change how a specific interface object is rendered by the snippet-based rendering engine, you modify the snippet itself.

To do this, you need to:

Identify the snippet that is associated with the interface object that you wish to modify.
Identify the language that the snippet is written in. We know that the snippets have template language (for that provides the path to the interface object(s), but the snippets may also include JavaScript and HTML (as with the AJAX theme - Set 1) or may simply be in HTML (as with the PDA theme - Set 3).
Create a copy of the snippet and make your modifications to the copy. Do not modify the snippet that comes installed with the product. If you modify the snippets provided with the product, you will lose your work when you upgrade the product. You can place the copy in a directory of your choosing; when you define the resource for your custom snippet you will be able to specify the path to the snippet file. See Using your Custom Snippet for more information.

Warning! By default, the Genero Application Server caches the template and snippet files; you must either restart the application server to use the latest template and snippet files, or you must start the application server using the --development option. See Installing and Starting the GWC for more information.

Back to the top

Modify a Snippet Example

In this example, the Image snippet is being modified to display differently depending on whether the file being displayed is a Flash file (with a .swf extension) or another type of image file.

Example AJAX Mode (Set 1 Snippets)

For AJAX Mode, we want to customize the Image snippet file so that it uses an HTML object tag instead of an image tag, as the object tag can handle the SWF. We then want to provide conditional code: if it is a Flash File, do x, if it is not a Flash File, do y.

Before Customization

01  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
02  <html xmlns:gwc="http://www.4js.com/GWC">
03  
04  <!-- the head element is ignored -->
05  <head>
06    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
07    <title>Image snippet</title>
08  </head>
09  <body>
10    <!-- the template snippet is the content of the gwc:snippet-root element -->
11    <gwc:snippet-root>
12      <img 
13        gwc:condition="hidden!=1"
14        gwc:attributes="
15          src value ? ImageURI(value) : null; title comment;
16          class (hidden!=2?'':' gHidden');
17        "
18      />
19    </gwc:snippet-root>
20  </body>
21  </html>

After Customization

01  <?xml version="1.0" encoding="UTF-8"?>
02  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
03  <html xmlns:gwc="http://www.4js.com/GWC">
04
05  <!-- the head element is ignored -->
06  <head>
07    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
08    <title>Image snippet</title>
09  </head>
10  <body>
11    <!-- the template snippet is the content of the gwc:snippet-root element -->
12    <gwc:snippet-root>
13      <img
14        gwc:condition="(hidden!=1) &amp;&amp; !contains(value, '.SWF')"
15        gwc:attributes="src value ? ImageURI(value) : null; title comment;class 
            (hidden!=2?'':' gHidden');"
16        style="max-width:480px;margin:10px;padding:20px;background-color:black;"
17      />
18      <object gwc:condition="!hidden &amp;&amp; contains(value, '.SWF')" width="480px" 
          style="margin:10px;">
19        <param name="movie" gwc:attributes="value ImageURI(type == 'Image' ? value : 
          image)"/>
20        <embed width="480px" gwc:attributes="src ImageURI(value)"/>
21      </object>
22
23    </gwc:snippet-root>
24  </body>
25  </html>

Notes

In Line 14, the gwc:condition instruction handles files that are NOT flash files (files without an SWF extension).
In Line 18, the gwc:condition instruction handles files that are flash files (files with an SWF extension).

Example PDA Mode (Set 3 Snippets)

For the PDA example, when a Flash file is found, we simply want the application to inform the user that their device does not support this type of file.

Before Customization

01  <?xml version="1.0"?>
02  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
03  <html xmlns:gwc="http://www.4js.com/GWC" xml:lang="fr">
04  <head>
05    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
06    <title>Image snippet</title>
07  </head>
08  <body>
09    <gwc:snippet-root>
10      <img gwc:condition="!hidden"
11           gwc:attributes="src ImageURI(type == 'Image' ? value : image)
12             ;width (autoscale ? (contains(width, 'px') ? width : number(width)*6 ) : null)
13             ;height (autoscale ? (contains(height, 'px') ? height : number(width)*10 ) : null)
14             ;title comment
15             ;alt comment
16             ;class 'gImage gStyle_'+translate(class, ' -/\#.=+()[]', '____________') +
17               (' gColor_'+style['textColor']) +
18               (tag ? ' gTag_'+translate(tag, ' -/\#.=+()[]', '____________') : '')"/>
19    </gwc:snippet-root>
20  </body>
21  </html>

After Customization

01  <?xml version="1.0" encoding="UTF-8"?>
02  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
03  <html xmlns:gwc="http://www.4js.com/GWC" xml:lang="fr">
04  <head>
05    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
06    <title>Image snippet</title>
07  </head>
08  <body>
09    <gwc:snippet-root>
10      <img gwc:condition="!hidden &amp;&amp; !contains(value, '.SWF')"
11        width="200px"
12        gwc:attributes="src ImageURI(type == 'Image' ? value : image)
13          ;title comment
14          ;alt comment
15          ;class 'gImage gStyle_'+translate(style, ' -/\#.=+()[]', '____________') +
16            (color ? ' gColor_'+color:'') +
17            (tag ? ' gTag_'+translate(tag, ' -/\#.=+()[]', '____________') : '')"/>
18      <div style="border:1px solid orange;
19                  background-color:#F4F4F4;
20                  text-align:center;"
21           gwc:condition="!hidden &amp;&amp; contains(value, '.SWF')">
22                  This animation cannot be displayed<br/>
23                  on this device.</div>
24    </gwc:snippet-root>
25  </body>
26  </html>

Notes

In Line 10, the gwc:condition instruction handles files that are NOT flash files (files without an SWF extension).
In Line 21, the gwc:condition instruction handles files that are flash files (files with an SWF extension).

Back to the top

Using your Custom Snippet

Once you have customized a snippet, you then need to make the snippet available.

Specify a custom snippet for a specific application
Specify a snippet for all applications

Specify a customized snippet for a specific application

If you only want to apply your customized snippet on a per application basis, you would override the resources for the snippets within the application's configuration.

01  <?xml version="1.0" encoding="UTF-8"?>
02  <APPLICATION Parent="defaultgwc">
03    <EXECUTION>
04      <PATH>/home/srcdir/app1</PATH>
05      <MODULE>app1</MODULE>
06    </EXECUTION>
07    <OUTPUT>
08      <MAP Id="DUA_AJAX">
09        <THEME>
10          <SNIPPET Id="Image">/home/srcdir/app1/Snippets/Set1_Image.xhtml</SNIPPET>
11        </THEME>
12      </MAP>
13      <MAP Id="DUA_PDA>
14        <THEME>
15          <SNIPPET Id="Image">/home/srcdir/app1/Snippets/Set3_Image.xhtml</SNIPPET>
16        </THEME>
17      </MAP>
18    </OUTPUT>
19  </APPLICATION>

Specify a customized snippet across all applications

If you want to have your customized snippet apply across all of your applications, then you want it to be part of the defined sets for the various application themes (AJAX, PAGE, PDA).

You have three options:

Option 1: You can alter how the snippet is defined within each of the relevant WEB_APPLICATION_THEME_COMPONENTS

01   ...
02  <WEB_APPLICATION_THEME_COMPONENT Id="cpn.theme.ajax.gwc">
03       ...
04    <SNIPPET Id="RadioGroup">$(res.path.tpl.ajax)/RadioGroup.xhtml</SNIPPET>
05    <SNIPPET Id="Image">/home/srcdir/app1/Snippets/Set1_Image.xhtml</SNIPPET>
06    <SNIPPET Id="StaticLabel">$(res.path.tpl.ajax)/StaticLabel.xhtml</SNIPPET>
07       ...
08  </WEB_APPLICATION_THEME_COMPONENT>
09   ...
10  <WEB_APPLICATION_THEME_COMPONENT Id="cpn.theme.pda.gwc">
11       ...
12    <SNIPPET Id="RadioGroup">$(res.path.tpl.pda)/RadioGroup.xhtml</SNIPPET>
13    <SNIPPET Id="Image">/home/srcdir/app1/Snippets/Set3_Image.xhtml</SNIPPET>
14    <SNIPPET Id="StaticLabel">$(res.path.tpl.pda)/Label.xhtml</SNIPPET>
15       ...
16  </WEB_APPLICATION_THEME_COMPONENT>
17   ...

Option 2: You can create new WEB_APPLICATION_THEME_COMPONENTS, then modify the auda.xrd to reference these components. To create new WEB_APPLICATION_THEME_COMPONENTS, you would copy and paste the content of the existing components and provide your copies with new names.

01  ...
02  <WEB_APPLICATION_THEME_COMPONENT Id="cpn.theme.ajax.gwc">
03    ...
04    <SNIPPET Id="RadioGroup">$(res.path.tpl.ajax)/RadioGroup.xhtml</SNIPPET>
05    <SNIPPET Id="Image">$(res.path.tpl.ajax)/Image.xhtml</SNIPPET>
06    <SNIPPET Id="StaticLabel">$(res.path.tpl.ajax)/StaticLabel.xhtml</SNIPPET>
07    ...
08  </WEB_APPLICATION_THEME_COMPONENT>

09  <WEB_APPLICATION_THEME_COMPONENT Id="cpn.theme.ajax2.gwc">
10    ...
11    <SNIPPET Id="RadioGroup">$(res.path.tpl.ajax)/RadioGroup.xhtml</SNIPPET>
12    <SNIPPET Id="Image">/home/srcdir/app1/Snippets/Set1_Image.xhtml</SNIPPET>
13    <SNIPPET Id="StaticLabel">$(res.path.tpl.ajax)/StaticLabel.xhtml</SNIPPET>
14    ...
15  </WEB_APPLICATION_THEME_COMPONENT>

16  ...
17  <WEB_APPLICATION_THEME_COMPONENT Id="cpn.theme.pda.gwc">
18    ...
19    <SNIPPET Id="RadioGroup">$(res.path.tpl.pda)/RadioGroup.xhtml</SNIPPET>
20    <SNIPPET Id="Image">$(res.path.tpl.pda)/Image.xhtml</SNIPPET>
21    <SNIPPET Id="StaticLabel">$(res.path.tpl.pda)/Label.xhtml</SNIPPET>
22    ...
23  </WEB_APPLICATION_THEME_COMPONENT>
24  <WEB_APPLICATION_THEME_COMPONENT Id="cpn.theme.pda2.gwc">
25    ...
26    <SNIPPET Id="RadioGroup">$(res.path.tpl.pda)/RadioGroup.xhtml</SNIPPET>
27    <SNIPPET Id="Image">/home/srcdir/app1/Snippets/Set3_Image.xhtml</SNIPPET>
28    <SNIPPET Id="StaticLabel">$(res.path.tpl.pda)/Label.xhtml</SNIPPET>
29    ...
30  </WEB_APPLICATION_THEME_COMPONENT>
31  ...

Option 3: You could replace the image snippet files in the respective template directories. For this solution, you would name your custom snippet file the same name as the snippet file provided during the installation.

If you choose either solution 1 or 2, when you upgrade the GWC you will have to modify the GAS configuration file to re-apply your changes. If you choose solution 3, you will have to replace the relevant snippet files with your custom versions each time you do an upgrade.

Back to the top

Do I have to restart the GAS to see the result of changes in my template or snippet files?

By default, the Genero Application Server daemon (gasd) keeps the template and snippet files in its cache. When developers make changes to a template or snippet file, the change is not recognized until the Genero Application Server daemon is restarted.

To change this default behavior, you can specify the --development flag. This flag is only valid for the Genero Application Server provided with the GWC install package.

For more information on starting the Genero Application Server daemon and the various command options, please refer to the Genero Application Server Manual.

Back to the top