Version 1.0 is released with MMBase 1.6.
This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.
The license (Mozilla version 1.0) can be read at the MMBase site. See http://www.mmbase.org/license
Table of Contents
This reference describes the syntax of the wizards and how to access them using a browser.
This reference describes the wizard pages and how to call them from a html or jsp page.
The editwizards need a xml file with a definition of the wizard to operate. By default, those are found in the subdirectory /editwizard/data/, but it is possible to place your definitions, as well as the wizard stylesheets (which define layout) elsewhere.
When the wizards search for a requested file (a wizard xsl stylesheet or a wizard xml schema), they look for the referenced file in the following order:
You call the editwizard scripts (list.jsp and wizard.jsp) from a page located in another directory than the editwizard home directory. If you do, the wizards keep a reference to the calling page, the 'referrer'. When a xml or xsl file is requested, the wizard first checks whether the file can be found in the directory of the referrer page.
Example: if the file requested is data/my_wizard.xml, and the referencing page is /myeditors/index.jsp, the system first checks for the file /myeditors/data/my_wizard.xml.
The editwizard home is the directory that contains the editwizard basic stylesheets, data library, and jsp pages. It is one directory lower than the location of the list.jsp and wizard.jsp files. In the standard distribution, this location is /mmapps/editwizard/ (the list.jsp and wizard.jsp are located in /mmapps/editwizard/jsp/), but you can place the wizards wherever you like.
Example: if the file requested is data/my_wizard.xml, and the editwizard home is in mmapps/editwizard/, the system checks for the file /mmapps/editwizard/data/my_wizard.xml.
To run a wizard, you'll need to call either list.jsp or wizard.jsp. These scripts are located in the jsp subdirectory of the editwizard home directory. In the standard distribution, this is mmapps/editwizard/jsp/.
List.jsp starts with running a search query on MMBase to create a list of items to search from. It shows a list of all found nodes and allows you to select one of these items to edit, to remove an item, or to add a new item. The actual options given depend on the security settings (if you are allowed to do this by MMBase), and the possibilities offered by the wizard. Note that the list.jsp does NOT run an editwizard itself, it is just a 'starter'. It eventually calls wizard.jsp (see below) to actually edit or create an item.
You need to specify a number of parameters to tell the list.jsp what wizard should be used, and what nodes and fields should be shown in the list.
In addition, by specifying the searchfields parameter, you can let the wizards generate a searchbox, allowing you to narrow the list of nodes to edit.
The following parameters MUST be specified (list.jsp does not work if you do not specify them):
The wizard to use. This is a relative reference to the xml schema file. Do not specify the ".xml" prefix.
wizard=data/simple.xml
The nodepath defines the object types to list. This can be one object type, or a comma-separated list of types, which are treated as a relation chain, like in path attribute of the taglib's <mm:list> tag. The last objecttype listed is the object that is used as the objecttype to edit in the wizard.
nodepath=people or nodepath=people,news
The following parameters MAY be specified:
The fields to show in the list. If you query only one nodetype (see nodepath), you can use simple field names. Otherwise, you need to preface the fieldnames with the name of the objecttype they belong to. If the first field listed is a number field, the objecttype of that field is used as the objecttype to edit in the wizard (instead of the last object type in the nodepath list). This parameter is similar to the fields attribute of the taglib's <mm:list> tag.
In 1.6.3 and lower, field is mandatory. In 1.6.4 and up, if fields is not specified, the wizard uses the default 'list' fields specified by MMBase.
fields=news.title,people.firstname,people.lastname
The directory where xsl templates and editwizard task xml's can be found. Use this to specify an alternate directory for xsl templates and wizard xml's. The other directories (current directory, default directory) remain working too, but this 'templates' is added between them in the resolve path.
templates=data/my_xsl
The name of the main node type in a node path. The main node type designates the element in a list that you want to edit. By default, the wizard takes the last name in a node path as the main node type.
For instance, in the node path 'mags,news,publishtimes', the main node type recognized automatically will be 'publishtimes' - but it is more likely that we desire to edit the news element in this list. In this case, you can point out to the wizard to use the 'news' element of the list instead.
Available from MMBase 1.6.4 and up. Prior to 1.6.4, you can designate the main node type by adding the number field of that node type to the fields parameter (i.e: 'news.number,news.title,publishtimes.date'). This method still works in 1.6.4, but is discouraged as it is confusing.
main=news
A key that identifies the 'session' of this wizard. Normally, you cannot run two separate editwizards concurrently from the same browser. If you want to allow this for your users for some reason, you can provide a 'sessionkey' to identify separate sessions: a wizard with one sessionkey runs independent from those who use a different one. The default session key is 'editwizard'. Note that allowing more wizards to be opened from one browser consumes more resources and is therefor not recommended.
sessionkey=my_key
The security context to assign to new objects and relations created by the editwizard. By default, objects are created using a default context defined by the security system (often depending on the logged on user). By explicitly specifying this default context. Not that specifying a context different from the default may result in objects that, once created, cannot be changed by the user due to security restrictions. A user needs to be able to change the context on objects he creates, or the parameter cause security errors.
context=default
The maximum size of a file to upload. The default maximum size for files is 4MB.
maxsize=8000000
A list of fieldnames used to order the returning list. This parameter is similar to the orderby attribute of the taglib's <mm:list> tag.
orderby=people.lastname,news.title
A list of one or more UP/DOWN keywords. Each keyword determines whether the order of a matching field specified in the orderby parameter is ascending (UP) or descending (DOWN). This parameter is similar to the directions attribute of the taglib's <mm:list> tag.
directions=UP
The direction in which relations between nodemanagers should be followed. This parameter is similar to the searchdirs attribute of the taglib's <mm:listcontainer> tag. It can be a list, in which case the first is for use between the first and second nodemanager, the second is for use between second and third nodemanager. If there are more steps in the nodemanager path then searchdirs, then the searchdir will default to the previous searchdir in the 'searchdirs' list.
Available from MMBase 1.7.0 and up. In MMBase 1.6.4 and up, only the 'searchdir' parameter was available and only one searchdir could be specified, valid for all steps of the nodepath.
searchdirs=source,destination
A SQL-like constraint, used to filter the list. If you use fieldnames in a constraint, surround it with brackets ([]). This allows MMBase to recognize the fields and optimize the query. This parameter is similar to the constraints attribute of the taglib's <mm:list> tag.
constraints=[news.title] like '%Brasil%'
If true, double entries in a list are returned only once.
distinct=true
The preferred language for display. The language is specified by the ISO standardized 2-letter lowercase languagecode. The effects are dependent on whether alterenate langauge elemenst are availabel for the specified language. If not, the default language settings are used instead.
language=nl
The maximum number of entries shown on one list page. Default value is 50.
pagelength=50
The maximum number of pages available to browse through. Default value is 10.
maxpagecount=10
The number of the item in the list where to start listing. This value is used to skip to a certain page when browsing a large list. Default is 0.
start=0
The maximum age (in days) of the objects to list. Default is no age restriction.
age=31
The field(s) on which to make a search, using the value specified in the search parameter and the type of comparison specified in the search type.
You can specify more than one field (separated by commas). if you do, a search matches if one or more of the specified fields matches.
If the search parameter (see below) is set to AUTO, specifying this parameter will create a searchbox at the top of the list, allowing you to enter the value to search for. If a search box is forced by the search parameter but the searchfields are not specified, the default is to search on the fields being displayed (specified in the fields parameter)
searchfields=news.title,news.subtitle
The actual field on which to search. Normally, searches are done on the fields mentioned in the searchfields parameter (used to create the search box in a list page). Sometimes, you want to search on a field other than those listed in searchfield (such as 'number' or 'owner'). In that case, use this parameter to specify the field.
This parameter is set by the system when a user submits a search- you will hardly ever use it yourself. If you want to add additional constraints, use the 'constraints' parameter. If you specify a constraints parameter, that constraint is combined in further searches with the search parameters given by a user. If you use realsearchfield to specify a constraint, that information is only valid for the first search - it will be replaced when a user submits his search.
Available from MMBase 1.6.4 and up
realsearchfield=news.title,news.subtitle
The term or value to search for. This is only valid if you also specify the searchfields parameter.
searchvalue=Brasil
Determines what type of search is used to filter on the searchfields, using the specified search value. This is only valid if you also specify the searchfields parameter.
Allowed values are 'string', 'like', 'equalto', 'greaterthan', 'lessthan', 'notgreaterthan', and 'notlessthan'. use 'string' to compare the search value to the field using an exact match. Use 'like' to make a pattern search using the specified searchvalue. Use the other values to compare the field to numeric values or dates. I.e. using 'greaterthan' selects all fields whose (numeric) value is greater than the specified (numeric) value.
searchtype=like
The search parameter specified when the list should show a search box, and whether searching is mandatory. There are four possible values:
no turns searching off. If other parameters such as searchfields and searchvalue are given, the search is performed using those parameters but a searchbox is not displayed.
yes turns searching on, displaying a searchbox on top of the list, using defaults for parameters such as searchfields, if these are not specified.
force is like YES, but searching (and showing a resultlist) is not performed until a searchvalue is specified. If no searchvalue is given, only the searchbox is displayed - no results are shown.
auto makes searching dependent on the presence of the searchfields parameter. If the searchfields parameter is given, a searchbox is shown. Otherwise, it is not. AUTO is the default value
Available from MMBase 1.6.4 and up
search=yes
A node alias or number, which will be passed to the underlying editwizard. the value can then be referenced in the editwizard schema using the {$origin} variable. This can be used to create relations to nodes whose 'origin' is determined outside the wizard (i.e. in a complex search or determined through user preferences).
origin=my_start_node
An optional title to use by the list. In general, you should specify this in the editwizard schema.
title=News of The Week
System parameter, see the description at the wizard.jsp reference page for more info
System parameter, see the description at the wizard.jsp reference page for more info
System parameter, see the description at the wizard.jsp reference page for more info
If this option is given, then you can besides searching in the given list, also search in the complete cloud. This can be useful if the presented list has an orgin. In this way you can add new entries to this list, without needing a wizard.
relationOriginNode=<origin>[&relationRole=<role>][&relationCreateDir=<dir>]
Where <origin> it the nodenumber to which a relation must be created, <role> is the role of that relation.
(See also: the <action type="unlink" />
Available from MMBase 1.8.5 and up
Example 1. How to use list.jsp to list objects
list.jsp?wizard=practice/people&nodepath=people&fields=firstname,lastname
list.jsp?wizard=practice/simple&startnodes=1&nodepath=people,news&fields=news.title,people.firstname,people.lastname
You can use wizard.jsp to directly start a wizard. Like list.jsp, you will need to supply the correct parameters in order to let the wizard run correctly. If you call the wizard.jsp page, a wizard will be loaded and started. The proper html will be rendered and shown in the browser. The syntax of wizard.jsp to create a new object looks like this:
wizard.jsp?wizard=practice/simple&objectnumber=new
To create a wizard and use an existing mmbase object as source:
wizard.jsp?wizard=practice/simple&objectnumber=[objectnumber]
The following parameters MUST be specified (wizard.jsp does not work if you do not specify them):
The wizard to use. This is a relative reference to the xml schema file. Do not specify the ".xml" prefix.
wizard=data/simple.xml
The number or alias of the object to edit. The object must exist. You can also supply the keyword 'new', which creates a new object instead of editing an existing one.
The following parameters MAY be specified:
A directory where xsl templates and wizard xml could be found. See also the description of the same parameter for list.jsp
templates=data/my_xsl
A key that identifies the 'session' of this wizard. Normally, you cannot run two separate editwizards concurrently from the same browser. If you want to allow this for your users for some reason, you can provide a 'sessionkey' to identify separate sessions: a wizard with one sessionkey runs independent from those who use a different one. The default session key is 'editwizard'. Note that allowing more wizards to be opened from one browser consumes more resources and is therefor not recommended.
sessionkey=my_key
The security context to assign to new objects and relations created by the editwizard. By default, objects are created using a default context defined by the security system (often depending on the logged on user). By explicitly specifying this default context. Not that specifying a context different from the default may result in objects that, once created, cannot be changed by the user due to security restrictions. A user needs to be able to change the context on objects he creates, or the parameter cause security errors.
context=default
The preferred language for display. The language is specified by the ISO standardized 2-letter lowercase languagecode. The effects are dependent on whether alterenate langauge elemenst are availabel for the specified language. If not, the default language settings are used instead.
language=nl
If debug=true, the wizard will place additional information in the wizard page that allows for debugging of the application. This includes a link to a debug page that allows you to view the loaded object data and the wizard schema. This link specifies parameters such as sessionkey and popupid as required.
debug=true
The maximum size of a file to upload. The default maximum size for files is 4MB.
maxsize=8000000
A node alias or number. This value can be referenced in the editwizard schema using the {$origin} variable. This can be used to create relations to nodes whose 'origin' is determined outside the wizard (i.e. in a complex search or determined through user preferences).
origin=my_start_node
This parameter is passed by the system, you never pass it yourself. It is used to identify a 'popup' wizard. A popup wizard is a sub-wizard for the main wizard that, unlike an 'inline' sub-wizard, opens in a separate browser window. Because of this, it needs to separately maintain its status (identified by the popupid). Once the task of a popup wizard ends, it's window is closed, and the parent wizard is refreshed.
You never pass this parameter by hand. They are provided by the <command name="startwizard"> and <field ftype="startwizard"> tags in a wizard schema. However, you might need to pass the parameter in links if you override xsl stylesheets, and if you want to use the debug.jsp page to view a popup wizard's debug data, you need to know the value of this parameter.
popupid=my_id
This is a parameter passed by the system. It is used to indicate that the current wizard is still being processed, and therefor its data (stored in the user's session) should be kept an re-used by this call. Omitting this parameter (or passing it with the value false) causes all processed data to be removed, and replaced by a new wizard.
You never pass this parameter by hand, but you might need to pass it in links in overriding xsl stylesheets.
popupid=my_id
System parameter
You never pass this parameter by hand. It is used to by the wizard to pass state information.
System parameter
You never pass this parameter by hand. It is used to by the wizard to pass state information.
Example 2. How to use wizard.jsp to start an editwizard
wizard.jsp?wizard=practice/simple&objectnumber=184
wizard.jsp?wizard=practice/simple&objectnumber=new
When you are debugging your wizard code, it can be useful to know what data is read and parsed by the wizard. The debug.jsp page gives access to three xml trees that are used by the current running wizard.
The data tree shows the xml that contains the data used by the wizard, including any changes made by the user. It can be useful to see if data is loaded (or changed) as expected. It can also be useful to determine xpaths when you plan to use these in your wizard: if you use an xpath in your wizard xml file, it access the data xml.
The wizard lists the fully expanded wizard schema file (including any inclusions and extensions). Note that this xml also contains some additional navigational information related to the current form, and does not fully follow the wizard dtd.
The wizard-schema combines the data and wizard xmlks into one xml tree. This tree is what is passed to the xsl-transformers, and is used to create the form that is sent to the end-user. Use this form to see if data loaded is actually used, and if you want to override the default xsl files.
The following parameters MAY be specified:
A key that identifies the 'session' of this wizard. See the wizard.jsp for more information.
sessionkey=my_key
Specify this parameter to view a popup wizard's debug data (instead of the data displayed by the main wizard). See the popupid of the wizard.jsp for more info.
popupid=my_id
TODO
object (inside action type="create")
<object type="[buildername]" />
Inside a create-action, you can place an object-node to define what should be created within mmbase if the create-action is performed. With this node, you can define what object should be created, what values should be placed in what fields, and you can define possible new relations that should be created.
type="[buildername]"
See needed attributes.
None
<relation /> If a relation node is placed inside an objectnode, a relation is created relating the object defined by the <object /> node and some other object (eg.: another to-be created object or an existing one.)
<field /> In the field nodes inside the object nodes, the user can define the defaultvalues of the designated fields. Eg.: <field name="firstname">Enter your firstname</field>
<action type="create" />
<object type="news">
<relation destination="13234" role="related" />
<relation role="posrel">
<field name="pos">42</field>
<object type="images">
<field name="title">new image</field>
</object>
</relation>
</object>
relation (inside action type="create")
<relation />
Usually, the relation is placed inside an object-node (inside a create-action), or it will be placed directly inside a create-action. With this node, the user can make relations between two newly created objects, or, create a relation between one newly created object and an already existing object.
None
destinationtype="[buildername]" This attribute is not used anymore. Forget it I'd say.
destination="[objectnumber or alias]" Use this attribute to point the relation to an already existing object in the mmbase cloud.
role="[relationname]" Use this attribute to define what kind of relation should be created. If omitted, the default InsRel relation is used. Best practice is to always define the role, eg.: "related" or "posrel" etc.
None
<object /> (see also: object)
<field /> Default values of fields of a relation itself can be set also. Eg.: <field name="pos">-1</field>
<action type="create" />
<object />
(See also: the <action type="create" /> example and the <object /> example.
field (general)
<field />
Field nodes define what form-elements will be placed in the wizard. This fieldnodes in the xml are an important part of the wizard's definition. For detailed information on what fieldtypes need what kind of settings, see the other fielddefinitions in the reference. Note: the field nodes that can be placed inside a relation or object node have different syntax! (See also: <object type="create" />)
name="[fieldname]" fdatapath, ftype, dttype, dtrequired, dtminlength, dtmaxlength are automatically retrieved from mmbase. Overriding is always possible, however.
or (advanced users:) fdatapath="[xpath]" and ftype="[fieldtype]"
ftype="[fieldtype]" (line|text|enum|date|int)
dttype="[datatype]" (string|int|date|datetime|time|html)
dtminlength="[minlength]"
dtmaxlength="[maxlength]"
dtrequired="[true|false]"
rows="[rowcount]"
None
<prompt /> For every field, a prompt-text can be given. If defined, the prompt text will be visible in front of the field in the wizard.
<description /> For every field, a description can be given. If defined, the description will be shown "onmouseover". If the user move the mouse over the field, the description will be shown in a hint.
<form-schema />
<item />
<form-schema id="step1">
<title>Example form</title>
<field name="title" dtminlength="1" ftype="line">
<prompt>News Title</prompt>
<description>You can enter the news-title here</description>
</field>
</form-schema>
field ftype="line"
<field ftype="line" />
A line-field will show a single-line inputfield in the wizard. Use them for simple text entry.
None
dttype="string"
dttype="int"
dtminlength="[minlength]"
dtmaxlength="[maxlength]"
dtrequired="[true|false]"
None
see field (general)
see field (general)
<field name="title" dtminlength="1">
<prompt>Title</prompt>
</field>
field ftype="int"
<field ftype="int" />
Use this field for number editing
None
dtmin="[minvalue]"
dtmax="[maxvalue]"
dtrequired="[true|false]"
None
see field (general)
see field (general)
<field name="score" dtmin="100" dtmax="5000" dtrequired="true"> <
<prompt>Enter position</prompt>
<description>Enter value between 100 and 5000 please.</description>
</field>
field ftype="date"
<field ftype="date" />
Use this field to edit date, date-time, or time fields.
None
dtmin="[mindate]"
dtmax="[mindate]"
dttype="[date|datetime|time]"
None
see field (general)
see field (general)
<field name="start" dttype="date">
<prompt>Startdate</prompt>
</field>
field ftype="upload"
<field ftype="upload" />
Use this field to process uploads. Note: Make sure that you use this field in the right context: Usually, this field will store it's binary-value in a mmbase field named 'handle'. See the upload example for more info.
None
None
see field (general)
see field (general)
see field (general)
<wizard-schema>
<title>Image Upload</title>
<action type="create">
<object type="images" />
</action>
<action type="load">
<field name="title" />
<field name="description" />
</action>
<form-schema id="step1">
<title>Image upload</title>
<field name="title">
<prompt>Title</prompt>
</field>
<field name="description" ftype="text" rows="8">
<prompt>Description</prompt>
</field>
<field name="handle" ftype="image" dttype="binary">
<prompt>upload</prompt>
</field>
</form-schema>
</wizard-schema>
field ftype="startwizard"
<field ftype="startwizard">
Use this field to start one wizard, from inside another wizard.
objectnumber="{object/@number}"
wizardname="[ name of the wizard ]"
inline="[true|false]" an inline startwizard will replace the current wizard to create the new object and come back when ready, a not-inline startwizard will pop-up a window to create the new object .
None.
None.
<item />
<command name="startwizard" inline="false" wizardname="tasks/myurls" objectnumber="new"/> <command name="startwizard" inline="true" wizardname="tasks/myurls" objectnumber="new"/>
field ftype="data"
<field ftype="data" />
Use this field to show values, but don't make it editable. In other words: use this to make a read-only field.
None
see field (general)
None
see field (general)
None
<field name="firstname" ftype="data">
<prompt>Your firstname is:</prompt>
</field>
field ftype="enum"
<field ftype="enum" />
Use this field to make a "dropdown" inputfield. (In HTML-terms: a selectbox).
None
None
<optionlist /> Use this node to define the possible options for the field. (see also: optionlist)
see field (general)
see field (general)
<lists>
<optionlist name="articletypes">
<option id="1">News</option>
<option id="2">Interview</option>
<option id="3">Information</option>
</optionlist>
</lists>
...and then use it like this.
<field name="type" ftype="enum">
<prompt>Articletype</prompt>
<optionlist select="articletypes"/>
</field>
lists
<lists />
Use this node to define optionlists in a wizard.
None
None.
<optionlist /> (see also:optionlist)
See needed childnodes
<wizard-schema />
<lists>
<optionlist name="priorities">
<option id="1">Low</option>
<option id="2">High</option>
</optionlist>
</lists>
optionlist
<optionlist />
Use this node to define an optionlist. It can be either a static list of options, or a list filled using an MMBase query.
None
name="[optionlistname]" This optional attribute can be used if an optionlist is defined in a <lists /> node. To reference to the defined optionlist, you will need the optionlistname. Eg.: <optionlist select="earlier_defined_optionlist" />
optionid="field[@name='fieldname']" This optional attribute can be used if an underlying 'query' node is present. Of all matching nodes, the field with name given in 'optionid' will be used as the 'id' part of the option.
optioncontent="field[@name='fieldname']" This optional attribute can be used if an underlying 'query' node is present. Of all matching nodes, the field with name given in 'optioncontent' will be used as the content part of the option.
<option id="[optionid]">[optionvalue_to_be_shown_in_wizard]</option>
<query> This childnode can be used instead of <option> childnodes to fill the optionlist with options. The query has three attributes: optional 'where' and 'orderby' clauses and a required 'xpath' clause. The xpath can have the following syntax:
/*@buildername, in this case a nodequery will be performed.
/*@buildername,otherbuildername,..., in this case a multilevel query will be performed. When doing a multilevel query, there must be a <object> childnode with two <field> childnodes for the 'optionid' and 'optioncontent' arguments of the optionlist.
<wizard-schema />
<field ftype="enum" />
<optionlist name="role"
optionid="field[@name='role.role']"
optioncontent="field[@name='role.name']">
<query xpath="/*@companies,roles" where="company.number = {$origin}">
<object>
<field name="role.role" />
<field name="role.name" />
</object>
</query>
</optionlist>command (name="search")
<command name="search" />
Use this command inside a list node to define how a user can search for objects and add them to a list.
See for detailed information how to use nodepath, startnodes, fields, constraints, orderby the documentation of the MMBase taglib.
name="search"
nodepath="[buildername_to_start_with]"
fields="[fieldnames of fields to show]"
startnodes="[objectnumber]"
age="[default age to show in search-field]" use -1 to set it to "any age", use 1,7,31,365 for day, week, month, year ages.
constraints="[mmbase where part]"
None
<prompt /> Place the text to be shown in front of the searchfield here.
<search-filter /> Defines what extra searchfields should be shown and used in the query. See also: search-filter.
<list />
<list destination="people" minoccurs="0" maxoccurs="*">
<command name="search" nodepath="people" fields="firstname,lastname" orderby="lastname" age="-1">
<prompt>#Search command prompt</prompt>
<search-filter>
<name>firstname contains</name>
<search-fields>firstname</search-fields>
</search-filter>
<search-filter>
<name>lastname contains</name>
<search-fields>lastname</search-fields>
</search-filter>
</command>
<item>
<field name="firstname" >
<prompt>Field prompt</prompt>
<description>Field Description</description>
</field>
</item>
<action type="create">
<relation destinationtype="people" role="related" />
</action>
</list>
search-filter
<search-filter />
Use the searchfilter to allow the user to fire a free-text query from the wizard. See the command name="search" example.
None
None
<name />
<search-fields />
None
<command name="search" />
<search-filter>
<name>Naam bevat</name>
<search-fields>name</search-fields>
</search-filter>
This is part of the MMBase documentation.
For questions and remarks about this documentation mail to: documentation@mmbase.org