====== Bureaucracy Plugin ======

---- plugin ----
description: Easily create HTML forms and collect the data via email or use it to create pages.
author     : Andreas Gohr
email      : andi@splitbrain.org
type       : syntax
lastupdate : 2011-11-29
compatible : 2009-12-25 "Lemming", 2010-11-07 "Anteater", 2011-05-25 "Rincewind", "Angua"
depends    : 
conflicts  : form
similar    : form, contact, contactmodern, conform
tags       : form, email, poll, create

downloadurl: http://github.com/splitbrain/dokuwiki-plugin-bureaucracy/zipball/master
sourcerepo : http://github.com/splitbrain/dokuwiki-plugin-bureaucracy/
bugtracker : http://github.com/splitbrain/dokuwiki-plugin-bureaucracy/issues
donationurl: http://donate.dokuwiki.org/Bureaucracy
----

The bureaucracy plugin allows you to create a HTML form right within DokuWiki. Input format validation is automatically handled by the plugin and requires no coding. User input can be emailed to a preconfigured address or used to create new pages using a template.

===== Download and Installation =====

Download and install the plugin using the [[plugin:plugin|Plugin Manager]] using the download link given above. Refer to [[:Plugins]] on how to install plugins manually.

==== Changes ====

{{rss>http://github.com/feeds/splitbrain/commits/dokuwiki-plugin-bureaucracy/master date}}

==== Recommended additional Plugins ====

You might want to use the [[CAPTCHA]] plugin to avoid automated spam. The [[swiftmail]] plugin may help when your DokuWiki can't send mails. This plugin can be used to gather data for use with the [[data]] plugin.

An additional plugin to look at is the [[pagemod]] plugin which uses the bureaucracy plugin to add data to an existing page (in addition to the current templating and mailing functionality)

==== Warning ====

Without the CAPTCHA, this plugin should only be used on closed wikis, because it could easily be abused as a spam gateway.

===== Usage =====

{{ :plugin:bureaucracy.png?nolink|A sample form with validation errors}}

Let's start with an example:

<code>
<form>
Action mail me@example.com
Thanks "Thanks for submitting your valuable data."

Fieldset "A set of fields"
Textbox  "Employee Name" "=Your Name"
number "Your Age" >13 <99
email "Your E-Mail Address"
textbox "Occupation (optional)" !
password "Some password"

fieldset "even more fields"
select "Please select an option" "Peaches|Apples|Oranges"
static "Some static text that could be an agreement"
yesno "Read the agreement?"
textarea "Tell me about your self"
textbox "You need to write 'agree' here" /^agree$/
submit "Submit Query"
</form>
</code>

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.

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.

The plugin takes care of validating the form the field types and set constraints.

Arguments need to be wrapped in double quotes when they contain spaces.

==== Fields ====

  * action
    * The first parameter needs to be a supported action (see below). Currently supported are ''mail'', ''template'' and ''[[plugin:pagemod|pagemod]]'' (if this plugin is installed).
    * 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 (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)
  * thanks
    * define a text to be displayed when the form was submitted. (optional)
  * fieldset
    * creates a new set of fields
    * a label is optional
    * may depend on the value of another field by (see below)
  * static
    * adds some static text to the form
  * 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
  * number
    * creates a single line input field
    * needs a label
    * the input is validated to be numeric
  * textarea
    * creates a multi-line input field
    * needs a label
    * to change the default size (10 rows) to //N// rows, use the argument "x//N//" (optional)
  * yesno
    * creates a checkbox
    * needs a label
    * needs default values for yes and no (=true_value !false_value)
  * select
    * creates a dropdown list
    * needs a label
    * needs a second argument containing the select options separated by a pipe (|) char
  * hidden
    * creates an invisible field with static data
    * needs a default value parameter (''"=some value"'')
  * hiddenautoinc
    * creates an invisible field with a number that increases by 1 on each form use
  * 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 when using a current [[devel:develonly]] version of DokuWiki
  * date
    * a date in the format YYYY-MM-DD
    * needs a label
    * provides a date picker when using a current [[devel:develonly]] version of DokuWiki
  * addpage page_tpl page_tgt
    * adds another page ''page_tgt'' based on a template page ''page_tpl''
    * only for use with the template action

==== Constraints and Defaults ====

  * Start with a ''>'' followed by a number to require numeric data bigger than the given number
  * Start with a ''<'' followed by a number to require numeric data smaller than the given number
  * Start with a ''='' to set a default value
  * Use a single ''!'' char to make a field optional
  * Use a single ''@'' char to make its value be used for the pagename in template mode
  * Use a ''++'' for a number field to make it auto-increment the counter on each form use.
  * Enclose a regular expression with ''/'' chars to require the the regexp to match before the field is accepted (case insensitive)

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

<code>
<form>
action    mail me@example.com

fieldset  "Your Order"
textbox   "Your Name"
select    "What do you want"  "Car|Blimp"

fieldset  "Car Parameters" "What do you want" "Car"
number    "Number of Wheels"
textbox   "Extras"

fieldset  "Blimp Parameters" "What do you want" "Blimp"
select    "Filling" "Helium|Hot Air"
number    "Size"

fieldset  "Confirm Order"
submit "Submit Query"
</form>
</code>

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.

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

Imaging the form given in the previous section 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 =====

The bureaucracy does three things:

  - it displays a neat form
  - it validates user input
  - it gives the user input to a action mode

The last step is where the data is processed. What action is to be used is defined in the ''action'' field as described above. Currently two modes are supported: ''mail'' and ''template''. Additional modes (e.g. for storing the data in a database) can easily be added.

==== Mail Mode ====

This is a simple action. When used 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 mail addresses separated by spaces.

==== Template Mode ====

This action uses given pages as template, will replace defined placeholders with the user input and create wiki pages. This is a very powerful, but somewhat complex concept.

The action line looks as follows:

  action template [template] [destination] [separator]

  * ''template'' is either a single page, or a whole namespace (with trailing colon). When a namespace is given, all contained sub namespaces and pages will be copied to the destination and replacement patterns will be applied in all pages. When you specify an underscore (''_'') as template name, the plugin will attempt to use the configured [[:namespace template]] of the destination namespace.
  * ''destination'' tells bureaucracy where to create the new page[s]. This is usually a namespace (trailing colon).
  * ''separator'' new page names can be created by using multiple form field values. This character defines how these should be concatenated (see [[#Defining the Output]]) 

=== Defining the Output ===

When using the template mode you need to define where resulting pages should be created. There are multiple ways to do this.

**1** The simplest way is to specify an output namespace and mark up your naming fields using the ''@'' character. Here's an example:

<code>
<form>
action   template userstpl users: :

fieldset "Create Your User Page"
select   "What's your Continent?" "Europe|North America|South America|Asia|Australia" @
textbox  "What's your Name?" @
textarea "Enter a short bio" !
submit
</form>
</code>

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

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

<code>
<form>
action   template userstpl users:%Y:@@What's your Name?@@:start

fieldset "Create Your User Page"
select   "What's your Continent?" "Europe|North America|South America|Asia|Australia"
textbox  "What's your Name?"
textarea "Enter a short bio" !
submit
</form>
</code>

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''

**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

FIXME add full example.

=== Creating Templates ===

The templates need to contain the same fields as your form, surrounded by ''@@'' characters.  You may also use ''##'' characters instead of the ''@@'' characters. This makes it simpler to use this plugin with the [[data]] plugin.

These placeholders will be replaced by the actual values the user filled into the form.

You may follow the field name with a pipe ''|'' char and a default value, should the user not have filled in an optional field.

Additionally you can use all [[phpfn>strftime]] parameters to refer to the current time. Note that you will need to replace all "normal" ''%'' chars with ''%%'' to avoid accidental time replacements in your template.

For the ''userstpl'' from the example above, you could have the following page:

<code>
====== @@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@@
</code>

The result then would look somewhat like this with all the user data filled in:

<code>
====== Andreas Gohr ======

I'm living in Europe. I'm a user since 2007-12-23.

It's me :-)
</code>



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


===== Checkbox user guide =====
It took me a while to figure out how the checkbox works. Here's my findings:
  * Checkbox cannot be checked by default. 
  * Checkbox can have default value when unchecked. 
  * :!: If you don't set default value, the checkbox does nothing ((i.e. form does not submit checkbox data.)), checked or unchecked. 
    * :-\ This means that the "Read the agreement?" checkbox in the [[#usage|example]] does nothing. :-\ 
  * Checkbox is always optional. 
    * This means that the "Read the agreement?" checkbox in the [[#usage|example]] **//cannot//** trigger constraint message like this **''(!) "Read the agreement?" -box has to be checked.''**

==== Checkbox example ====
<code>
<form>
Action mail me@company.com
yesno "Are you happy?" ="Yes sir!"
yesno "Are you sad?" !"No sir!"
submit
</form>
</code>


| ^Checked^Result^
^Are you happy?|x|Yes sir!|
|Are you sad?|-|No sir!|
^Are you happy?|-|-|
|Are you sad?|x|-|
^Are you happy?|-|-|
|Are you sad?|-|No sir!|
^Are you happy?|x|Yes sir!|
|Are you sad?|x|-|

--- //Ciove 2010/08/18 //



===== Issues =====
**July 3 2011, Selection Box Bug**:  Not sure if anyone else is having this problem but my selection boxes (drop down lists) are behaving funny and the source seems to be bureaucracy itself. Basically what happens is that they act a bit like a link (nothing happens when you click though) and then there is a small (1-2px) area which is a thin strip across the top of the selection boxes which triggers it to drop down and be selectable.  I am very surprised no one else has run into this problem.  Here is a brief run down:
  - I did a clean install of the most recent Dokuwiki (Rincewind a).  I have not touched any of these files.  
  - I am working on a custom template based largely off of the mnml-blog template.  I have made all of my changes in the user/screen.css and main.php and no where else.
  - I switched to three different templates.  On a clean version of the mnml-blog template and the vector template the error is still there.  In the starter template the error is not there BUT the 'submit' button is in the wrong place (most of the way up the page underneath the first text box).
  - My syntax for the bureaucracy plugin is good.\\ I narrowed the problem down to the following lines of code: <code>

.dokuwiki form.bureaucracy__plugin label span,
.dokuwiki form.bureaucracy__plugin input.edit,


</code>

Specifically the line  float: none !important;.  If I remove that line the selection boxes (drop down lists) work fine BUT the submit button goes most of the way up the page again.  Changing that value to float: left gives the same result, selection boxes are good, submit button is broken.  

So does anyone have any brilliant ideas?  This seems like perhaps the bureaucracy plugin itself needs to be updated to work with Rincewind...or am I missing something.

**FIXED THIS PROBLEM:**
Fixed it.  In case anyone is wondering here is the code.  I had to switch another float around form the bureaucracy style.css.  Put this code inside tpl/tpl_name/user/screen.css

<code>

/* --------------------Bureaucracy Bug Fix------------*/

.dokuwiki form.bureaucracy__plugin label span,
.dokuwiki form.bureaucracy__plugin input.edit,
.dokuwiki form.bureaucracy__plugin textarea.edit {
    text-align: left !important;
    margin: auto 5px;
    float: left !important; /* Part 1 of fix */
    width: 96% !important;
    min-width: 96%;
    max-width: 96%;
}

div.dokuwiki form.bureaucracy__plugin input.button {
margin: 10px; /* Part 2 of fix */
}

div.dokuwiki form.bureaucracy__plugin label input,
div.dokuwiki form.bureaucracy__plugin label .edit,
div.dokuwiki form.bureaucracy__plugin label select {
    display: block;
    float: none !important; /* Part 3 of fix */
    margin-left: 5px;
}
.dokuwiki form.bureaucracy__plugin textarea.edit {
    text-align: left !important;
    margin: auto 5px;
    float: none !important;
    width: 96% !important;
    min-width: 96%;
    max-width: 96%;
}
</code>