Creating midcom.helper.datamanager schemas
- midcom.helper.datamanager2
- An example schema
- Schema definition
- Schema's field definitions
- Input validation
- Field grouping
- Complex example schema
Datamanager schemas are one of the most powerful features in MidCOM. Most components utilize Datamanager for content storage, editing and display.
midcom.helper.datamanager2
Schema declarations described here are valid only for the first generation datamanager, known as midcom.helper.datamanager. Most of the modern components use midcom.helper.datamanager2, which is a complete rewrite of the first generation datamanager and is not backwards schema compatible.
Please refer to Datamanager 2 schema definition for more details on midcom.helper.datamanager2 schemas.
An example schema
Here's a schema we can use with taviewer:
"default" => array (
"name" => "default",
"description" => "Article",
"fields" => array (
"name" => array (
"description" => "URL name",
"datatype" => "text",
"hidden" => TRUE,
"location" => "name"
),
"title" => array (
"description" => "Title",
"datatype" => "text",
"required" => TRUE,
"location" => "title"
),
"abstract" => array (
"description" => "Abstract",
"datatype" => "text",
"location" => "abstract",
"widget_text_inputstyle" => "longtext",
"widget_text_height" => "8em",
),
"content" => array (
"description" => "Text",
"datatype" => "text",
"location" => "content",
"widget" => "html"
),
)
)
<?
Schema definition
name is the schema's identifier used by Datamanager. A schema file, or in MidCOM terms, a "schema database" can contain multiple schemas, and this name is used by Datamanager to identify which object uses which schema.
description is the human-readable name of the particular schema. It is displayed in the content authoring interface as New Article.
Once the schema has been defined the component must be configured to use it.
Schema's field definitions
After the schema's identifying information we describe the data fields that are used for objects managed by the schema. The visible fields will be shown in the editing form.
The field definition contains information on both how the field should be stored, and what kind of user interface is used for editing and rendering it.
"abstract" => array (
"description" => "Abstract",
"datatype" => "text",
"location" => "abstract",
"widget_text_inputstyle" => "longtext",
"widget_text_height" => "8em",
),
A field definition consists of following pieces:
description is the human-readable label of the field. It will be run through the localization system for translation support.
location tells which Midgard object property is used to store the contents of the field. In addition to regular properties of an object, schema can extend the object with two additional locations:
parameter- store the content to a parameter of the objectattachment- store the content to a file attachment of the object
helptext is a human-readable help text that will be shown as a tooltip for the field in the editor.
required tells whether filling the field is required before the form can be saved. It can be either TRUE or FALSE.
hidden tells whether the field is shown in the editor. It can be either TRUE or FALSE.
readonly tells whether the field is editable in the editor. It can be either TRUE or FALSE.
default is the default value used for an empty field.
datatype defines which data type will be used for handling the field. The following data types are available:
- account - Midgard user account username and password
- array - PHP Array storage
- blob - File attachment
- boolean - A boolean
TRUEorFALSE - collection
- communityhtml - Bbcode-formatted content
- image - Image attachment that can be resized by the data type
- integer - PHP integer storage
- mailtemplate - Email template
- markdown - Markdown-formatted HTML to text content
- multiselect - Multiple selection values stored in comma-separated format
- number - PHP float number storage
- text - Regular text content
- unixdate - Date and time storage
Some of the data types provide additional configuration options.
widget defines how the contents managed by the data type are to be rendered in the editor. The widget field is not necessary as all datatypes provide their default setting for it.
Some data types may require specific widgets to be used with them.
- account - Username and password inputs
- blob - File upload dialog
- checkbox - Check box for setting boolean values
- communityhtml - BBcode editor with emoticons
- collection
- date - Calendar pop-up widget for easy date and time selection
- html - The HTMLAREA WYSIWYG editor
- image - Image upload dialog
- multiselect - Multiple selection dialog
- radiobox - Radio button selection list
- select - Selection list
- text - Regular text input
- tinymce - TinyMCE WYSIWYG editor
Some of the widgets provide additional configuration options.
Input validation
Datamanager fields support input validation using the optional HTML_QuickForm PEAR package. If HTML_QuickForm is not installed, possible validation settings of a field will be ignored silently.
To add input validation to a field, set the validation key into the field definition array using the following syntax:
"validation" => array (
'type' => array (
'message' => 'Some message to the user' ,
['format' => 'string',]
['function' => 'functionname']
['object' => 'classname',]
)
)
The variables used follow HTML_QuickForm conventions quite closely. As an example, to check for valid email address in a field, the field definition would look like the following:
"email" => array(
"description" => "Email address",
"location" => "parameter",
"datatype" => "text",
"validation" => array(
"email" => array(
"message" => "Please input a valid email address",
),
),
),
User-defined validation functions can be used by setting the function parameter of the validation array.
More information about input validation can be found from the HTML_QuickForm manual.
Field grouping
Fields in a datamanager schema can be grouped together to form fieldsets. To do this, add the key start_fieldgroup containing a PHP array into the first field definition in the group. The field group start should be in following format:
"start_fieldgroup" => array(
"title" => "Contact information",
"css_group" => "contact",
),
To end the field group, add to the last field in it the key end_fieldgroup containing an empty string:
"end_fieldgroup" => "",
Complex example schema
Here is a complex example schema using most of the datamanager features.
"default" => array (
"name" => "default",
"description" => "Statischer Inhalt",
"locktimeout" => 90,
"lockoverride" => "admin",
"fields" => array (
"name" => array (
"description" => "URL-Name",
"datatype" => "text",
"location" => "name",
"required" => true,
"helptext" => "blah some long text blah some long text blah some long text blah some long text blah some long text blah some long text blah some long text blah some long text blah some long text blah some long text blah some long text blah some long text blah some long text ",
),
"title" => array (
"description" => "Titel",
"datatype" => "text",
"location" => "title",
"required" => true,
"helptext" => "blah",
),
"content" => array (
"description" => "Text",
"datatype" => "text",
"location" => "content",
"widget_text_inputstyle" => "longtext",
"helptext" => "blah",
),
"content_html" => array (
"description" => "Text (HTML)",
"datatype" => "text",
"location" => "abstract",
"helptext" => "blah",
"widget" => "html",
"widget_html_stripmstags" => true,
"widget_html_customconfig" => <<<EOF
config.formatblock = {
"Zwischenüberschrift Ebene 2": "h2",
"Zwischenüberschrift Ebene 3": "h3",
"Normal": "p",
"Vorformatiert": "pre"
};
config.toolbar = [!!
[!! "formatblock", "space",
"bold", "italic", "subscript", "superscript", "separator",
"insertorderedlist", "insertunorderedlist", "separator",
"inserthorizontalrule", "createlink", "insertimage", "inserttable", "htmlmode", "separator",
"popupeditor", "about" ]
];
EOF
),
"image" => array (
"description" => "Bild",
"datatype" => "image",
"widget_image_simple" => true,
"helptext" => "blah",
),
"coll" => array (
"description" => "Downloads",
"datatype" => "collection",
"datatype_blob_anchorprefix" => "http://cvs.devel.midcom-project.org/midcom/",
"helptext" => "blah",
),
"coll2" => array (
"description" => "Downloads2",
"datatype" => "collection",
"datatype_blob_anchorprefix" => "http://cvs.devel.midcom-project.org/midcom/",
"element_datatype" => "image",
"helptext" => "blah",
),
"select-test" => array (
"description" => "Select-Test",
"datatype" => "text",
"location" => "parameter",
"widget" => "select",
"widget_select_choices" => Array ("null", "eins","zwei","drei"),
"helptext" => "blah",
),
"multi-test" => array (
"description" => "Multi-Select-Test",
"datatype" => "multiselect",
"multiselect_selection_list" => Array (
"key 1" => "Schlüsselwert 1",
"key-2" => "Blafaselblubb",
"key_3" => "supertest"
),
"helptext" => "blah",
),
"date-test" => array (
"description" => "Date-Test",
"datatype" => "unixdate",
"date_withtime" => true,
"helptext" => "blah",
),
"text-att-test" => array (
"description" => "Text-att-test",
"datatype" => "text",
"location" => "attachment",
"widget_text_inputstyle" => "longtext",
"helptext" => "blah",
),
"checkbox-test" => array (
"description" => "Checkbox-Test",
"datatype" => "boolean",
"helptext" => "blah",
),
"account"=> array (
"description" => "Account",
"datatype" => "account",
"account_enable_crypt" => true,
"helptext" => "blah",
),
"mailtemplate" => array (
"description" => "Mail Template example",
"datatype" => "mailtemplate",
"helptext" => "blah",
),
"schemapath" => array (
"description" => "Schema Path",
"datatype" => "text",
"helptext" => "blah",
),
"select-schema" => array (
"description" => "Select Schema Test",
"datatype" => "text",
"location" => "parameter",
"widget" => "schemaselect",
"widget_schemaselect_linkto" => "schemapath",
"widget_schemaselect_default_schemapath" => "/de/linkm/taviewer/_config/schemadb_default",
"helptext" => "blah",
),
"select-group-test" => array (
"description" => "Select Group Test",
"datatype" => "text",
"location" => "parameter",
"widget" => "select",
"widget_select_choices" => midcom_helper_datamanager_selectlist_allgroups(),
"helptext" => "blah",
),
),
),