From eba475c2c8409f61634812b942c97d12bf437b1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hans-J=C3=BCrgen=20Tappe?= Date: Sun, 12 Sep 2010 12:52:28 +0000 Subject: [PATCH] Merge Rev. 31586 into 1.8. --- etemplate/doc/reference.html | 1061 ++++++++++++++++++++++++++++++++++ 1 file changed, 1061 insertions(+) create mode 100644 etemplate/doc/reference.html diff --git a/etemplate/doc/reference.html b/etemplate/doc/reference.html new file mode 100644 index 0000000000..4800a1fd98 --- /dev/null +++ b/etemplate/doc/reference.html @@ -0,0 +1,1061 @@ + + + + eGroupWare: eTemplate-reference + + + + +

eTemplate-reference - Templates and Dialog-Editor for eGroupWare

+

by Ralf Becker RalfBecker AT outdoor-training DOT de

+

A reference 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. +
  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
    3. +
+
+

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>
+  <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:

+ +
+ +

Syntax and Parameter reference

+

Standard parametes / attributes for all widgets

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Name in Editorxml attrxulinternal namedescription of the attribut +
Typetype
(only for
sub-types)		notype + 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. +
Nameidyesname + 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):
+ + + + + + + + + + + + + + + + + + + + +
$cthe column-number (starting with 0, if you have a header, data-cells start at 1)
$colthe column-letter: 'A', 'B', 'C', ...
$rowthe row-number (starting with 0, if you have a header, data-cells start at 1)
$contthe 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_contthe 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.
+

Labellabelnolabel + 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. +
Helpstatustextyeshelp + 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). +
NoTranslationno_langnono_lang + If checked the content of the widget and the label gets NOT translated.
+ The helptext of a widget is always translated. +
neededneedednoneeded + If checked (xml-attr: needed="1") the etemplates will reprompt the user if he left + the widget / field empty.
+
Readonlyreadonlyyesreadonly + 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. +
Disableddisabledyesdisabled + If checked (xml-attr: disabled="true") the widget will NOT be shown. + For buttons this could be archived on runtime via setting them readonly. +
onChangeonchange?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, Classspan
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). +

Alignalignyesalign + Can be set to 'left' (default), 'center' or 'right'. +
Width, Disabled
column-attr.		widthyesrow[0][#] + Can be set to a percentage (eg. '10%'), a number of pixels or ... +
Height, Disabled
row-attr.		heightyesrow[0][h#] + Can be set to a percentage (eg. '10%'), a number of pixels or ... +
Disabled
column-attr.
row-attr.		disablednodisabled + 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: yesrow[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' +

blurTextblurnoblur + 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. +
+ + +

standard widgets and extensions of the eTemplates

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Widget Name
in Editor		xml tagxulinternal namedescription of the widget +
Label<description />yeslabel + 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:
+ 1. if it contains a 'i' and/or a 'b' the content (not the label) is rendered + in italic and/or bold.
+ 2. link: if set to a menuaction string or an array with get-params (via the content-arry), + a link to that methode = app.class.method is put around the label
+ 3. if set URLs in the content get activated
+ 4. name of form-element the label is for: gives focus to that element if the label gets clicked
+ 5. target for the link, eg. _blank
+ 6. widthxheight if a popup should be used for the link, eg. 600x400
+ 7. titlextitle for the link +

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

+ Options has 3 comma-separated fields:
+ xml: size: the length in chars of the input-field
+ xml: maxlength: the maximum length of the input
+ xml: validator: perl regular expression to validate the input (kommas are allowed in the expression) +

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:
+ xml: min: minimum value, default none, empty values are Ok, as long as needed is not set
+ xml: max: maximum value, default none, empty values are Ok, as long as needed is not set
+ 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 ...>. 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:
+ xml: min: minimum value, default none, empty values are Ok, as long as needed is not set
+ xml: max: maximum value, default none, empty values are Ok, as long as needed is not set
+ xml: size: the length in chars of the input-field, default 5 + xml: precision: precision of the float number, default maximum +

Textarea<textbox
multiline="true" />		yestextarea + 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 +

Formatted Text
(HTML)		<htmlarea />nohtmlarea + 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 5 comma-separated fields:
+ xml: mode: {ascii|simple|extended|advanced}
+ xml: height: height of htmlarea
+ xml: width: width of htmlarea
+ xml: toolbar: {true|false} show toolbar
+ xml: base_href: if passed activates the browser for images at the path (relative to the docroot +

Checkbox<checkbox />yescheckbox + 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.
+ Options: [set_value][,ro_true[,ro_false]]
+ set_value: which value in the content represents the checked state, default=1
+ 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 + If the value of the content array at index name/id matches set_value the radiobutton is marked 'checked'. +
Submitbutton<button image="img.gif" ro_image="img-grey.gif" />yesbutton + 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.
+ 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) . + onclick: specify some java-script to be called if the button gets pressed/clicked:
+ a) general javascript: "window.close();"
+ b) confirmation: "return window.confirm('');" (message get run through lang()!)
+ c) popup: app.class.func&id=$cont[id],target(default _blank),width (default 600),height (default 450) + You can use $cont[] or $row_cont[] (note no quotes!) to pass further information to the popup + via the content array.) +

Button<buttononly image="img.gif" ro_image="img-grey.gif" />nobuttononly + + a button
+ Same as Submitbutton but it is rendered as <input type="button" ...> in the html-UI +
Horizonatal Rule<hrule />nohrule + 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" />yestemplate + 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" />yesimage + 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
+ <listbox rows="#"/>

+ Examples for predefined selectboxes:

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

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

+ + +

yesselect + 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. +
  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
    3. +
+ 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 an eGW category, determined by the options-field:
+ ,{no_global_cats},{extra_style_multiselct},{cat_app(default:current app)}
+ select-account:
+ Select a user and/or group, determined by the options-field:
+ ,{accounts(default)|groups|both},{''(phpgw-default)|0(only lid)|1(only names)|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)
+ select-number:
+ Select a number out of a range specified by the options-field:
+ ,{start (default=1)},{end (incl., default=10)},{decrement (default={padding zeros}1)},{suffix}.
+ Example with padding zeros: options=',0,59,05' will give values: 00, 05, 10, ..., 55 + (like you would use it for minutes in a time-field). The suffix get's added to the label of each option.
+ select-dow:
+ Select one or multiple weekdays, keys are as defined in MCAL_M_... (1=Sun, 2=Mon, 4=Tue, ...)
+ select-app:
+ Select an application, availible options: ,{''=user enabled(default)|installed|all)} +

FileUpload + <file id="name"/>
+ 		nofile + 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"/> +

nodate + 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
+ week-number-prefix: if set (&32) readonly dates get prefixed with lang('Wk') & weeknumber
+ 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)
+ Options: [duration-storage-format] [,[duration-display][,hours_per_day]]
+ duration-storage-format: 'h' = hours (float), 'd' = days (float), default minutes (integer)
+ duration-display: 'd' = days, 'h' = hours, 'dh' = days or hours with selectbox, optional '%' allows to enter a percentage
+ hours_per_day: conversation between hours and (working) day, default 8 + hours_per_day: conversation between hours and (working) day, default 8 +

VBox, HBox, Box + <vbox>
+   <widget ...>
+   <widget ...>
+ </vbox>

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

+ <box orient="horizontal">
+   <widget ...>
+   <widget ...>
+ </box> +

yesvbox, 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).
+ orient: horizontal, vertical or none (means h/vbox as expected and no table for boxes) + cellpadding,cellspacing: known table-options + keepEmpty: if true, empty cells (lines or rows) are kept, otherwise they are completly removed +

GroupBox + <groupbox>
+   <caption label="Legend"/>
+   <widget ...>
+   <widget ...>
+ </groupbox>

+

yesgroupbox + 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).
+ orient: horizontal, vertical or none (defaults to vertical) + options: cellpadding,cellspacing of the table +

Tabs + <tabbox id="name">
+   <tabs>
+     <tab label="Tab 1" statustext="Help"/>
+     ...
+   </tabs>
+   <tabpanels>
+     <grid id="app.name.tab1"/>
+     ...
+   </tabpanels>
+ </tabbox> + 		yestab + 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 '.' +

Manual + <manual> + nomanual + 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> + nocustom_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"/> + yestab + 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_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
+	'lettersearch'   => True// I  show a lettersearch
+	'searchletter'   =>	// I0 active letter of the lettersearch or false for [all]
+	'start'          =>	// IO position in list
+	'num_rows'       =>	// IO number of rows to show, defaults to maxmatches from the general prefs
+	'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)
+	'filter_onchange'=> 'this.form.submit();'// I onChange action for filter, default: this.form.submit();
+	'filter2'        =>	// IO filter2, if not 'no_filter2' => True
+	'filter2_no_lang'=> True// I  set no_lang for filter2 (=dont translate the options)
+	'filter2_onchange'=> 'this.form.submit();'// I onChange action for filter, default: this.form.submit();
+	'rows'           =>	//  O content set by callback
+	'total'          =>	//  O the total number of entries
+	'sel_options'    =>	//  O additional or changed sel_options set by the callback and merged into $tmpl->sel_options
+	'no_columnselection' => // I  turns off the columnselection completly, turned on by default
+	'columnselection-pref' => // I  name of the preference (plus 'nextmatch-' prefix), default = template-name
+	'default_cols'   => 	// I  columns to use if there's no user or default pref (! as first char uses all but the named columns), default all columns
+	'options-selectcols' => // I  array with name/label pairs for the column-selection, this gets autodetected by default.
+					A name => false hides the column from the column-selection.
+					To completely hide a column, you need to use the Grid column attributes - disabled in eTemplate, and have your get_rows function
+					set a key that matches.
+					For example, if your column name is private_phone, use the eTemplate editor to set column disabled to @no_private_phone,
+					and have your get_rows function set $rows['no_private_phone'] = true (or some calculated condition).
+					
+	'return'         =>     // IO allows to return something from the get_rows function if $query is a var-param!
+	'csv_fields'     =>	// I  false=disable csv export, true or unset=enable it with auto-detected fieldnames,
+					or array with name=>label or name=>array('label'=>label,'type'=>type) pairs (type is a eT widget-type)
+);
+
+/*
+ * 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-
FilterHeader

Nextmatch-
Custom FilterHeader

Nextmatch-
AccountFilter

 + <nextmatch type="nextmatch-sortheader" id="col-name" options="DESC" label="ColLabel"/>

+ <nextmatch type="nextmatch-filterheader" id="col-name"/>

+ <nextmatch type="nextmatch-customfilter" id="col-name" options="select-precent"/>

+ <nextmatch type="nextmatch-accountfilter" id="col-name"/> +

nonextmatch-
sortheader

nextmatch-
filterheader

nextmatch-
customfilter

nextmatch-
accountfilter

nextmatch-
header

 + These widget are an optional part of the nextmatch widget.

+ nextmatch-sortheader
+ Widget to be placed as a colum-header in the headerline of a nextmatch-template. It allows, by clicking on it, + to order the lines of the nextmatch after a certain column. The column-name is given as name (xml:id) the + label is show as a link of button (no javascript). One can specify a default sorting: options={DESC|ASC} (default=ASC), + to be used when the header is clicked for the first time. Consecutive click on the header change the sorting + direction, indicated by a little up- or down-arrow. As a second comma-separated parameter one can specify an extra + label for the column-selection.

+ nextmatch-filterheader
+ Widget to allow to show only certain row, which match a selected filter-value. The column-name is given as name + (xml:id), the options of the displayed selectbox need to be set as for an ordinary selectbox (eg. in the options + parameter to the uietemplate::exec function). If no extra-label is given in options, lang('all') will be used for + the empty value, which means no filter activ. An (optional) label can be given and is also used for the column-selection.

+ nextmatch-customfilter
+ The custom filterheader allows to use other (select-)widgets to filter by them. They have to be specified as the first + parameter in the comma-separated options attribute. In all other aspects it is identical to the filterheader.

+ nextmatch-accountfilter
+ The Accountfilter allows to select users (via the prefered user-selection-method) to filter by them. + It's identical to a nextmatch-customfilter with options="select-account".

+ nextmatch-header
+ Just a header-label for a nextmatch column. It names the column for the column for the column-selection (in difference to the label). + The name is used to hide the column (with a 'no_' prefix) and as the name for the preference. + A different label for the column-selection preference can be specified via the option field.

+ Note: All four 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"/>

+

nolink-to

link-list

link-string

 + These widgets are the UI-part of the link-class ({bo|so}link) in the API.

+ eGroupWare has a linking system that lets you link two records from different apps together.

+ For example, you can link the addressbook entry of the person you're meeting with to the meeting on your calendar, + or an infolog entry for the phone call you made to postpone the meeting.

+ To display links in your own application, you should use the LinkList group of widgets.

+ link-list
+ Widget to shows the links to an entry and a Unlink Button for each link.

+ It needs an array with two entries. If you name the LinkList widget 'links', you need:

+
+$data['links']['to_app'] = 'myapp';
+$data['links']['to_id'] = $record_id;
+
+

This will display links where the $record_id record of myapp is one side of the link. + Make sure that both variables are properly defined before the form template gets executed. +

link-to
+ Widget to make a links to other entries of link-aware apps and to attach files.

+ Note: Both Widgets can be used on the same template with the same name. They share + the content of the variable with that name, which contains just the id of the entry in the current app.

+ + link-string
+ Comma-separated list of link-titles with a link to its view-method, value is like the return + of bolink::get_links().

+

+ Before you can use a link to your application, you need to specify some information in a 'search_link' hook.

+ In your setup.inc.php, you need to point $setup_info['myapp']['hooks']['search_link'] to a function that will return an array:

+

return array(
+'query' =>      'myapp.bo_myapp.link_query', 
+	// A function that takes a search string
+	// and returns a list of matching records
+'title' =>      'myapp.bo_myapp.link_title', 
+	// A function that takes an id from one side
+	// of a link and returns a string for that entry
+'view'  =>      array('menuaction'=>'myapp.ui_myapp.link_view'),
+	// Function to view a link, may be an existing view function
+'view_id'       =>      'link_id', 
+	// name of the id variable provided to the view function above
+'add'   =>      array('menuaction' => 'myapp.ui_myapp.new_entry'), 
+	// Function to add a new entry
+);
+
+

Also, make sure that the declared methods are implemented and methods from the UI class are listed in its $public_methods attribute: +

+class ui_myapp {
+	var $public_methods = array(
+		'view' => true,
+		'add' => true
+	);
+...
+}
+
+
Ajax Selectajax_select +

The Ajax Select is a Combo Box. It lets the user type anything they want, and choose from a list of options that are presented below. The user is not limited to the choices, but there is +some checking done. If what they type returns several results, and they don't choose one, for example. You can reject +any values you don't like in your UI code. It is best used where you might normally want to use a selectbox but your list of data is too large. You can have several on one page, but the name +must be different for each.

+

Options can be found under the "AJAX Select options" section of the pop-up.

+

Data Source: the list options, can be any function that can provide data for a nextmatch widget.

+

Title Source: When an option from the list is selected, the text in the search function is replaced with the result of this function. The ID Field is passed. link_title() functions work well.

+

ID Field: Data Source is expected to return an array as for a nextmatch, with several columns. This is the key of the column you actually want returned for a value.

+

Result row template: (Optional) You can provide a custom eTemplate to use for the list options. It should be constructed similarly to a row template for a nextmatch, and will be repeated for each option.

+

Link: (Optional) If the field is read-only, and Link is provided, the widget will turn into a link. Link should look like: perp_ap.ui_perp_supplier.edit&supplier_id=${cont[supplier_id]} where ID Field is supplier_id.

+

Icon: (Optional) An icon placed to the left of the search box, to help indicate what the user is searching (addresses, suppliers, etc.). It will be automatically resized.

+
+

One remark about cross-site-scripting

+The following eTemplate Widgets are parsing its content before displaying through htmlspecialchars() to +correctly display the content and to gard against malecious data (like scripts etc.): + +This is done in most cases by the underlaying html-class and not direct in eTemplate. +

+

+ +

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 +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. + +

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

+ + +