Bureaucracy Plugin

Download and install the plugin using the Plugin Manager using the following URL. Refer to Plugins on how to install plugins manually.

• bureaucracy-plugin-latest.tgz

• 05 Jan 22:13 - Allow multiple mail receivers (just separate by space)
• 05 Jan 22:13 - German language fixes
• 05 Jan 22:03 - Spelling correction
• 05 Jan 22:00 - Support for namespace templates
• 05 Jan 21:16 - More docs in the action.php, change of the run() return
• 03 Jan 17:59 - Added CAPTCHA support (when plugin is installed)
• 03 Jan 00:40 - Support for namespace and sepchar in template action
• 03 Jan 00:30 - simplified template handling

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.

This plugin should currently only be used on closed wikis, because it could easily be abused as a spam gateway. Counter measurements are planned for future releases.

Let's start with a example:

<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
</form>

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

• action
  • The first parameter needs to be a supported action (see below). Currently supported are mail and template.
  • Additional parameters for type mail:
    • one or more email addresses to send the data to (required)
  • Additional parameters for type template:
    • pagename of a page to use as template (required)
    • namespace 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 from was submitted. (optional)
• fieldset
  • creates a new set of fields
  • a label is optional
• 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
• yesno
  • creates a checkbox
  • needs a label
• select
  • creates a dropdown list
  • needs a label
  • needs a second argument containing the select options separated by a pipe (|) char
• submit
  • creates a submit button (required)
  • a button label is optional

• 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
• Put a single ! char to make a field optional
• Put a single @ char to make its value be used for the pagename in template mode
• Enclose a regular expression with / chars to require the the regexp to match before the field is accepted (case insensitive)

The bureaucracy does three things:

1. it displays a neat form
2. it validates user input
3. 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.

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.

This action uses a given page as template, will replace defined placeholders with the user input and create a new wiki page.

When using this mode you need to make sure to mark at least on of the input fields to be used as pagename using the @ character.

The page that is used as template needs to contain the same fields as your form, surrounded by @@ characters.

Let's have an example – assume the following to be your form definition:

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

To create a new page the above will look for the page userstpl (given as second parameter in the action field). This page needs to contain placeholders to be replaced with the user data. Here is an example how this could look like:

====== @@What's your Name?@@ ======

I'm living in @@What's your Continent?@@.

@@Enter a short bio@@

The above example form will use the use the continent and name to create a new page. The third parameter of the action field is a namespace that is prepended to the pagename. Because the fourth parameter of the action field is set to : it will use the continent as a namespace, too. For example if I would fill the form, the resulting page would be users:europe:andreas_gohr. When the third parameter is not given, the fields are joined with the character from the sepchar config option. E.g. it would result in users:europe_andreas_gohr.

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

====== Andreas Gohr ======

I'm living in Europe.

It's me :-)

Alternatively you can just give an underscore (_) as template name and the plugin will attempt to use the configured namespace template. You may also use ## characters instead of the @@ characters in placeholders. This makes it simpler to use this plugin with the data plugin.

I'd love to see:

1. an instruction to set the subject of the email (something like Subject “This is the subject for this email”), with a fallback to current behavior if no Subject is specified.
2. The ability to specify a wiki page using the “Thanks” attribute, resulting in a re-direct to that page on success (Thanks [[:start]])
3. The ability to fill field defaults based on the user's DokuWiki profile (name, username, email address) using macros like those in the newpagetemplate plugin (email “Email Address” ”=@EMAIL@”)

2008-12-03 m.mccarn@aicr.org

- The ability to specify a wiki page using the “Thanks” attribute, resulting in a re-direct to that page on success (Thanks [[:start]])

This should be possible when you change line 173

$R->doc .= '<p>'.hsc($data['thanks']).'</p>';

to the following

$R->doc .= p_render('xhtml',p_get_instructions($data['thanks']),$info);

Now it is possible to use wiki-syntax in the “Thanks” attribute. So you can use the include plugin to include a page into the result view.

2008-12-09 christian.moll@tudor.lu

Thanks for your efforts, but there are one issue I am not happy with. We get a lot of emails produced with bureaucracy, and it would be very helpful to have the email address of the sender directly in the subject. To easily sort the incoming mails.

2009-01-07 christian.moll@tudor.lu