As you can see, you can define a email address where the data should be sent to and a thank you text to be shown when a user submitted the form. What follows are the various fields to fill in.
==== Field definitions ====
* Fields are defined by giving a type and a label.
* For ''fieldset''s and the ''submit'' button, the label is optional.
* Some fields, like the ''select'' type, need a third parameter.
* Additional constraints can be added after the main options.
* Arguments need to be wrapped in double quotes when they contain spaces e.g. ''%%"S p a c e s"%%''
* Including a ''%%"%%'' by using ''%%""%%'' e.g. ''%%"With ""quotes"" in the string"%%''
The plugin takes care of validating the form, the field types, and set constraints.
==== Fields ====
* **action**
* The first parameter needs to be a supported action (see [[#action modes|below]]).\\ Currently supported are ''mail'', ''template'', ''script''.\\ Or if respective plugin is installed: ''[[plugin:pagemod|pagemod]]'' or ''[[plugin:struct:bureaucracy#action_struct_lookup|struct_lookup]]''.
* Additional parameters for type ''mail'':
* one or more email addresses to send the data to (required)
* Additional parameters for type ''template'':
* name of a page or namespace (trailing colon) to use as template or a single underscore ''_'' to try and use the target namespace template (use an absolute path) (required)
* namespace:prefix or namespace: (mind the trailing colon) where new pages shall be created (optional)
* separator to use when combining multiple fields into the pagename (optional)
* Additional parameters for type ''script'':
* the name of the script-file in the ''conf/plugin/bureaucracy/'' directory
* Multiple actions can be defined by adding another action field
* **thanks**
* define a text to be displayed when the form was submitted. (optional)
* **fieldset**
* creates a new set of fields
* a label is optional
* Can be shown/hidden depending on the value of another field above it (see [[#dependencies_with_fieldsets|below]])
* Switching depends on the field given as second parameter (optional)
* Fieldset is displayed as that field is set\\ or has an exact match with the value given as third parameter (optional)
* **static**
* adds some static text to the form
* **wiki**
* similar to static, but parses the input as Wiki syntax
* should be used sparsely as it is computationally expensive
* **textbox**
* creates a single line input field
* needs a label
* **password**
* creates a single line password input field
* needs a label
* **email**
* creates a single line input field
* needs a label
* the input is validated to be a valid email address
* argument ''@@'' marks emailadress as Reply-To address for mail action
* **[[#number_field|number]]**
* creates a single line input field
* needs a label
* the input is validated to be numeric
* can be pre-filled with auto-incrementing number, see [[#number_field|example]].
* **textarea**
* creates a multi-line input field
* needs a label
* to change the default size of 10 rows to **//N//** rows, use the argument x**//N//** ('' x23 '') (optional)
* **[[#checkbox_field|yesno]]**
* creates a checkbox
* needs a label
* needs default values for yes and no (''%% "=true value" "!false value" %%''). If only used for a fieldset the default values are not required.
* **select**
* creates a dropdown list
* needs a label
* needs a second argument containing the select options separated by a pipe ''|'' char\\ (''%% "Peaches|Apples|Oranges" %%'')
* **multiselect**
* you can select multiple values
* needs a label
* needs a second argument containing the select options separated by a pipe ''|'' char\\ (''%% "Peaches|Apples|Oranges" %%'')
* example: ''%% multiselect "Label" "Opt1|Opt2|Opt3" =Opt1,Opt3 %%''
* In mail action: all options will be joined by "'', ''" in e-mail message
* In template action:
* if field is marked with "@" all selected options will be joined with page separator
* during template substitution all options will be joined by "'', ''" or you can provide optional separator: ''@@Label(separator)@@''
* **radio**
* creates a set of radiobuttons
* needs a label
* needs a second argument containing the radio options separated by a pipe ''|'' char\\ (''%% "Peaches|Apples|Oranges" %%'')
* **hidden**
* creates an invisible field with static data
* needs a label
* needs a default value parameter (''%% "=some value" %%'')
* **hiddenautoinc**
* needs a label
* creates an invisible field with a number that increases by 1 on each form submit
* **submit**
* creates a submit button (required)
* a button label is optional
* **user / users**
* a DokuWiki user or list of DokuWiki users
* needs a label
* provides autocompletion
* **date**
* a date in the format YYYY-MM-DD
* needs a label
* provides a date picker
* **time**
* a time in the format (H)H:MM(:SS)
* needs a label
* **usemailtemplate** template_id
* the content of the ''%%..%%'' and ''%%..%%'' at the template page is used in the email of the mail action, instead of default table with field values.
* template_id is absolute or relative pageid. If relative, it is solved against the pageid of the form
* **addpage** page_tpl page_tgt
* adds another page ''page_tgt'' based on a template page ''page_tpl''
* only for use with the template action
* if page_tpl is absolute or relative pageid. If relative, it is solved against the pageid of the form
* page_tgt is relative to destination of page created by action field. e.g. action field tries to create ''new:destination'', then addpage will try to add ''new:destination:page_tgt''
* When in the ''action'' field a ''!'' is given as template, that template is skipped and only template(s) added by ''addpage'' are used.
* **labels**
* parameter is a wiki page containing a list of label translations
* **file**
* let user select a file for upload (which is added to media by template action, or added as attachment in mail action)
* needs a label
* an optional addition parameter specifies the namespace to which the upload should go to. ''.'' and ''..'' can be used to reference namespaces relative to the new page. Defaults to ''.''
* **data_aliastextbox** (needs plugin)
* requires [[Data|Data plugin]] to display the field (See [[data#bureaucracy_plugin_and_type_aliases|example]])
* needs a label
* an additional parameter is starting by underscore ''_'' for type of field, using dataplugin type syntax
* datatypes with a type alias that defines 'valid values' will appear as a (multi)select field
* otherwise it appears as usual textbox, sometimes with [[data#custom_entry_editor|added features]] as datepicker and pagesuggestions
* **struct_field** + **struct_fieldhidden** (needs plugin)
* Just specify a field from a defined schema "
The translation page needs to contain a single wiki list with items named ''label = translation'':
* field = Tell us about yourself
* name = Your Name
* age = Your Age
* submit = Send your Data
The above would result in the following form:
{{ :plugin:bureaucracy_labels.png?nolink |}}
|**Note:** double slashes ''%%//%%'' cannot be used in the translation field on the translation page --- [[user>SFITCS]] //2016-12-15 22:27//|
==== Dependencies with Fieldsets ====
Sometimes part of a form should only be asked when a certain answer was picked for a previous question. Simple dependencies like that can be created by using Fieldsets.
Consider the following example:
In this example, a user can select to order a car or a blimp. Depending on his choice, the second or third fieldset will be hidden or shown accordingly. The second parameter for the ''fieldset'' field references a previously defined field and the third parameter the value that field shall have to display the fieldset. Only exact matches are supported here, so best combine this feature with a ''select'' field as shown above.
When the user marks the checkbox of the ''yesno'' field in the fourth fieldset the fifth fieldset is shown, so the correct details can be noted. Here is no third parameter given to the fieldset, because it will check if the referred yesno field is set (It will not look for the default values eventually set by "=Value" "!Not Value". If you need the value of the yesno in a template, you have to provide the default values explicitly.).
NOTE:
* Apparently dependencies don't work when the choice is provided by "radio" (only "select" and "yesno" work) for some reason. There might by a logical explanation for this, maybe.
===Dependencies with Fieldsets - creating two levels of selects ===
How to use dependencies to adapt a select list. Example:
First level "select" list
select "Vehicule" "Car|Motorbike"
Second level "select" lists:
fieldset "Car spareparts" "Vehicule" "Car"
select "Sparepart1" "4 wheels|steering wheel"
and
fieldset "Motorbike spareparts" "Vehicule" "Motorbike"
select "Sparepart2" "3 wheels|handle bar"
To show only the shown value of both select fields "Sparepart1" and "Sparepart2" in a template, use the construct @@Sparepart1|@@@@Sparepart2|@@
The chosen one will be filled out and the not chosen one will be replaced by an empty string ("").
==== Prefilling fields from Links ====
Sometimes you may want to link to a bureaucracy form and pre-fill one or more fields. This can be easily achieved by adding parameters to your link using ''@''-wrapped field names.
Imagining the form given in the previous section is on a page called ''orderform''. Here is how you could link to a form for ordering Hot Air blimps:
[[orderform?@What do you want@=Blimp&@Filling@=Hot Air|Order a Hot Air Blimp!]]
===== Action Modes =====
Bureaucracy does three things:
- it displays a neat form
- it validates user input
- it sends the user's input to an action mode
The last step is where the data is processed. The action to use is defined in the ''action'' field, as described above. Currently three modes are supported: ''mail'', ''template'', and ''script''. Additional modes (e.g. to store the data in a database) can easily be added.
==== Mail Mode ====
This is a simple action. When used default, all user input will be sent by email to the configured email address. See the example above how to use it. You may specify multiple recipient mail addresses separated by commas.
//Example to automate email to an address which the user enters://
Fieldset "Some Information"
Textbox "Employee Name"
email Email_Address
Action mail @@email_address@@
* If you add the field ''usemailtemplate'' you can define alternative content for the email. The template should contain two code blocks with text and html version of the message. Other text on the page is ignored. In the template you can use [[#Creating Templates|placeholders]].
* With the ''subject'' field you can replace the default subject
* and by marking field(s) with the option ''@@'' you add Reply-To address(es) to the mail.
//Example://
action mail @MAIL@ forename@surname.name
usemailtemplate your:template
subject "new special subject"
Dear @@Your Name@@,
You are great, you just purchased our @@What do you want@@!
We will deliver it fast as possible, see the
conditions.
Kind regards,
Future Machines company
Dear @@Your Name@@,
You are great, you just purchased our @@What do you want@@!
We will deliver it fast as possible, see [1].
Kind regards,
Future Machines company
[1] http://example.com/conditions
This would create a new page using the continent and name fields. Eg. if I fill in "Europe" and "Andi" for those fields, the resulting page would be ''users:europe:andi''.
**Method 2** Sometimes you want some more control over the resulting pagename(s). This can be achieved by using placeholders in the destination parameter and omitting the ''@'' marker in the field definitions.
Placeholders are the field names surrounded by ''@@'' characters. Additionally any [[phpfn>strftime]] parameters can be used. Let's have another example:
The above would create a namespace based on the current year and my name and create a start page within it: ''users:2012:andi:start''
**Method 3** When working with [[#Dependencies with Fieldsets]] you might want to add additional pages when a fieldset is shown, but skip the page when the fieldset is hidden. This can be achieved with the special ''addpage'' field.
Just put it in the fieldset of question:
addpage additionaltpl somepage
The second fieldset from the example above adds a publication page, via a checkbox. Here the template for additional page is located on absolute path: ''users:publicationtemplate''.
Only when the ''yesno'' field is checked, the additional page is created on ''users:2012:andy:start:publications''
=== Creating Templates ===
The templates need to contain the same fields as your form, and some other placeholders are available too. Some of them can be used as default values for form fields:
^Placeholder ^ action ^
| ''@@Field label@@''\\ ''##Field label##'' | Will be replaced by the actual values the user filled into\\ the form. |
|''@curNS(arg)@''\\ ''@getNS(arg)@''\\ ''@noNS(arg)@''\\ ''@p_get_first_heading(arg)@''|Will be replaced with a result of the corresponding dokuwiki function. ''arg'' can be both a static value, eg. ''@curNS(some:test:value)@'' or the placeholder of a field, eg. ''@p_get_first_heading(@@field@@)@''.|
| ''@@Field label|Nice alternative@@'' | For empty field the text ''Nice alternative'' is shown |
|''@NSBASE@'' | (only template action) Namespace that contains new page.\\ eg. if the new page is ''foo:bar:baz:bang'', ''@NSBASE@'' will contain ''baz'' |
| %Y %F %a %Y-%m-%d %s... etc | [[phpfn>strftime]] parameters to refer to current time |
|
====== @@What's your Name?@@ ======
I'm living in @@What's your Continent?@@. I'm a user since %Y-%m-%d.
@@Enter a short bio|FIXME please fill in your biography@@
The result then would look somewhat like this with all the user data filled in:
====== Andreas Gohr ======
I'm living in Europe. I'm a user since 2007-12-23.
It's me :-)
=== ACL Checking & runas Option ===
By default this plugin will check for [[:ACLs]] in template mode using the permissions of the user filling the form. This means the user needs to have at least ''read'' permissions for the template and ''create'' permissions for the namespace where the new page should be saved.
However sometimes you may want to give anonymous users a way to create pages in a restricted namespace without giving them any direct access. This is where the ''runas'' option comes into play. With this option you can specify a username in the [[config|config manager]]. The user you specify here will always be used for checking the permissions mentioned above, regardless of the user filling the form. This way you can specify the needed access for this particular virtual user in the [[acl|ACL manager]].
Note: the ''runas'' user does not need to exist. In fact it is recommended to use a non existing user. Even when it exists, permission checks are done on user level only, groups of the user will be ignored.
=== Accessing user field infos ===
When using a ''user'' or ''users'' field, additional data of the selected users can be used in the template:
* '@@user.name@@' replaced by user full name
* '@@user.mail@@' replaced by user e-mail address
* '@@user.grps@@' replaced by user grps, comma separated
* '@@user.grps(separator)@@' replaced by user groups, separated by 'separator'
* '@@users(separator)@@' - replaced by list of user's nicks, separated by 'separator'
* '@@users(separator).name' - replaced by list of user's full names, separated by 'separator'
* '@@users(separator).mail' - replaced by list of user's emails, separated by 'separator'
* separator may be omitted then the comma is used as a separator. Eg. @@users.mail@@, @@users.name@@
* @@users.grps@@ is not supported
==== Script Mode ====
This action gives the data to a PHP script supplied by the administrator. The script then can do whatever it wants with the data.
The script must be placed in ''conf/plugin/bureaucracy/'' directory. It must contain one class that is named ''helper_plugin_bureaucracy_handler_//scriptname//'' and implements the interface ''[[https://github.com/splitbrain/dokuwiki-plugin-bureaucracy/blob/master/interfaces/bureaucracy_handler_interface.php|dokuwiki\plugin\bureaucracy\interfaces\bureaucracy_handler_interface]]''
That means the class has to have the ''handleData($fields, $thanks)'' method with the fields and the thanks-message as parameters. It returns a thanks-message on success or ''false'' on error.
=== Example ===
This is a simple script handler that will just print the form's arguments in DokuWiki's debug log.
$data = array(
'fields' => &array(), // the fields initialized so far - add yours here
'args' => array() // the tokenized line, args[0] should be your plugin
);
In your handler you need to check that args[0] is the field type you want to register. If it is, you need to call ''preventDefault()'' and add your own field(s) to the ''fields'' array. The added field has to be a descendant of ''helper_plugin_bureaucracy_field''!
==== Adding a new action ====
To add a new action create a new [[devel:helper_plugins|Helper Plugin]] inheriting from ''helper_plugin_bureaucracy_action''. This works similar to adding a new field described above.
Theres is also an Event you can hook called ''PLUGIN_BUREAUCRACY_ACTION_UNKNOWN''. Again, there's only a preventable ''BEFORE'' event.
FIXME describe passed data in detail. For now check the source.
==== Influence Template mode ====
Saving the final page in template mode triggers an event called ''PLUGIN_BUREAUCRACY_TEMPLATE_SAVE''. In the before mode you can prevent saving the page or modify it's content. The after event is triggered after a page has been created.
Passed data:
$data = array(
'patterns' => &array(), // list of PREG patterns to be replaced
'values' => &array(), // values for the above patterns
'id' => string, // ID of the page being written
'template' => &string, // the loaded template text
'form' => string, // the page the bureaucracy form was on
'fields' => helper_plugin_bureaucracy_field[], // all the fields of the form
);
==== Hook into email action ====
The event ''PLUGIN_BUREAUCRACY_EMAIL_SEND'' gives developers of other plugins access to the submitted form data before it is actually sent in the ''actionmail.php''.
This makes it easier to provide custom fields in bureaucracy emails.
The event data includes the form fields info and all the values, so they can be processed by third-party plugins:
$evdata = [
'fields' => $fields,
'values' => &$this->values
];
===== Customisations =====
**Important!** These are //hacks// - there is no guarantee they'll always work, and they will **not** survive updates.
If it breaks you get to keep the pieces. :-)
==== Customise the Date Format ====
**NOTE:** The configuration setting for the PHP strftime function in ''/conf/dokuwiki.php'' also need to be changed (can also be changed via **Admin->Configuration**) $conf['dformat'] = '%d/%m/%Y %H:%M';
To change the default date format from ''yy-mm-dd'' to ''dd-mm-yy'' (e.g. for Australia)
Change the jQuery datepicker format ''/plugins/bureaucracy/script/datepicker.js'' from:-
/**
* Init datepicker for all date fields
*/
jQuery(function(){
jQuery('.bureaucracy__plugin .datepicker').datepicker({
dateFormat: "yy-mm-dd",
changeMonth: true,
changeYear: true
});
});
to this:-
/**
* Init datepicker for all date fields
*/
jQuery(function(){
jQuery('.bureaucracy__plugin .datepicker').datepicker({
dateFormat: "dd-mm-yy",
changeMonth: true,
changeYear: true
});
});
Change the Bureaucracy error message in ''/bureaucracy/lang/en/lang.php'' from:-
$lang['e_date'] = '"%s" needs to be a valid date in the format yyyy-mm-dd.';
to this:-
$lang['e_date'] = '"%s" needs to be a valid date in the format dd-mm-yyyy.';
Change the Bureaucracy date validation in ''/bureaucracy/helper/fielddate.php'' from:-
* Validate field input
*
* @throws Exception when empty or wrong date format
*/
protected function _validate() {
parent::_validate();
$value = $this->getParam('value');
if (!is_null($value) && !preg_match('/^\d{4}-\d{2}-\d{2}$/', $value)) {
throw new Exception(sprintf($this->getLang('e_date'),hsc($this->getParam('display'))));
}
}
}
to this:-
* Validate field input
*
* @throws Exception when empty or wrong date format
*/
protected function _validate() {
parent::_validate();
$value = $this->getParam('value');
if (!is_null($value) && !preg_match('/^\d{2}-\d{2}-\d{4}$/', $value)) {
throw new Exception(sprintf($this->getLang('e_date'),hsc($this->getParam('display'))));
}
}
}
As of release 2016-03-11 it is also necessary to change this:-
if(preg_match('/^(\d\d\d\d)-(\d\d?)-(\d\d?)$/', $value, $m)) {
to this:-
if(preg_match('/^(\d\d?)-(\d\d?)-(\d\d\d\d)$/', $value, $m)) {
--- [[user>SFITCS]] //2016-11-26 01:16//
**Now packaged as a plugin** - [[plugin:bureaucracy-au]] --- [[user>SFITCS]] //2017-03-10 08:23//
====Customise the Thankyou message=====
To allow inserting DokuWiki code into the Thankyou field.
Change the syntax in ''bureaucracy/syntax.php'' from:-
$thanks .= '' . $thanks_string . '
';
to this:-
$thanks .= p_render('xhtml',p_get_instructions($data['thanks']),$info);
Which then allows the use of a link back to the same page when processing a Bureaucracy form:-
Thanks [[$examplepage|Continue]]
**NOTE:** If form creates a data plugin edit table the wiki code needs to be quoted (surrounded by //" "// quotes as in the example below)
Thanks "[[$page|Continue]]"
===== CSS Formatting =====
* [[:tips:button_align|How to align a