Simple Groupware sgsML Extended Attributes

This page contains all extended attributes and tags for sgsML. All basic attributes are described here.

Note: All extended attributes and tags are optional.


Tag structure


<table> tag: extended attributes

  • load_library: Loads an additional library in the bootstrap. The base path is "<sgs-dir>/bin/" or "<sgs-dir>/src/".
    useful for: modules that need a PHP library
    example: load_library="lib/pmwiki/pmwiki.php"
    used in: cms.xml, nodb_pmwiki.xml
  • load_css: Loads an additional stylesheet in the head section of the page. The base path is "<sgs-dir>/bin/" or "<sgs-dir>/src/".
    useful for: modules that need a custom stylesheet
    example: load_css="ext/cms/styles.css"
    used in: cms.xml, nodb_pmwiki.xml
    available since: 0.643
  • name: Defines a table name which overrides the normal table name in all queries. If undefined, the module name will be used as the table name.
    useful for : overwriting the default table name
    example: name="simple_sys_tree"
    used in: nodb_rights_edit.xml
  • custom_name: Defines a table name or a sub-query which overrides the normal table name in all "select" queries. If undefined, the module name will be used as the table name.
    useful for: map data into another (sub-)schema
    example: custom_name="simple_contacts_archive"
    used in: search.xml, nodb_calendar_contacts.xml
  • default_sql: Defines a default query used to retrieve assets. If undefined, a select query is automatically built by the "fields" and "where" statements assigned to a view. Variables like @folder@ or @table@ automatically get replaced with their current values.
    By default, only assets of the current folder are shown in the current view. So if a "default_sql" query returns a "folder" field with a different ID, assets are not shown because the access is denied. You can bypass the folder check by adding the attribute "nosqlfolder" with the value "true".
    ---
    special values: no_select (don't run selects)
    example: default_sql="show full columns from @table@" (MySQL)
    used in: nodb_structure.xml, nodb_admin.xml (and more)
  • template: Defines the default Smarty template, used to render the views. If undefined, each view needs to define it's own template attribute or uses the view's name to set a template implicitly.
    useful for: refer to a different template without changing the view name
    example: template="display" (for templates/asset_display.tpl)
    used in: nodb_schema.xml, nodb_rights.xml (and more)
  • no_search_index: Disables the search indexer for the module. If undefined, all new or changed assets will be put into the search index. Modules that contain "_nodb_" in the filename are automatically excluded.
    example: no_search_index="true"
    used in: search.xml, session.xml (and more)
  • disable_*: Disables automatic views, buttons or fields in the module. If undefined, some special views, buttons and fields are automatically added to the module.
    Notification and summary allow people to get notified about changes.
    Bgcolor allows to mark assets with a background color as label.
    attribute names for views: disable_{history|index|schema|search|copy|structure|rights}
    attribute names for buttons: disable_{paste|copy|cut}
    attribute names for fields: disable_{bgcolor|notification}
    example: disable_history="true"
    used in: session.xml
  • enable_calendar: Enables the calendar box above the tree. Contains relevant fields for time frame selection, can be only field (created), two fields (begin, end) or nine fields (including recurrence, intervals and exclusions). If undefined, only events that match the selected time frame will be shown.
    example: enable_calendar="created"
    example #2: enable_calendar="begin,ending"
    used in: calendar.xml, events.xml (and more)
  • hide_calendar: Hides the calendar pane. If undefined, all entries with begin and end date will be displayed in the calendar pane.
    example: hide_calendar="true"
    used in: ---
  • sql_handler: Defines a class used to delegate all queries to. The prefix of the class name "lib_" is left out. The folder for a library of a module is "modules/lib/". Is mainly used for external data structures defined over mountpoints (see data handlers and "modules/lib/default.php").
    ---
    example: sql_handler="fs" (class name lib_fs)
    example classes: modules/lib/fs.php, modules/lib/csv_contacts.php
    interface definition: modules/lib/default.php
    used in: nodb_fs.xml, nodb_csv_contacts.xml (and more)
  • disable_rights: Disables folder permissions for a module. If undefined, folder permissions can be set for every folder of the module.
    example: disable_rights="true"
    used in: nodb_fs.xml, nodb_imap.xml (and more)
  • disable_folder_operations: Disables folder operations for a module. If undefined, folders can be created, renamed and deleted.
    example: disable_folder_operations="true"
    used in: nodb_pop3.xml, nodb_xml.xml (and more)
  • trigger_new: Calls a PHP method after a new asset was created. Can be more than one method, separated by "|". Method parameters can be added, separated by ":". Default class is "trigger", can be changed with prefix "classname::".
    example: trigger_new="createcontact"
    example #2: trigger_new="somemethod|other_class::anothermethod:100:abc"
    example #3: trigger_new="runxml:modules/coreprojects.xml:projects"
    ---
    signature: static function anothermethod($id, $row, $params, $table)
    [$id = asset id, $row = dataset array, $params = parameters array(100,'abc'), $table = table name, return string empty (success) or error message (trigger failed)]
    ---
    used in: contacts.xml, projects.xml (and more)
  • trigger_edit: Calls a PHP method after an asset was changed. Can be more than one method, separated by "|". Method parameters can be added, separated by ":". Default class is "trigger", can be changed with prefix "classname::".
    example: trigger_edit="editcontact"
    example #2: trigger_edit="somemethod|other_class::anothermethod:100:abc"
    ---
    signature: static function anothermethod($id, $row, $params, $table)
    [$id = asset id, $row = dataset array, $params = parameter array(100,'abc'), $table = table name, return string empty (success) or error message (trigger failed)]
    ---
    used in: contacts.xml, projects.xml (and more)
  • trigger_delete: Calls a PHP method after an asset was deleted. Can be more than one method, separated by "|". Method parameter can be added, separated by ":". Default class is "trigger", can be changed with prefix "classname::".
    example: trigger_delete="deletecontact"
    example #2: trigger_delete="somemethod|other_class::anothermethod:100:abc"
    ---
    signature: static function anothermethod($id, $row, $params, $table)
    [$id = asset id, $row = dataset array, $params = parameter array(100,'abc'), $table = table nae, return string empty (success) or error message (trigger failed)]
    ---
    used in: contacts.xml, projects.xml (and more)
  • disable_trigger_ccp: Disables all triggers on cut-copy-paste. If undefined, the paste command will execute a trigger defined in the "trigger_new" attribute. If undefined, the cut command will execute a trigger defined in the "trigger_delete" attribute.
    example: disable_trigger_ccp="true"
    used in: emails.xml, nodb_imap.xml
    available since: 0.651


Note: Custom classes can be put under "custom/core/classes/" (will be tried first) or "ext/core/classes/" (reserved for extensions). E.g. "class mymethods {}" in "custom/core/classes/mymethods.php".


<view> tag: extended attributes

  • template: Defines the Smarty template, used to render the current view. If undefined, the "template" attribute in the "table" tag will be used or (if not present), the "name" attribute of the current view will be used to determine the Smarty template (e.g. name="display" => templates/asset_display.tpl).
    useful for: refer to a different template without changing the view name
    example: template="free" (for templates/asset_free.tpl)
    used in: gallery.xml, portal.xml (and more)
  • enable_calendar: Enables the calendar box above the tree. Contains relevant fields for time frame selection, can be only field (created), two fields (begin, end) or nine fields (including recurrence, intervals and exclusions). If undefined or not present in the "table" tag, only events that match the selected time frame will be shown in the current view.
    ---
    example: enable_calendar="created"
    example #2: enable_calendar="begin,ending"
    used in: calendar.xml, events.xml (and more)
  • hide_calendar: Hides the calendar pane in the current view. If undefined, the "hide_calendar" attribute in the "table" tab will be used or (if not present), all entries with begin and end date will be displayed in the calendar pane.
    example: hide_calendar="true"
    used in: ---
  • hide_tabs: Hides some tabs in the current view. If undefined, all tabs are visible. Multiple values can be used, separated by "|".
    example: hide_tabs="tabname1|tabname2"
    used in: ---
  • disable_tabs: Hides the tabs bar and shows all (visible) fields in one tab.
    example: disable_tabs="true"
    used in: users.xml
  • default_sql: Defines a default query used to retrieve assets in the current view. If undefined, the "default_sql" attribute in the "table" tag will be used or (if not present), a select query is automatically built by the "fields" and "where" statements assigned to a view. Variables like @folder@ or @table@ automatically get replaced with their current values.
    ---
    special values: no_select (don't run selects)
    example: default_sql="show full columns from @table@" (MySQL)
    used in: sgsml.php
  • nosqllimit: Shows all assets in a folder. If undefined, only a maximum number of assets will be displayed on a page, including links to next and previous pages.
    example: nosqllimit="true"
    used in: ---
  • nosqlorder: Shows assets unsorted. If undefined, assets are displayed sorted by the "orderby" attribute defined in "view" or "table" tags.
    example: nosqlorder="true"
    used in: ---
  • nosqlwhere: Shows all assets in the view. If undefined, filters from "where" attributes in "view" or "table" tags will be applied to all select queries.
    example: nosqlwhere="true"
    used in: ---
  • nosqlfolder: Shows assets of all folders in the view. If undefined, only assets of the current folder will be shown in the current view.
    useful for: views not depending on folders
    example: nosqlfolder="true"
    used in: events.xml, tree.xml (and more)
  • visibility: Defines where the link to the view should be shown. If undefined, the link will be displayed as a button in the view bar at the top. The value "hidden" will not show a link to the view. The value "bottom" will show a link below the tree at the left side. And "active" will only show a button in the view bar, if the view is currently selected.
    valid values: hidden, active, bottom
    example: visibility="bottom"
    used in: emails.xml, users.xml (and more)
  • noviewbuttons: Hides buttons in the current view. If undefined, all buttons defined as "view buttons" are displayed in the upper right in the current view. Can hide all buttons with value "true" or some buttons with names in the value, separated by "|".
    example: noviewbuttons="true"
    example #2: noviewbuttons="paste|delete"
    used in: sgsml.php, calendar.xml
  • nosinglebuttons: Hides buttons for each asset in the current view. If undefined, all buttons defined as "single buttons" are displayed for each asset. Can hide all buttons with value "true" or some buttons with names in the value, separated by "|".
    example: nosinglebuttons="true"
    example #2: nosinglebuttons="take_over|close"
    used in: sgsml.php, calendar.xml (and more)
  • doubleclick: Defines a name of a view that will be opened when a double-click is done on the background of an asset.
    example: doubleclick="details"
    used in: ---
  • accesskey: Defines an accesskey which opens the view. If undefined, views can be accessed by numbers, e.g. first view Alt-1, second view Alt-2, etc.
    example: accesskey="e"
    used in: sgsml.php
  • schema_mode: Defines a mode in which the current view can be used. The value "new" is used for forms that create new assets. The value "edit" is used for forms that change assets. The value "edit_as_new" is used for forms that create new assets from existing assets. The value "static" hides filters and pagers from the view and is used in combination with the "function" attribute. If undefined, creating or editing assets in a view won't be allowed.
    ---
    valid values: edit, create, edit_as_new, static
    example: schema_mode="edit"
    used in: users.xml, emails.xml (and more)
  • schema: Defines a sub-schema (sgsML) that is used for the current view. If undefined, the sgsML schema from the current module will be used for all views. A sub-schema is the first view of a separate module in a separate .xml file. The sub-schema overloads the current view and also attributes from the "table" tag.
    ---
    useful for: map a birthday field in contacts into appointments
    example: schema="sys_nodb_calendar_contacts" (modules/schema_sys/nodb_calendar_contacts.xml)
    used in: contacts.xml, users.xml (and more)
  • right: Defines a permission that is required to access the current view. If undefined, read permissions to the current folder are required.
    valid values: read, write, admin
    example: right="write"
    used in: sgsml.php
  • function: Calls a PHP method to render the current view. Default class is "custom", can be changed with prefix "classname::". Important feature to integrate custom PHP applications within Simple Groupware.
    example: function="testing"
    example #2: function="other_class::somemethod"
    ---
    signature: static function somemethod($folder, $view)
    [$folder = current folder id, $view = current view, return HTML output]
    ---
    used in: nodb_phpinclude.xml


Note: Custom classes can be put under "custom/core/classes/" (will be tried first) or "ext/core/classes/" (reserved for extensions). E.g. "class mymethods {}" in "custom/core/classes/mymethods.php".


<rowfilter> tag

Rowfilter is an optional tag in the structure and contains a PHP method to modify the output of an asset in a view. Compared to the <filter> tag, the result can be applied as a style to the whole asset.
Calls a PHP method to modify the output of an asset in a view. There can be multiple <rowfilter> tags inside a <table> tag. Method parameters can be added, separated by "|". Default class is "modify", can be changed with prefix "classname::". The "name" attribute serves as a unique identifier. The "views" attribute contains view names to apply the filter to, separated by "|". The "type" attribute can be set to "_fgstyle" to set a foreground CSS attribute or "_bgstyle" to set a background CSS attribute. The "views" attribute contains the field names to be validated, separated by "|".

Example:

<rowfilter name="filter1" views="all" type="_bgstyle" function="isinpast|ending|background-color:#FFDDDD;"/>

<rowfilter name="filter2" views="all" type="_bgstyle" function="myclass::rowfilter|abc|100"/>

Signature: static function rowfilter($row, $params)

  • $row = dataset array with "data" and "filter" keys
  • $params = parameter array('abc',100)
  • return string style attribute(s)


<rowvalidate> tag

Rowvalidate is an optional tag in the structure and contains a PHP method to validate new assets. Compared to the <validate> tag, it validates the whole row in place of one field.
Calls a PHP method to validate an asset before saving it to the database. There can be multiple <rowvalidate> tags inside a <table> tag. Method parameters can be added, separated by "|". Default class is "validate", can be changed with prefix "classname::". The "name" attribute serves as a unique identifier. The "fields" attribute contains the field names to be validated, separated by "|".

Example:

<rowvalidate name="v1" fields="categoryname|cattype" function="itemsexist|simple_categories|categoryname,cattype"/>

<rowvalidate name="v2" fields="field_a,field_b" function="myclass::rowvalidate|abc|100"/>

Signature: static function rowvalidate($row, $params)

  • $row = dataset array
  • $params = parameter array('abc',100)
  • return string empty (valid asset) or error message (invalid asset)


<field> tag: Extended attributes (optional)

  • simple_default_function: Defines a default input value by using a PHP method when creating a new asset. If undefined, the input value will be empty by default. Default class is "modify", can be changed with prefix "classname::".
    translatable: yes
    example: simple_default_function="getusername"
    example #2: simple_default_function="dateformat|now|{t}m/d/Y{/t}"
    example #3: simple_default_function="fillform|var1" (request parameter "var1")
    example #4: simpleabc_default_function="myclass::default_method|100|abc"
    ---
    signature: static function default_method($params)
    [$params = parameter array(100,'abc'), return string default value]
    ---
    used in: contacts.xml
  • is_unique_with_trash: Requires the field to have a unique value and covers also values that exist in the trash folder. If undefined, the input value of the current field can exist more than once in assets belonging to the same module.
    ---
    useful for: unique system values (e.g. usernames)
    example: is_unique_with_trash="true"
    used in: users.xml
    available since: 0.644
  • no_checks: Avoids checks for insecure HTML. If undefined, all fields will be checked for insecure HTML code (see function modify::htmlfield). This can be useful for filters producing HTML code like forms, that normally get stripped out.
    ---
    useful for: filters producing HTML code like forms (get stripped out by default)
    example: no_checks="true"
    used in: surveys.xml
    available since: 0.643
  • hidden: Fetches the values for the field from the database, but does not show the field in the view. If undefined, all fields defined in a module will be fetched from the database and shown in the view. Can be overridden by "editable" attriute for "new" and "edit" views.
    ---
    useful for: fields to hide in a view but use them in filters
    example: hidden="true"
    used in: calendar.xml, forum.xml (and more)
  • editable: Allows to edit a field that is hidden in all views. Used to set a value in "new" and "edit" views, but do not show the value in other views.
    useful for: notifications, assign colors to assets
    example: hidden="true" editable="true"
    used in: tasks.xml, forum.xml (and more)
  • nodb: Uses a field in a view, but does not create the field in the database table. If undefined, all fields defined in the module will be created in the database.
    example: nodb="true"
    used in: search.xml, stats.xml
  • db_size: Sets the maximum field size for the field in the database table. If undefined, the field size will be determined by the "simple_type" attribute. Text fields get a limit of 255, IDs get 15, dates get 10 and text areas, select boxes are limited to 64k.
    example: db_size="VALUE"
    used in: stats.xml, tree.xml (and more)
  • db_type: Sets a field type for the field in the database table. If undefined, the field type will be determined by the "simple_type" attribute. Text fields get be "varchar", text areas and select boxes get "text", dates, bools and IDs are saved as "int".
    ---
    useful for: fields requiring bigger fields or numeric representations
    example: db_type="int"
    used in: calendar.xml
  • no_search_index: Forbids to put the field values in the search index. If undefined, all field values will be indexed and presented in the search results.
    useful for: password fields
    example: no_search_index="true"
    used in: tree.xml, users.xml (and more)
  • disable_ccp: Does not copy the field value when using copy-paste. If undefined, all field values will be copied to the new dataset.
    useful for: password fields
    example: disable_ccp="true"
    used in: users.xml, surveys.xml (and more)
  • input_height: Sets the height of an input field. If undefined, the height will be set to "300" pixels. Only used for simple types "htmlarea", "codearea" and "spreadsheet".
    example: input_height="300"
    used in: htmldocs.xml
  • notinall: Excludes a field from all views and from the search index. Also avoids fetching the field from the database. Can be overridden for some views with the "onlyin" tag.
    useful for: internal fields like created, lastmodified
    example: notinall="true"
    used in: tasks.xml, projects.xml
  • form: Sets attributes used to display the current field in a form (edit, new, edit as new). Only defined for simple_type "textarea". "no_template_bar" disables the option to add templates to the text box. "no_formatting_button" hides the button "Text formatting rules".
    valid values: no_formatting_button, no_template_bar
    example: form="no_formatting_button|no_template_bar"
    used in: emails.xml, nodb_imap.xml (and more)
    available since: 0.651


<field> tag: extended sub-tags

  • <KEY>: Makes the field a primary key in the database table. Primary keys are unique indexes which speed up lookups in the database.
    example: <KEY/>
    used in: hosts.xml, search.xml
  • <INDEX>: Creates an index over the field in the database table. Indexes speed up lookups in the database.
    example: <INDEX/>
    used in: contacts.xml, tasks.xml (and more)
  • <INDEX_FULLTEXT>: Creates a fulltext index over the field in the database table. Fulltext indexes speed up search operations on texts.
    example: <INDEX_FULLTEXT/>
    used in: search.xml

  • <store>: Calls a PHP method to modify the current field before saving it to the database. There can be multiple <store> tags inside a <field> tag. Method parameters can be added, separated by "|". Default class is "modify", can be changed with prefix "classname::".
    ---
    useful for: convert user input before saving, e.g. convert human readable dates to unix timestamps
    example: <store function="html_tidy"/> (reduce HTML code)
    example #2: <store function="datetime_to_int"/>
    example #3: <store function="myclass::store_method|100|abc"/>
    ---
    signature: static function store_method($value, $row, $params)
    [$value = value to be stored, $row = dataset array, $params = parameter array(100,'abc'), return string storable value]
    ---
    used in: contacts.xml, htmldocs.xml (and more)

  • <restore>: Calls a PHP method to restore the current field before displaying the field in the form of the "edit" and "edit as new" views. There can be multiple <restore> tags inside a <field> tag. Method parameters can be added, separated by "|". Default class is "modify", can be changed with prefix "classname::". The "views" attribute contains view names, separated by "|". Will be applied before "filters" attribute.
    ---
    useful for: make fields empty in "edit as new" view, convert unix timestamps to human readable dates
    example: <restore views="edit_as_new" function="empty_str"/>
    example #2: <restore views="reply|replyall" function="empty_str"/>
    example #3: <restore views="all" function="myclass::restore_method|100|abc"/>
    ---
    signature: static function restore_method($value, $params, $row)
    [$value = value to be restored, $params = parameter array(100,'abc'), $row = dataset array with "data" and "filter" keys, return string restored value]
    ---
    used in: cms.xml, forum.xml (and more)

  • <readonlyin>: Read-only-in removes the field from "new" and "edit" views. If undefined, all fields of a module are visible in a view. The "views" attribute contains view names, separated by "|".
    useful for: non-editable fields like IDs
    example: <readonlyin views="edit"/>
    used in: emails.xml, users.xml (and more)

  • <hiddenin>: Hidden-in fetches the current field from the database, but does not show it in some views. If undefined, all fields of a module are editable in "new" and "edit" views. The "views" attribute contains view names, separated by "|".
    ---
    useful for: fields to hide in a view but use them in filters
    example: <hiddenin views="display"/>
    used in: surveys.xml


Note: Custom classes can be put under "custom/core/classes/" (will be tried first) or "ext/core/classes/" (reserved for extensions). E.g. "class mymethods {}" in "custom/core/classes/mymethods.php".

Note: Custom types can be put under "custom/core/types/" (will be tried first) or "ext/core/types/" (reserved for extensions). E.g. "class type_mytext {}" in "custom/core/types/mytext.php".

Note: Showing a field in a view is evaluated by the following order: notinall (attribute in <field>), notin (tag in <field>), onlyin (tag in <field>), showonly (attribute in <view>)

Note: In Simple Groupware, translatable strings are marked with "{t}", "{/t}". For example "{t}Open{/t}" will be translated to "Offen" in German.


Release changes

  • v0.730: added "disable_notification" and "disable_bgcolor" attributes to the table tag.
  • v0.720: changed form attribute separator from "," to "|".
  • v0.661: added "form" attribute to the "field" tag.
  • v0.651: added "disable_trigger_ccp" attribute to the "table" tag.
  • v0.646: renamed "cust_name" attribute to "custom_name"
    ("cust_name" will continue to work)