Design - Template Language

/ Design - Template Language / Project / Subproject:
Starter Kit- 6020 - Lot 5
Reference Number / Version:
2005008 / 0.1
Starter Kit- 6020 - Lot 5
Design - Template Language
Version 0.01 (Draft)
05/03/2008
Analysis document
From / IDS, Informer, Delt & Software AG Consortium
For / Publications Office
Object / Analysis Starter Kit Improvements
Contract ref. / 6020 - Lot 5
Analysis id. / O.200500X_BE
Date / 28/01/2005

Document History

Version / Date / Author / Description / Action(*) / Confidentiality / Pages
0.1 / 07/05/2008 / IDS, PSC / Intermediate version / C / High / 31

(*) Action: C= Creation, I=Insert, U=Update, R=Replace, D=Delete

Summary

Commercial proposal for analysis and technical design of two improvements for the Starter Kit.

Table of Contents

1.Introduction

1.1Purpose of this document

1.2Applicable and Reference documents

1.3Contact persons

2.Template Language aspects

2.1Guidelines

2.2Configurable properties

2.3Common object properties

2.4Transformable attributes

2.5Date conditions

3.Template Language – common elements

3.1Dates

3.2Labels

3.3Hyper links

3.4URLs and image sources

3.5Document language

4.Template Language – context

4.1Modification date

4.2Publication date

5.Template Language – header elements

5.1Crumb trail

5.2Tools

5.3Services

5.4Header style

5.5Configuring the header

6.Template Language – footer

7.Template Language – linkgroup elements

7.1Introduction

7.1.1Ordering

7.1.2Pre-filtering

7.1.3Templating objects

7.1.4Prefix and suffix templates

7.1.5Templating objects with scripts

7.1.6Default presentation

7.2Menu (left)

7.2.1Element definition

7.3Simple linkbox

7.3.1Element definition

7.4Complex linkbox

8.Template language – contextual linkbox

8.1Specifying categories

8.2Search templates

8.3Element definition

9.Conditional comments

10.Template Language – CSS and JavaScript

10.1Includes for objects

10.2Includes by location

10.3Organizing includes

11.Template Language – area

11.1Inner area

11.2Referenced area

12.Template Language – documentation

13.Template Language – feeds

13.1Detect feed type

13.2Title and footer

13.3Date formatting

13.4Generated links

13.5Element

14.Template language – scripting

15.Template language optional elements

16.Binding configuration

Table of Figures

Error! No table of figures entries found.

List of Tables

Table 1: Applicable and reference documents

Table 2: Contact persons

1.Introduction

1.1Purpose of this document

This document describes the technical design of the site and page templating module.

1.2Applicable and Reference documents

The following documents are referenced or applicable in the context of this document.

Type(*) / Title / Identification / Version / Date
A / Framework contract 6020 Lot 5 / Framework contract 6020-5 / 1.0 / 13/06/2004

(*): Reference document, Applicable document

Table 1: Applicable and reference documents

1.3Contact persons

Contact persons for obtaining more information about this proposition are:

Name / Function / Phone and/or e-mail address
Frank van der Kleij / Project Leader / +32 2 777 02 90

Table 2: Contact persons

2.Template Language aspects

2.1Guidelines

Some common rules should be followed.

-a notation using lower case only

-words should be separated with underscores

-prefix wcm: is used for template language specific elements and attributes

-Boolean attributes should use the values:

true/false
yes/no

2.2Configurable properties

Some attributes of the WCM language elements will be configurable, meaning that their value is not static but is instead looked up during the transformation.Different approaches are possible.

Approach 1: short notation

Example:

<wcm:linkbox wcm:lg_id=”$lg_id”/>

(Or the following notation without namespace for the wcm attributes; this is perhaps a cleaner notation.)

<wcm:linkbox lg_id=”$lg_id”/>

Advantage: very condensed, clear notation, all WCM properties are configurable

Disadvantage: default values can’t be declared in the XML

Approach 2: long notation

Example:

<wcm:linkbox>

<wcm:lg_id wcm:value=”$lg_id” wcm:default=”12345”/>

</wcm:linkbox>

Disadvantage: long, cumbersome notation; perhaps less clear for the user; only properties formatted this way can be configurable

Advantage: the separate element can be used to declare a default value (or other meta information like a description)

Approach 3: combination

Of course a combination is always possible. If the user wants to declare a default value, he should use the second approach. Properties formatted as attribute (approach 1) overwrite properties formatted as child elements (approach 2).

Advantage: more flexible

Disadvantage: very complex both for user and engine

Preferred approach:

Approach 1 (short notation with wcm:-less attributes); if default values are needed they can be declared as follows.

<wcm:linkbox lg_id=”$lg_id?1234”/>

After the ?-character a default value can be specified.

2.3Common object properties

By objects we mean complex structures like link groups and menus.

Such objects will have a common set of properties.

Attribute style:

The style attribute determines how the engine should generate the element, i.e. using tables instead of ULs.

Attribute id:

All generated elements will have a root element (i.e. a DIV) with a unique ID specified by this attribute. For the template language this attribute will always be optional. If nothing is provided, an id will automatically be generated.

Inner element wcm:str:

This element will define which link strategy should be applied the A-tags of the generated element.

Attribute active:

Boolean indicating if the element should be generated.

2.4Transformable attributes

Some attribute values should be transformed. A common notation scheme should be followed.

A space separated list should always be used.

An action will be applied to the values of the attributes.

The attributes will be recreated containing the result of the action.

If an action fails the original value should be maintained.

The wcm:action attribute must be removed after the processing.

2.5Date conditions

Sometimes it will be needed to specify a date condition in the template language; i.e. when searching all events starting in a specific time frame.

In all these cases the time values should be used. This form of notation is currently used in some cases but should become the default for the template language.

However time values are not sufficient for the template engine. Since a declarative approach is used users can not “calculate” a date to be passed as parameter. For example if a search should be performed for documents with a creation date older than 3 months.

With the template engine users should be able to specify a date expression which must first be calculated before it can be used.

The date values will be extended with a simple expression language to calculate dynamic dates. Expressions should be noted between [].

A few examples:

[now-10d]-[now+10d]

Date value matching any date after today minus 10 days and before today plus 10 days.

[now-1m]-

Date value matching any date not older than 1 month from today.

For a first implementation we will only support adding or subtracting days and/or months to the current date.

Examples:

[now-nmnd]

[now+nmnd]

[now-nd]

[now+nd]

[now-nm]

[now+nm]

TODO:

-find a standard Java library and/or standardized XML notation for date expressions

-extend fdate element with support for expressions (of course only simple expressions)

3.Template Language – common elements

This chapter describes some common elements of the template language.

3.1Dates

The following is used to transform a date to a specific format.

Element: fdate
Attributes / Description / Optional
text / The date string to format. / x
in / The pattern of the date string as provided in the text attribute. / x
out / The pattern to transform to.

Java date format patterns are used.

If no input pattern is provided the engine should try to guess the format or use a default.

Example:

<wcm:fdate text=”01/05/08” in=”MM/dd/yy” out=”dd/MM/yyyy”/>

If the text is omitted the current date will be formatted and outputted.

3.2Labels

A special element must exist to indicate that a label should be translated. The following element will be used.

The following is used to output the current date.

Element: translate
Attributes / Description / Optional
label / The identifier/name of the label.
lang / Indicates for which language the label should be translated. In almost all cases the language of the processed document will be used therefore this attribute will be optional.
Default value: 2 letter language code the processed document
Possible values: en, nl, fr… / X
parse / Indicates if the translation value should be treated as XML.
Default: if a XHTML fragment is detected, yes. Developers have to specify NO if the fragment should not be treated as XML. / X

Example:

<wcm:translate label=”header_title” lang=”nl” asXml=”no” />

<wcm:translate label=”header_title” />

The XHTML contained in a parsed label can contain links. However these links will NOT be processed as by the hyper link functionality.

Sometimes attribute contain labels that need to be translated.An attribute wcm:translate can be used to indicate which attributes contains labels that should be translated. An example:

The result will be.

To be able to specify a language for a translation a separate attribute wcm:lang will be used.

The wcm:lang attribute specifies the language for every label to translate.

3.3Hyper links

Hyperlinks can occur in the content XML and the layout template XML.

Content XML:

-links will always be formatted as a normal A-tag

-href attribute always contain a path

-impossible to pass link strategy options directly in the XML notation

-currently all the links are processed using the same link strategy

Layout template XML:

-links can be inserted directly in the layout template XML

-links can come from an object (i.e. menu or link group)

-an alternative notation (i.e. wcm:a) is possible

The problem is finding a consistent notation applicable for all situations and that allows passing parameters to the link processing algorithm.

Solutions:

Use a specific WCM notation (see below)

<wcm:a href=”/psc/dummy/index_en.xml” strategy=”check” cnticons=”yes” target=”_blank”>

[content of the A-tag]

</wcm:a>

For the content,all A-tags are first converted to that notation. For the content links a default link strategy is used which should be configurable.

Disadvantages: additional transformation step is needed

Use 2 different processing and notation schemes; there are 2 different pipelines anyway; the same extension function will also be used.

Disadvantages: 2 different notations is confusing

Another solution is to simply use the A-tag notation as basis with optional wcm:* attributes. In other words A-tags will always be processed by the template engine. For example:

[content of the A-tag]

</a>

The A-tags in the content should always be considered “to process” and should all be processed the same way. A default strategy should always be applied. This strategy should however be configurable. Different approaches are possible:

configuration made on the subsite containing the document
configuration made in the template configuration objects with a reserved key
configuration made in the layout template

For links pointing to document ids a notation like the one below can be used.

[content of the A-tag]

</a>

The element:

Element: a
The wcm:a element can contain any other elements (XHTML or WCM). They will be processed like any other element therefore it is not needed to provide parameters to specify the content of the generated A-tag.
Attributes / Description / Optional
href / An ID or URL identifying the target to link to.
The Java code should detect which one is given.
wcm:strategy / The link strategy to use. / x
wcm:cnticons / Boolean specifying if the special content icons (file size and type) should be generated. / x
any other attribute will be copied, i.e. target, id… / x

Note: Optionally provide an attribute to specific the link type (ID or URL).

Disadvantages: a notation mixing wcm:* and XHTML is used for a WCM language feature

Preferred solution: solution C

3.4URLs and image sources

In the current approach it happens that links must be processed without generating the HTML of hyper links (= language icons…); i.e. for images or for “hand made” links in the layout.

In these cases a template is called createUrlForLanguage like showed in the example below.

<a>

<xsl:attribute name=”href”>

<xsl:call-template name=”createUrlForLanguage”>

<xsl:with-param name=”url” select=”/home/europa-info/index_en.xml” />

</xsl:call-template>

</xsl:attribute>

</a>

<img>

<xsl:attribute name=”src”>

<xsl:call-template name=”createUrlForLanguage”>

<xsl:with-param name=”url” select=”/home/images/logo_en.jpg” />

</xsl:call-template>

</xsl:attribute>

</img>

To support these cases the FTS suggested using transformable attributes where the action is to resolve an URL (see example below).

However other solutions are possible:

Hyperlink notation

A notation similar to the hyperlinks can be used.

This would mean that we have a single notation for all URL, link and image resolving. A specific phase in the pipeline will be to process ALL the A and IMG tags and resolve the URLs/IDs if needed following the provided link strategy.

Advantage: Single notation for links.

Disadvantage: Not all the strategies can be applied to the SRC of an image. For example a web service strategy is not applicable to images.

3.5Document language

Sometimes it is needed to output the language of the document as an attribute “lang”. The template language will provide an attribute lang to that purpose.

If the attribute is empty, the template engine will generate an attribute lang containing the 2 letter language code of the document.

4.Template Language – context

This chapter lists some elements that show some information about the subject (= the document being regenerated).

4.1Modification date

An element to show the modification date:

<wcm:modification_date out=”dd/MM/yyyy” />

4.2Publication date

An element to show the publication date:

<wcm:publication_date out=”dd/MM/yyyy” />

5.Template Language – header elements

This chapter describes the elements of the template language that will be used to construct the header.

Currently the header is often constructed using one main template (i.e. “header”). It controls the creation of all the template components like the language selector, the banner etc.

With the template engine a different approach will be followed. The header will probably be declared directly in the layout template or in a reusable fragment.The declaration will be a XHTML structure with references to other header components like the language selector or the crumbtrail (see example below).

<wcm:language_selector />

</div>

Therefore it is needed that, contrary to the current approach, the different header components are independent from each other. Therefore specific language elements will be defined for each of them. The following paragraphs describe these elements.

5.1Crumbtrail

Currently the crumbtrail is part of the create header template(s). In the templating the crumbtrail will have to be a self-contained element.

Currently to control the length of the crumbtrail 2 parameters can be passed:

the maximal depth: to limit the number of retrieved levels
the maximal length: to limit the physical (= textual) size of the crumbtrail

However the maximal length of the crumbtrail could be controlled completely in CSS and JavaScript (to be checked with Christophe). Removing this parameter would make the crumbtrail considerably easier.

Normally the crumbtrail is a default element that should always have the same representation style. An optimal HTML structure will have to be defined.

However a simple HTML notation using tables should also be supported.

Element: wcm:crumb_trail
Attributes / Description / Optional
Id / Id for the root element.
style / X
validate / Boolean indicating if the referenced index file should be validated.
Default: yes / X
max_depth / The maximal depth of the path.
Default: -1 (no limit) / X
max_length / The maximal length of the crumb trail in characters.
Default: 100
This property will probably disappear. / X
separator / The separator character to use between nodes.

Could we add a baseName attribute indicating which documents should be lookup up to construct the crumbtrail? Is there an added value? Or a fallback name?

5.2Tools

The tools component only adds 2 links to the header:

contact link
search link

The tools are currently not used in the newly defined default header. Perhaps in a first implementation we can drop this element. If needed, the tools can be added manually in the XHTML fragment of the header.

5.3Services

The services are a list of standard IPG links that can be added to the header (or the footer). The following are the IPG standard services:

LEGAL_NOTICE_LINK
TEXT_VERSION_LINK
PRINT_USER_FRIENDLY
JOBS_LINK
WHATS_NEW_LINK
KEY_ISSUES_LINK
SITE_MAP_LINK
INDEX_LINK
GLOSSARY_LINK
INFORMATION_LINK
SURVEYS_LINK
ABOUT_EUROPA_LINK
ABOUT_THIS_SITE_LINK
FAQ_LINK
FORUM_LINK
LINKS_LINK
HELP_LINK
SEARCH_LINK
CONTACT_LINK
SUBSCRIBE_LINK

They should be displayed in the given order.

The following table describes the wcm:services element.

Element: wcm:services
This element triggers the generation of the default IPG services (used in the header). To declare custom services users can use the wcm:custom element.
Attributes / Description / Optional
id / Id for the root element. / X

Standard services have a specific name and an URL (reference). Optionally users can declare a custom label for them. To declare standard services the following element will be used.

Element: wcm:standard
Attributes / Description / Optional
label / The name of label to translate. / X
ref / The target; i.e. the URL of the service.
name / The name of label to translate.

To declare custom services the following element will be used.

Element: wcm:custom
Attributes / Description / Optional
label / The name of label to translate.
ref / The target; i.e. the URL of the service.

An example:

<wcm:services id=”services”

<wcm:standard name=”legal_notice” ref=”/home/legel_notice.htm” />