t5gui templates

  • thin client, all browsers, no need for ActiveX objects of client side java, only javascript
  • easy/efficient keyboard navigation
  • powerful automatic cross linking of records
  • fields can be distributed over (tab) pages with some fields be visible on all tabs
  • fields can be grouped
  • setting links using suggest values (*)
  • generated components can be used to build custom pages
  • highly customizable, layout components define how things are combined on screen
  • possible to change the components used for a specific type or field or on a case by case basis

Usage

To make sure the generated site works properly, you need to include the following dependencies.


<dependency>
<groupId>org.equanda</groupId>
<artifactId>equanda-tapestry5</artifactId>
<version>${tapestry-version}</version>
</dependency>
<dependency>
<groupId>org.equanda</groupId>
<artifactId>equanda-t5gui</artifactId>
<version>${tapestry-version}</version>
</dependency>
<dependency>
<groupId>org.chenillekit</groupId>
<artifactId>chenillekit-tapestry</artifactId>
<version>1.0.0</version>
</dependency>

and following repositories


<repositories>
<repository>
<id>progs</id>
<url>http://maven.progs.be/m2repo</url>
</repository>
<repository>
<id>chenillekit</id>
<url>http://www.chenillekit.org/mvnrepo/release</url>
</repository>
</repositories>

As some of the t5gui classes are used for equanda rights handling, the Login package is required to build these pages. See the login template in the equanda-generate module for more information.

Generated components

For each (root) table the following components are generated.

  • Edit : allows editing and or showing an entire record, considering the configured authorization for the user. Two important parameters are "editMode" and "canSwitch". They both accept boolean values and indicate whether the component starts in edit or display mode and whether the user can switch between the two. There is also a "showMetadata" parameter which allows you to disable the display of the metadata tab.
  • InlineLinkList : allows inline editing of the multiple records. The "canAdd" parameter allows you to determine whether adding records is allowed.
  • InlineLinkOne : allows inline editing of the one record.
  • LinkList : ...
  • LinkOne : ...
  • Select : allows to select one or more records to be assigned to edited record.
  • Summary : Short summary of a record. Displays the fields which have been configured for summary display.
  • SummaryEditLink : A summary on which you can click to edit/view the record.

Also one universal component are generated.

  • InlinePrimitiveList : allows inline editing of the multiple string, date and timestamp fields.

Generated pages

For each (root) table the following pages are generated.

  • Edit : allows editing of a record, considering the configured authorization for the user.

For each action on each table.

  • Action : pass the parameters to the action.
  • ActionRes : display the action result.

For each select defined on a table.

  • Select : allow applying the select, you can enter the parameters and see the results.

renderer support

In the domain model, it is possible to overwrite the rendering of specific fields or groups using the "renderer" parameter on the definition.

There are two renderers which are provided by default which can be used :

  • text : to assure a string can be input in a text box
  • url : allows the user to link to the resource when in view mode
  • email : allows the user to click on the e-mail address to send an e-mail (when in view mode)

TODO : documentation to be completed

configuring how forms are generated

The generation of forms is multi-layered to allow configuration of how specific elements will be generated. This makes the user interface highly customizeable, it assures consistency and assures the user interface can be updated based on the domain model.
At field or group level, the rendering can be overwritten using the "renderer" parameter in the domain model. However, some generic changes can also be handled as generation parameters.

In the configuration file "dm.ini" you can define which files should be read to get the properties.


[t5gui]
keyvalue1=t5gui/templates.properties
keyvalue2=t5gui/mytemplates/templates.properties

The first file included above is always included and contains the default mappings. You can include as many keyvalueX keys as needed, but there should be no gaps in the numbering.
The references properties files are searched on the classpath. As an example the default (t5gui/templates.properties) is included below.
When several mappings exist for the same key, the last one is applied.
Note that any templates mentioned in the properties file should be in a path starting with "t5gui", and this should not be included in the file name (this is to allow several template sets to coexist easily).


pages=edit-tml/pages.tml.vm
page=edit-tml/page.tml.vm
group=edit-tml/group.tml.vm
field=edit-tml/field.tml.vm
fieldData=edit-tml/fieldData.tml.vm

edit.type.string=edit-tml/string.tml.vm
edit.type.clob=edit-tml/text.tml.vm
edit.type.double=edit-tml/double.tml.vm
edit.type.int=edit-tml/int.tml.vm
edit.type.date=edit-tml/date.tml.vm
edit.type.timestamp=edit-tml/timestamp.tml.vm
edit.type.boolean=edit-tml/boolean.tml.vm
edit.type.link.one=edit-tml/linkone.tml.vm
edit.type.link.list=edit-tml/linklist.tml.vm
edit.type.choice=edit-tml/choice.tml.vm

edit.field.EquandaUser.Password=edit-tml/password.tml.vm
edit.field.EquandaType=edit-tml/type.tml.vm

edit.renderer.text=edit-tml/text.tml.vm
edit.renderer.wiki=edit-tml/text.tml.vm
edit.renderer.url=edit-tml/string.tml.vm
edit.renderer.email=edit-tml/string.tml.vm

view.type.string=view-tml/string.tml.vm
view.type.clob=view-tml/text.tml.vm
view.type.double=view-tml/tostring.tml.vm
view.type.int=view-tml/tostring.tml.vm
view.type.date=view-tml/date.tml.vm
view.type.timestamp=view-tml/timestamp.tml.vm
view.type.boolean=view-tml/tostring.tml.vm
view.type.link.one=view-tml/linkone.tml.vm
view.type.link.list=view-tml/linklist.tml.vm
view.type.choice=view-tml/choice.tml.vm

view.field.EquandaUser.Password=view-tml/password.tml.vm
view.field.EquandaType=view-tml/type.tml.vm

view.renderer.text=view-tml/text.tml.vm
view.renderer.wiki=view-tml/text.tml.vm
view.renderer.url=view-tml/url.tml.vm
view.renderer.email=view-tml/email.tml.vm

list.type.string=list-tml/string.tml.vm
list.type.clob=list-tml/string.tml.vm
list.type.double=list-tml/tostring.tml.vm
list.type.int=list-tml/tostring.tml.vm
list.type.date=list-tml/date.tml.vm
list.type.timestamp=list-tml/timestamp.tml.vm
list.type.boolean=list-tml/boolean.tml.vm
list.type.link.one=list-tml/linkone.tml.vm
list.type.link.list=list-tml/linklist.tml.vm
list.type.choice=list-tml/choice.tml.vm

list.field.EquandaUser.Password=list-tml/password.tml.vm
list.field.EquandaType=list-tml/type.tml.vm

list.renderer.text=list-tml/string.tml.vm
list.renderer.wiki=list-tml/string.tml.vm
list.renderer.url=list-tml/string.tml.vm
list.renderer.email=list-tml/string.tml.vm

summary.type.string=list-tml/string.tml.vm
summary.type.clob=list-tml/text.tml.vm
summary.type.double=list-tml/tostring.tml.vm
summary.type.int=list-tml/tostring.tml.vm
summary.type.date=list-tml/date.tml.vm
summary.type.timestamp=list-tml/timestamp.tml.vm
summary.type.boolean=list-tml/tostring.tml.vm
summary.type.link.one=summary-tml/linkone.tml.vm
summary.type.link.list=summary-tml/linklist.tml.vm
summary.type.choice=list-tml/choice.tml.vm

summary.field.EquandaUser.Password=list-tml/password.tml.vm
summary.field.EquandaType=list-tml/type.tml.vm

summary.renderer.text=list-tml/string.tml.vm
summary.renderer.wiki=list-tml/string.tml.vm
summary.renderer.url=list-tml/string.tml.vm
summary.renderer.email=list-tml/string.tml.vm

java.pages=edit-tml/pages.java.vm
java.page=edit-tml/page.java.vm
java.group=edit-tml/group.java.vm
java.field=edit-tml/field.java.vm

You can define the templates (and thus tapestry objects) which are used for the display based on the structure.

  • pages : defines how the sequence of pages are handled, implemented using the Tabs component which creates tab pages. There is some special handling for the "ALL" and "metadata" pages.
  • page : handle the contents of one page, rendering the fields (which are not part of a group) and groups.
  • group : handling of a group, put the contents in a fieldset.
  • field : default rendering of individual fields.

The default field handling uses the keyvalue settings again to read the velocity templates used to build the .tml tapestry template.
Below are the possible configurations which are used, in order. Of course only the types which are possible according to the field type apply.
The names are aways prefixed by an indication of the usage. This can be either "edit." "view." or "list.".
When a renderer is specified, the name is prefixed by "edit.renderer." "view.renderer." or "list.renderer." to find the templates to be used.

  • type.TableName.FieldName : specific templates for a field in a table.
  • type.FieldName : specific tamplates for fields of that name in all tables.
  • type.link.TableName.one, type.link.TableName.list : templates to use for instances links to the table of the name as included in the key.
  • type.link.one, type.link.list : generic handling for link fields.
  • type.string, type.boolean, type.date, type.timestamp, type.int, type.double, type.blob, type.clob : templates for generic handling of fields of a certain type.
  • group.TableName.FieldName : specific templates for handling an entire group of fields. This can for example be used for dynamic selection of fields which needs to be visible.

For the display and edit components (shared between the two), there are two more overwrite possibilities.

  • pages.TableName : allow overwriting the generation of all pages (allow changing the use of the MemTabs component for a specific page).
  • page.TableName.PageName : allow overwriting a specific page in a table. When combined with the default pages template, content should be inside a "t:parameter" for the parent component (by default MemTabs)

The generated "Edit" components also allows custom java code to be injectd. For this the temapltes with keys starting with "java." are used. The default templates don't need any specific additions, so there is no code for these. However, all is in place for additions in custom templates.

Important
When customizing the templates which are used, you have to do a clean build ("mvn clean install") in your project to assure the modified templates are applied. As the templates are read from the classpath, the system is unable to know the timestamp for the templates and thus does not know when to overwrite the generated files if the domain model has not changed.

When you used the archetype to create your empty project, the t5compo module is intended to write your custom components and templates which are used during generation. It also contains a templates.properties file for you to extend.

Useful standard templates

For generating links, the default rendering is to have a compact display of the record, and all operations are done on different pages. There is also an option to have links being displayed inline. For this add lines like the following in your templates.properties file :


type.link.Address.list=edit-tml/inlinelinklist.tml.vm
type.link.Score.list=edit-tml/inlinelinklist.tml.vm

In this example, all links to the Address or Score table will be rendered inline.

Configuring security

You can add an annotation on each generated page by including the following in your "dm.ini" file.
This could also be used for other purposes, but in this example it adds a login restriction using chenillekit-access.


[t5gui]
page-class-annotation=@org.chenillekit.access.annotations.Restricted( role = 1 )

Configuring the generated interface

The generated interface uses a few symbols which allow application wide configuration.


public static void contributeApplicationDefaults( MappedConfiguration<String, String> configuration )
{
configuration.add( "equanda.edit.truncate.length", "30" );
configuration.add( "equanda.select.truncate.length", "250" );
configuration.add( "equanda.select.rows.per.page", "25" );
}
  • equanda.edit.truncate.length : length to which string fields in the edit component are truncated
  • equanda.select.truncate.length : length to which string fields in the edit component are truncated
  • equanda.select.rows.per.page : max number of rows which are dispmlayed on one page in the select component
  • 1. t5gui templates
  • 1.1. Usage
  • 1.2. Generated components
  • 1.3. Generated pages
  • 1.4. renderer support
  • 1.5. configuring how forms are generated
  • 1.5.1. Useful standard templates
  • 1.6. Configuring security
  • 1.6.1. Configuring the generated interface