eTemplate-Referenz - Templates and Dialog-Editor for phpGroupware

by Ralf Becker RalfBecker@outdoor-training.de

A referenz documentation about the new eTemplates and the syntax and parameters of the several widgets.


Introduction - The concept of the eTemplates

As I already covered this in the Tutorial, I like would suggest to have a look there if your are not familiar with the overal concept.

There are two possibilities now to create an eTemplate:

  1. Use the eTemplate-Editor (as descript in the Tutorial) to interactivly design your template.
  2. Write a xml-file in a Syntax similar to XUL (the mozilla UI-interface definition language) and import it into the database with the eTemplate-Editor

The xml-interface to the eTemplates

The eTemplates-Editor can import and export now eTemplates as xml-files. Here is short example showing an eTemplate from the example app in the Tutorial (here are screenshots of the template in the editor and the show-function):

<?xml version="1.0"?>
<!-- $Id$ -->
<overlay>
  <grid id="et_media.edit" template="" lang="" group="" version="" width="100%">
    <columns>
      <column/>
      <column/>
      <column/>
      <column/>
    </columns>
    <rows>
      <row>
        <description options="ib" span="all" value="eTemplates MediaDB" no_lang="1" id="msg"/>
      </row>
      <row>
        <hrule span="all"/>
      </row>
      <row>
        <description span="all"/>
      </row>
      <row>
        <description value="Name"/>
        <textbox size="100" maxlength="100" span="all" id="name" statustext="here goes the name of the publication / record"/>
      </row>
      <row>
        <description value="Author"/>
        <textbox size="100" maxlength="100" span="all" id="author" statustext="please use Name, First Name"/>
      </row>
      <row>
        <description value="Type"/>
        <menulist span="all" statustext="select the type fitting most">
          <menupopup id="type"/>
        </menulist>
      </row>
      <row>
        <description value="Description"/>
        <textbox ="" cols="3" rows="100" span="all" id="descr" statustext="we have a fulltext search using that description"/>
      </row>
      <row>
        <description span="all"/>
      </row>
      <row>
        <button label="Read" id="read" statustext="reads or searches for entries matching the criteria above"/>
        <button label="Save" id="save" statustext="saves the change to the db"/>
        <button label="Cancel" id="cancel" statustext="clears the form, without changing anything"/>
        <button label="Delete" id="delete" statustext="deletes an entry"/>
      </row>
    </rows>
  </grid>
</overlay>

The tags / widget-names and attributes / parameters used are as close as possible to XUL. For more information about XUL refer to www.xulplanet.com or the Mozilla docs www.mozilla.org/xpfe/xulref/.

Please keep in mind that the xml-files used to store the eTemplates are only similar to XUL and implement only a subset of XUL. Here are the main differences:

Like XUL the eTemplate-xml-files are quite strict with the xml-syntax:


Syntax and Parameter Referenz

Standard parametes / attributes for all widgets

Name in Editor xml attr xul internal name description of the attribut
Type type
(only for
sub-types)
no type The type of the widget is stored in the tag itself, some widgets have sub-types (unknow to XUL). In that case the subtype is stored in the type attribut.
The Type / tag has to be either the name of a standard eTemplate-widget or of an already existing extension.
Name id yes name A string to locate the content for the widget in the content array (index) to show the dialog and for the returned content. Can be left blank or be obmitted as xml-attribut if the widget needs no content.

The name can contain the following variables, which gets expanded before they are used as array index (for an example see the Tutorial):

$c the column-number (starting with 0, if you have a header, data-cells start at 1)
$col the column-letter: 'A', 'B', 'C', ...
$row the row-number (starting with 0, if you have a header, data-cells start at 1)
$cont the content-array the (sub-)template, on auto-repeated row's this could eg. be used to generate button-names with id-values in it: "del[$cont[id]]" expands to "del[123]", if $cont = array('id' => 123)
$row_cont the sub-array indexed by $row of the content-array, on auto-repeated row's this could eg. be used to generate button-names with id-values in it: "del[$row_cont[id]]" expands to "del[123]", if $cont = array('1' => array('id' => 123),'2' => array('id' => 456)) and $row = 1
$c_
$col_
$row_
are the respective values of the previous template-inclusion, eg. the column-headers in the eTemplate-editor are templates itself, to show the column-name in the header you can not use $col as it will be constant as it is always the same col in the header-template, what you want is the value of the previous template-inclusion.
Label label no label Displayed in front of each widget (if not empty) or the widget is replacing a '%s' in the label itself. Eg. '%s Name' to have the label Name behind a checkbox. The label can contain variables, as descript for name. If the label starts with a '@' it is replaced by the value of the content-array at this index (with the '@'-removed and after expanding the variables).
Help statustext yes help This text / help-message is displayed in the status-bar of the browser when the widget gets focus (or as tooltip for buttons or general in gtk). If the user has JavaScript switched off, the help-texts get NOT submitted, as this is detected. If the helptext starts with a '@' it is replaced by the value of the content-array at this index (with the '@'-removed).
Options ? ? size This attribute controls certain aspects of the different widgets. It's meaning and xml / xul-values are document with the widgets.
NoTranslation no_lang no no_lang If checked the content of the widget and the label gets NOT translated.
The helptext of a widget is always translated.
needed needed no needed If checked (xml-attr: needed="1") the etemplates will reprompt the user if he left the widget / field empty.
This is not yet implemented, but should be filled if applicable.
Readonly readonly yes readonly If checked (xml-attr: readonly="true") the widget will NOT be editable. If it is not supported by the browser, the etemplate-class makes shure that no changes / content is transmitted back to the app. Only applicable to widgets with input capabilities. Readonly Buttons get removed from the dialog, like they where disabled. The readonly attribute could be set on runtime via a readonly-array sublied to the exec or show function of the class, the value on index=name/id has to be true to make a widget readonly.
Disabled disabled yes disabled If checked (xml-attr: disabled="true") the widget will NOT be shown. For buttons this could be archived on runtime via setting them readonly.
onChange onchange ? onchange If checked (xml-attr: onchange="1") and the contet of the widget is changed by the user, the form will be submitted. Via xml or by a program other values can be set (not in the editor at the moment and this is not compatible with the phpGTK implementation of the eTemplates).
Span, Class span
class
span: no
class: yes
span In the editor and internaly this field contains two comma-separated values:

span: how many cell a widget should span (default is one), the special value of 'all' can be used to indicate it should span all remaining cells of a row. This is not supported by xul-grid's at the moment, but is planned to be.

class: the CSS class for the widget.

Align align yes align Can be set to 'left' (default), 'center' or 'right'.
Width, Disabled
column-attr.
width yes row[0][#] Can be set to a percentage (eg. '10%'), a number of pixels or ...
Height, Disabled
row-attr.
height yes row[0][h#] Can be set to a percentage (eg. '10%'), a number of pixels or ...
Disabled
column-attr.
row-attr.
disabled no   Syntax: [!]{@name|value}[={@name2|value2}]
Disables (=dont show it) a row/column if a certain criteria is (not (=!)) meet.
If no '=...' / 2. value is given, the test is made on the first value being not empty, else the test is made by comparing the two values. Instead of a value you can give a name as an index into the content prefixed by @. Examples:
!@data disables row/col if value of data is empty,
@val=false disables if value of val is equal to (the string) 'false'
Class, Valign
row-attr.
class
valign
both: yes row[0][c#] In the editor and internaly this field contains two comma-separated values:

class: the CSS class for the row, there are 4 predefined css-classes: nmh: next-match-header-background, nmr: alternating next-match-row-background which gets replaced by the etemplate class with nmr0 or nmr1.

valign: vertical alignment of the widgets in the row: 'top', 'middle' (default) or 'bottom'

standard widgets and extensions of the eTemplates

Widget Name in Editor xml tag xul internal name description of the widget
Label <description/> yes label a textual label
The content is taken from the content-array but it can have an own label from the label attribute too.

Options: if it contains a 'i' and/or a 'b' the content (not the label) is rendered in italic and/or bold.

Text <textbox/> yes text a single-line input field for text
In the html-UI this is rendered as <input ...>

Options has 2 comma-separated fields:
xml: size: the length in chars of the input-field
xml: maxlength: the maximum length of the input

Integer <textbox
type="int"/>
? int a input-field to enter an integer
In the html-UI this is rendered as <input ...>. There are no checks implemented at the moment, but the will come in the near future.

Options has 3 comma-separated fields:
xml: min: minimum value, default none
xml: max: maximum value, default none
xml: size: the length in chars of the input-field, default 5

Float <textbox
type="float"/>
? float a input-field to enter a float
In the html-UI this is rendered as <input ...>. There are no checks implemented at the moment, but the will come in the near future.

Options has 3 comma-separated fields:
xml: min: minimum value, default none
xml: max: maximum value, default none
xml: size: the length in chars of the input-field, default 5

Textarea <textbox
multiline="true"/>
yes textarea a multiline input-field for text
In the html-UI this is rendered as <textarea ...>.

Options has 2 comma-separated fields:
xml: cols: the width of the field in chars
xml: rows: the number of rows

Checkbox <checkbox/> yes checkbox a widget that can be checked or unchecked
In the html-UI this is rendered as <input type="checkbox" ...>.
Radiobutton <radio/> ? radio a widget in a group of which only one can be checked
In the html-UI this is rendered as <input type="radio" ...>
Unlike XUL (and like html) the radio-buttons are grouped by giving them the same name / id. If it is checked, the value is set to what is entered in Options. If the value of the content array at index name/id matches the options-field the radiobutton is marked 'checked'.
Submitbutton <button image="img.gif" ro_image="img-grey.gif"/> yes button a button to submit the form / end the dialog
In the html-UI this is rendered as <input type="submit" ...>.
If a button is set readonly (via seting its id in the $readonlys array passed to exec) it is not rendered at all (if no ro_image is given), like it would be diabled.

onChange xml: onchange: if set and the user has JavaScript enabled the button is renderd as a link around the label and a hidden input to set id if the link is clicked.
Options xml: image, ro_image: Image to use instead of a Button with a label. There will be no button around the image. If a ro_image is given (separated by a comma in the editors options) it will be used if the button is set readonly (else the button is no rendered at all) .

Horizonatal Rule <hrule/> no hrule a horizontal rule / line
In the html-UI this is rendered as <hr ...>
Options can contain a width of the rule, default is 100%
Template <grid id="app.name" content="subarr"/> yes template a separate eTemplate to be loaded into this cell
Name xml: id: the name of the etemplate to load
Options xml: content: if set, the template uses an own sub-array of the content array indexed by the value of this field (if not the full content-array is used). Variables like $row can be used as descript for the general attribute Name.
Image <image src="foo.gif" label="Get a foo" options="app.class.method"/> yes image shows an image
Label xml: label: the label is shown as tooltip (like html-title)
Name xml: src: the name of the image to load, the image is search in the apps template-dirs
Options xml: options: if set, a link to that methode = app.class.method is put around the image
Selectbox <menulist>
  <menupopup id="name" options="Select one"/>
</menulist>

multiselect: options > 1
<listbox rows="#"/>

Examples for predefined selectboxes:

<listbox type="select-cat" rows="5"/>

<menulist>
  <menupopup type="select-account" options="All,both,2"/>
</menulist>

yes select shows a selectbox
The content of the selectbox / the options have to be in an array which can be in 2 locations:
  1. in $content["options-$name"]
  2. or in an separate array only for select-box-options under the index name, this array is passed to the exec or show function of the etemplate-class
Options in the editor: if set and > 1 the selectbox is a multiselection with options number of lines

xml: rows: only for <listbox>: number of rows to show

xml options: only for <menupopup/>: textual label for a first Row, e.g. 'All' or 'None' (id will be ''), additional attr see sub-types

xml: type: can be set to get several predefined select-contents, in that case you dont need to set the content as descripted above (if set it too its in front of the predefined rows):
select-cat: Select a phpgw category
select-account: Select a user and/or group, determined by the options-field: ,{accounts(default)|groups|both},{0(only lid)|1(only names/default)|2(both)}
select-percent, select-priority, select-access, select-country, select-state: as you expect by the name
select-year, select-month, select-day: options for year: ,start,end (start and end can be a number of years from now or if > 100 a absolut year)

FileUpload <file id="name"/>
no file Input and Button to select a file for uploading
Returns the file-name of the uploaded file in the servers tmp-dir (the webserver needs to have a writable tmp-dir) plus, if javascript is enabled, the local filename of the client as "${name}_path".
Date <date options="Y-m-d,1"/>
no date Dateinput via selectboxes or a field for the year
The order of the input-fields is determined by the prefs of the user.
Options: [date-storage-format][,year-no-selectbox]
date-storage-format is the format, in which the date is stored in the variable: empty means an unix-timestamp, or a string containing the letters Y, m and d plus separators, eg. 'Y-m-d': 2002-12-31.
year-no-selectbox if true an int-widget (input-field) is used instead of a select-year widget.
If readonly is set, this widget can be used to display a date, without the need to convert it.
VBox, HBox <vbox>
  <widget ...>
  <widget ...>
</vbox>

<hbox span="all">
  <widget ...>
  <widget ...>
</hbox>

yes vbox, hbox vertical or horizontal container to contain other widgets. This is useful if one needs more widgets or widgets outside the column- / row-order of a grid.
Disabled child-cells are completly left out (no empty cells or rows get generated).

Options in the editor: the number of cells in the box (does NOT need to be set in xml).

Tabs <tabbox id="name">
  <tabs>
    <tab label="Tab 1" statustext="Help"/>
    ...
  </tabs>
  <tabpanels>
    <grid id="app.name.tab1"/>
    ...
  </tabpanels>
</tabbox>
yes tab shows a tab-widget
The tab-widget is implemented as an extension, as html does not have a tab-widget.

The following fields / attributes are in the Editor and internaly in the class separeted by '|', in the xml/xul-file the are attributes of each tab- or grid-tag:
Label xml: label: the labels of the tabs eg. 'Tab 1|Tab 2|Tab 3'
Help xml: statustext: of the tabs
Name xml: id: the names/ids of the eTemplates/grid's to fill the bodies of the tabs, if the name contains no '.', it will be prefixed with the name of the template the widget is in plus a '.'

Demo: There is a demo availible: load 'etemplate.tab_widget.test' into the eTemplate editor and run it with show.

NextMatch <nextmatch options="notes.index.rows" id="nm"/> yes tab shows a table with some selectboxes, a search-field and arrows to scroll the table
The nextmatch-widget is implemented as an extension.

Options xml: options: name of the template to display the rows
Name xml: id: index into the content-array, it need to be pre-set with some information for the nextmatch widget and it returns its content with it:

$content[$id] = array(		// I = value set by the app, 0 = value on return / output, 
	'get_rows'     =>	// I  method/callback to request the data for the rows eg. 'notes.bo.get_rows'
	'filter_label' =>	// I  label for filter    (optional)
	'filter_help'  =>	// I  help-msg for filter (optional)
	'no_filter2'   => True	// I  disable the 2. filter (params are the same as for filter)
	'template'     =>	// I  template to use for the rows, if not set via options
	'start'        =>	// IO position in list
	'cat_id'       =>	// IO category, if not 'no_cat' => True
	'search'       =>	// IO search pattern
	'filter'       =>	// IO filter, if not 'no_filter' => True
	'rows'         =>	//  O content set by callback
	'total'        =>	//  O the total number of entries
);

/*
 * example: the get_rows function from notes.bo.get_rows (has to be in public_functions !)
 */
function get_rows($query,&$rows,&$readonlys)
{
	$rows = $this->read($query['start'],$query['search'],$query['filter'],$query['cat_id']);
	if (!is_array($rows))
	{
		$rows = array( );
	}
	else
	{
		array_unshift($rows,0); each($rows);	// first entry is not used !!!
	}
	$readonlys = array( );	// set readonlys to enable/disable our edit/delete-buttons
	while (list($n,$note) = each($rows))
	{
		if (!$this->check_perms($this->grants[$note['owner_id']],PHPGW_ACL_EDIT))
		{
			$readonlys["edit[$note[id]]"] = True;
		}
		if (!$this->check_perms($this->grants[$note['owner_id']],PHPGW_ACL_DELETE))
		{
			$readonlys["delete[$note[id]]"] = True;
		}
	}
	return $this->total_records;
}

/*
 * Example how the nextmatch-widget is used in notes.ui.index:
 */
function index($content = 0)
{
	if (!is_array($content))
	{
		$content = array('nm' => $this->session_data); // restore settings from the session
	}
	if (isset($content['nm']['rows']))		// one of the buttons in the rows is pressed
	{
		$this->session_data = $values['nm'];	// save the settings in the session
		unset($this->session_data['rows']);	// we dont want to save the content of the rows
		$this->save_sessiondata();

		if (isset($values['nm']['rows']['edit']))
		{
			list($id) = each($values['nm']['rows']['edit']);
			return $this->edit($id);
		}
		elseif (isset($values['nm']['rows']['delete']))
		{
			list($id) = each($values['nm']['rows']['delete']);
			return $this->delete($id);
		}
	}
	$values['nm']['options-filter'] = array (	// set up the data for our filter
		'all'			=> 'Show all',
		'public'		=> 'Only yours',
		'private'	=> 'Private'
	);
	$values['nm']['get_rows'] = 'notes.bo.get_rows';
	$values['nm']['no_filter2'] = True;		// disable the 2. filter

	$this->tpl->read('notes.index');
	$this->tpl->exec('notes.ui.index',$values);
}


How to implement new widgets / extensions to the eTemplates?

The eTemplates have an interface to extend them with new widgets. These widgets are php-classes, can use eTemplates to define the UI of the new widget and are stored in the eTemplate's inc-dir or the inc-dir of a phpGroupWare application. The editor and the etemplate-class autoload the existing extensions.

I will made more documentation about the interface availible soon.

please contact me if you have further questions or comments about the eTemplates