A reference documentation about the new eTemplates and the syntax and parameters +of the several widgets.
+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:
+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>
+ <template id="et_media.edit" template="" lang="" group="" version="">
+ <grid 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>
+ </template>
+</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:
+| 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):
|
+||||||||||||
| Label | +label | +no | +label | +
+ The label is displayed by default in front (for radiobuttons behind) each widget (if not empty).
+ If you want to specify a different position, use a '%s' in the label, which gets replaced by
+ the widget 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). + Note: The label gets always translated, if its longer than 1 char! If this is not + disired, use a label widget, place the not-to-translate label in the content-array + and check NoTranslation or set the xml attribute no_lang. + |
+||||||||||||
| 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 and after expanding the variables). + | +||||||||||||
| Options | +? | +? | +size | ++ This attribute controls certain aspects of the different widgets. It's meaning and xml / xul-values + are document with the widgets. + If the options-string starts with a '@' it is replaced by the value of the content-array at this + index (with the '@'-removed and after expanding the variables). + | +||||||||||||
| 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. + |
+||||||||||||
| 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. + If the class-string starts with a '@' it is replaced by the value of the content-array at this + index (with the '@'-removed and after expanding the variables). + |
+||||||||||||
| 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 | +disabled | +
+ 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' + |
+||||||||||||
| blurText | +blur | +no | +blur | +
+ This text get displayed if an input-field is empty and does not have the
+ input-focus (blur). It can be used to show a default value or a kind of help-text. + If it contains a text (eg. 'Search...'), this text is run through lang(), if it contains + a reference to the content array (eg. '@blur_text') it does not get translated. + |
+
| 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 has 5 comma-separated fields: |
+|
| Text | +<textbox /> | +yes | +text | +
+ a single-line input field for text + In the html-UI this is rendered as <input ...>
+ Options has 3 comma-separated fields: |
+|
| Integer | +<textbox type="int" /> |
+ ? | +int | +
+ a input-field to enter an integer + In the html-UI this is rendered as <input ...>. The input-validation is done at the moment only on server-side, + clientside validation and input-restriction to only numbers is planed.
+ Options has 3 comma-separated fields: |
+|
| Float | +<textbox type="float"/> |
+ ? | +float | +
+ a input-field to enter a float + In the html-UI this is rendered as <input ...>. The input-validation is done at the moment only on server-side, + clientside validation and input-restriction to only numbers is planed.
+ Options has 4 comma-separated fields: |
+|
| 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: |
+|
| Formatted Text (HTML) |
+ <htmlarea /> | +no | +htmlarea | +
+ a multiline input-field for formatted (HTML) text + In the html-UI this is rendered as <textarea ...> and the HTMLarea javascript editor is used.
+ Options has 2 comma-separated fields: |
+|
| Checkbox | +<checkbox /> | +yes | +checkbox | +
+ a widget that can be checked or unchecked + In the html-UI this is rendered as <input type="checkbox" ...>. + Multiple checkboxes can have an identical name ending with [], in that case the value will be an array with the set_value's + of the checked boxes. You can use a button with a custom javascript onclick action of eg. + "toggle_all(this.form,form::name('nm[rows][checkbox][]')); return false;" and a set_value of "$row_cont[id]" to toggle + all checkboxes in the lines of a nextmatch widget. The form::name( ) function translate the name used + in the template into the name used in the form. If the button is an image-button, check needed to render it as button + and not as image with link, which has no this.form property! + Options: [set_value][,unset_value[,ro_true[,ro_false]]]+ set_value: which value in the content represents the checked state, default=1 + unset_value: value in the content representing the unchecked state, default=0 + ro_true: what should be displayed for a readonly checked box, default=x + ro_false: display for an unchecked box, can be set to 'disable', to not display the widget (incl. label), default is empty + |
+|
| 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 disabled.
+ needed: 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. |
+|
| 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 | +<template 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: up to 4 comma-separated values: + 1. link to a methode = app.class.method for the image + 2. target for the link, eg. _blank + 3. imagemap + 4. widthxheight if a popup should be used for the link, eg. 600x400 + |
+|
| Selectbox | +
+ <menulist> + <menupopup id="name" options="Select one" /> + </menulist>
+ multiselect: options > 1 + Examples for predefined selectboxes: + <listbox type="select-cat" rows="5"/>
+ <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: +
+ 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): |
+|
| 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"/> + <date type="date-time"/> + <date type="date-timeonly" options="H:i"/> + <date type="date-houronly"/> + <date type="date-duration"/> + |
+ no | +date | +
+ Date-/Time-input via selectboxes or a field for the year + The order of the input-fields is determined by the prefs of the user. + Options: [datetime-storage-format] [,&1=year-no-selectbox|&2=today-button|&4=one-min-steps|&8=ro-suppress-0h0] + datetime-storage-format is the format, in which the date is stored in the variable: + empty means an unix-timestamp (in GMT), or a string containing the letters Y, m, + d, H, i plus separators, eg. 'Y-m-d': 2002-12-31. The storage format + for times is always 24h or timestamp with date 1.1.1970 (if no date used). (This has nothing + to do with the format of the display, which is only determined by the users preferences.) + year-no-selectbox if set (&1) an int-widget (input-field) is used instead of a + select-year widget. + today-button: if set (&2) a [Today] button is displayed which sets the fields to + the up-to-date date (via javascript) + one-min-steps: if set (&4) the minute-selectbox uses one minutes steps, default 5min steps + ro-suppress-0h0: if set (&8) the time is suppressed for readonly and a time of 0h0 + day-of-week-prefix: if set (&16) readonly dates get prefixed with the day of week + Sub-widgets: date-time: a date and a time and date-timeonly or date-houronly: only a time / hour + These widgets allow the input of times too or only, they use 12h am/pm or 24h format as + specified in the user prefs. + If readonly is set, this widget can be used to display a date, without the need to convert it.
+ Duration a floating point input with an optional selectbox for the unit (hours or days) |
+|
| VBox, HBox, Box | +
+ <vbox> + <widget ...> + <widget ...> + </vbox>
+ <hbox span="all">
+ <box orient="horizontal"> |
+ yes | +vbox, hbox, box | +
+ vertical or horizontal container for child widgets. This is useful if one needs more
+ widgets or widgets outside the column- / row-order of a grid. HBox or VBox is rendered as Grid/html:table
+ with only one row or colum. Box is rendered as a html:div containing all child-widgets. + 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). |
+|
| GroupBox | +
+ <groupbox> + <caption label="Legend"/> + <widget ...> + <widget ...> + </groupbox> + |
+ yes | +groupbox | +
+ container to visualy group other widgets by putting a border around them. + The upper line may contain a legend. The widgets are ordered vertical, like a VBox. + 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: |
+|
| Manual | ++ <manual> + | +no | +manual | +
+ open the online help: displays a small manual icon. + Name xml: id: optional name of the manual page (as index into $content or direct). + If no manual page is given, the link included the referer as _GET param. + |
+|
| Custom fields | ++ <custom_fields> + | +no | +custom_fields | +
+ display custom fields: the fields can be configured with admin.customfields.edit&appname={app} + The indexes of the custom fields in content are prefixed with a hash (#). + |
+|
| 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 |
+|
++$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_filter' => True// I disable the 1. filter + 'no_filter2' => True// I disable the 2. filter (params are the same as for filter) + 'no_cat' => True// I disable the cat-selectbox + 'cat_app' => // I application the cat's should be from, default app in get_rows + 'template' => // I template to use for the rows, if not set via options + 'header_left' => // I template to show left of the range-value, left-aligned (optional) + 'header_right' => // I template to show right of the range-value, right-aligned (optional) + 'bottom_too' => True// I show the nextmatch-line (arrows, filters, search, ...) again after the rows + 'never_hide' => True// I never hide the nextmatch-line if less then maxmatch entrie + 'start' => // IO position in list + 'cat_id' => // IO category, if not 'no_cat' => True + 'search' => // IO search pattern + 'order' => // IO name of the column to sort after (optional for the sortheaders) + 'sort' => // IO direction of the sort: 'ASC' or 'DESC' + 'col_filter' => // IO array of column-name value pairs (optional for the filterheaders) + 'filter' => // IO filter, if not 'no_filter' => True + 'filter_no_lang' => True// I set no_lang for filter (=dont translate the options) + 'filter2' => // IO filter2, if not 'no_filter2' => True + 'filter2_no_lang'=> True// I set no_lang for filter2 (=dont translate the options) + '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( ); + } + $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); +} ++ |
+|||||
| Nextmatch- SortHeader Nextmatch- Nextmatch- |
+
+ <nextmatch type="nextmatch-sortheader" id="col-name" options="DESC" label="ColLabel"/> + <nextmatch type="nextmatch-filterheader" id="col-name"/> + <nextmatch type="nextmatch-accountfilter" id="col-name"/> + |
+ no | +nextmatch- sortheader nextmatch- nextmatch- |
+
+ These widget are an optional part of the nextmatch widget.
+ nextmatch-sortheader
+ nextmatch-filterheader
+ nextmatch-accountfilter + Note: All three widgets interoperate with the nextmatch-widget which passes the set values as part if + the query-parameter to its get_rows function, they are not returned in the rows sub-array. + |
+|
| LinkWidgets | +
+ <link type="link-to" id="name"/> + <link type="link-list" id="name"/> + <link type="link-string" id="name"/> + |
+ no | +link-to link-list link-string |
+
+ These widget are the UI-part of the link-class ({bo|so}link) in InfoLog and maybe the API soon.
+ link-to
+ link-list + Note: Both Widgets can be used on the same template with the same name. They share + the content of that variable, which contains just the id of the entry in the current app.
+
+ link-string |
+|
+
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 +eGroupWare application. The editor and the etemplate-class autoload the existing extensions.
+ +I will made more documentation about the interface availible soon. For now have a look for the source +of the existing extensions. + +