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

The following file includes a patch which fixes the bug loosely described here but more plainly means that you can't have 2 forms on a single page, if you submit the second form, it will process the first one. With this patch, the forms are given id's and the corresponding form is processed. (Hopefully Andreas will incorporate my changes into his codebase, since its only 4 or 5 lines, I have mailed him)

• bureaucracy-plugin-latest-BASELINE_PATCH.tgz

• 16 May 12:25 - typo fix in dutch translation
• 16 Apr 17:01 - Russian translation
• 23 Mar 09:20 - Dutch translation
• 16 Feb 17:59 - upped version
• 16 Feb 17:57 - work around broken plugin_load() when looking for captcha support
• 21 Jan 19:46 - Optionally use a virtual user for ACL checking
• 05 Jan 22:13 - Allow multiple mail receivers (just separate by space)
• 05 Jan 22:13 - German language fixes

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 bureauracy plugin to add data to an existing page (in addition to the current templating and mailing functionality)

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.

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

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

I've done that:

It might be a bit dirty how I've done it, but it works and it is expandable. The only odd thing is it works only in email and in textbox.

cd/var/www/roehrs-ag/lib/plugins/bureaucracy
vi syntax.php
/ case 'email'

case 'email':
                    global $INFO;
                    $value = str_replace('@USER@',$_SERVER['REMOTE_USER'],$value);
                    $value = str_replace('@NAME@',$INFO['userinfo']['name'],$value);
                    $value = str_replace('@MAIL@',$INFO['userinfo']['mail'],$value);

:wq

2009-02-17 muetze

- 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

I like this plug-in but for the way i would like to use it, I have a problem. I would like to make a few parts with a form and in between some other wiki information (movies with flowplay). And sent all the parts at the end in one e-mail. At the moment is it not possible to do this, because when the information is in the form block it is ignored and when I close the form block and open it after the information the plug-in malfunctions.

2009-01-16 Xavier Vrijdag

UPDATE 01/02/2009 in order to parse wiki code within the form the following code has to be altered in the syntax.php at case 'static': (line 339)(delete the contents of the case “static”)

$hRender = new Doku_Renderer_xhtml();
        $form->addElement('<p>'.$hRender->render($opt['label']).'</p>');
        break;

UPDATE 27/01/2009 I improved the patch. the thanks section is now cut out of the match per regex.

Hi, i created a patch that allows wiki syntax in the Thanks section and also multiline thanks lines. You have to patch the syntay.php file with this:

81c81
< 
---
>     
87c87
<         $lines = explode("\n",$match);
---
> 
90c90,106
< 
---
>         // -------------------------
>         // find the thanks part
>         $t = preg_split("/thanks/i",$match, -1);
>         if (isset($t) && count($t) > 1) {
>             // the thanks text and the rest is in [2]
>             $t1 = explode("\"",$t[1], 3);
> 
>             // replace single quotes with double quotes
>             $thanks = str_replace("'", "\"", $t1[1]);
>             // -------------------------------------------
>             // assemble the match without the thanks section
>             $choppedmatch = $t[0].$t1[2];
>             $lines = explode("\n",$choppedmatch);
>             
>         } else
>           $lines = explode("\n",$match);
>         // -------------------------------------------
116,121d131
<             // is thank you text?
<             if($args[0] == 'thanks'){
<                 $thanks = $args[1];
<                 continue;
<             }
< 
166,167d175
<         }else{
<             $thanks = hsc($thanks);
199,202c207,212
<                     $R->doc .= '<div class="bureaucracy__plugin" id="scroll__here">';
<                     $R->doc .= $success;
<                     $R->doc .= '</div>';
<                     return true;
---
>                  $R->doc .= '<p>';
>                  $hRender = new Doku_Renderer_xhtml();
>                  $R->doc .= $hRender->render($thanks);
>                  $R->doc .= p_render('xhtml',p_get_instructions($success),$info);
>                  $R->doc .= '</p>';
>                  return true;

and the template.php in the action folder with this:

93c93
<         return $thanks.' '.html_wikilink($pagename);
---
>         return html_wikilink($pagename);

Maybe this is can be included in the plugin!? Greetings martin — Martin Heinemann 2009/01/27 17:07

Like the plug-in but I wanted to use the regexp feature to check correct date formatting. With UK dates we use ”/” as the separator, but I can't use that in the regexp match because it needs to be enclosed in ”/” chars. Or if you can't fix that can you provide a date field type, but make sure you can use date formats for different countries. — Anthony Yates 31/01/2009 10:00

I was using the Formular plugin, but it seems to be broken. This plugin works well instead! But there were two things missing that I needed: to be able to pass the form info to another script for processing, and to be able to grab GET values and put them into a hidden field.

BTW, this is my first time ever doing dokuwiki programming, so please excuse me if this is not where I should be posting this.

PASSING DATA: Sure, you could make an action every time you wanted to do this, but then you're modifying files in the plugin… so I made a new ACTION.

<?php
/**
 *
 * @author Andrew Petersen <senofpeter@gmail.com>
 */
class syntax_plugin_bureaucracy_action_shoot extends syntax_plugin_bureaucracy_actions {

    function run($data, $thanks, $argv, &$errors)
	{
		// make an array with input names all lowercase, 
		// with no spaces and special chars removed
		$inputs = array();
		foreach($data as $opt)
		{
			switch ($opt['cmd'])
			{
				case 'submit':
					break;
				case 'hidden':
					$label = $opt['label'];
					$inputs[$label] = $_POST[$label];
					break;
				/*case 'fieldset':
					$value = strtolower(preg_replace("/[^a-zA-Z0-9]/", "", $opt['label']) );
					$inputs['formname'] = $value;
					break;*/
				default:
					$label = strtolower( preg_replace("/[^a-zA-Z0-9]/", "", $opt['label']) );
 					$inputs[$label] = $_POST['bureaucracy'][$opt['idx']];
			}
        }

		// check if exernal script is available
        $escript = array_shift($argv);
		$escriptFolder = "";
		foreach($argv as $entry)
		{
			$escriptFolder .= array_shift($argv) . "/";
		}
		$escriptPath = DOKU_INC.$escriptFolder.$escript . '.php';
        if(!$escript or !@file_exists($escriptPath)) 
		{
            msg(sprintf($this->getLang('e_noscript').$escriptPath, $escript),-1);
			return false;
        }

        require_once($escriptPath);
        $class = $escript;
        $script = new $class();

        $success = $script->run($inputs);
        if($success) {
            return $thanks;
        }
		return false;        
    }
}

This script should be placed in a file called “shoot.php” and placed in the actions folder of the bureaucracy plugin.

This takes all the labels of the form and turns them into script friend names, so “First Name: ” becomes “firstname”. Basically lowercase, no symbols, no spaces. Then it looks for a script you've defined in the form markup, and calls its run() function. You do whatever you want from there.

Example form code:

<form>
Action shoot signupvalidator customScripts
Thanks "Thanks for the submission! Captured!"

Fieldset "Contact Info"
textbox "First Name: "
textbox "Last Name: "
textbox "Title: "
textbox "Company: "
textbox "Street Address: " 
textbox "City: " 
textbox "ZIP: " 
textbox "State: " 
textbox "Telephone: " 
textbox "Fax: " 
email "E-Mail: " 
submit
</form>

The syntax for the action line goes: Action shoot scriptname scriptfolder. The action is called shoot, so it'll always be that, then the filename of the script. In my example above, I have a folder called “customScripts” located in my dokuwiki folder… so from the root of the server it looks like this: /var/www/wiki/customScripts. Without modifying the plugin itself, you can only have one folder, in the root. By my action can take more arguments/folders, but the main plugin only allots 2 arguments for the Action keyword.

GET VARIABLES: This requires a bit of editing of the main plugin files, and it's not functioning exactly. I call out to the creator of this plugin for help! I've got things working enough where it takes any get variable and sets it as the value of a hidden field in the form. The entry looks like this:

hidden "get_value_name"

and in the url: ?get_value_name=43 or something like that.

There's a problem though: sure, you can pass in a get value using the url, but if there is a validation error (like someone didn't put in a valid e-mail address), then the url gets reset. If there is no get value in the url, the hidden field isn't rendered (and even if it were, it wouldn't have a value), and then your script will fail since it won't have that value. Here's the diff:

--- /Users/drew/Downloads/bureaucracy/syntax.php	2009-02-16 12:59:44.000000000 -0600
+++ /Volumes/johnnytatlock.com/wiki/lib/plugins/bureaucracy/syntax.php	2009-02-26 14:45:36.000000000 -0600
@@ -31,9 +31,10 @@
                         'textarea'   => 2,
                         'action'     => 2,
                         'thanks'     => 2,
+						'hidden'	 => 2
                         );
     // types that are no fields
-    var $nofield = array('action','static','fieldset','submit','thanks');
+    var $nofield = array('action','static','fieldset','submit','thanks', 'hidden');
 
     /**
      * return some info
@@ -276,7 +277,6 @@
 
         $form = new Doku_Form('bureaucracy__plugin');
         $form->addHidden('id',$ID);
-
         $captcha = false; // to make sure we add it only once
 
         foreach($data as $opt){
@@ -345,6 +345,9 @@
                     $form->addElement('<label class="'.$class.'"><span>'.hsc($opt['label']).'</span>'.
                                       '<textarea name="'.$name.'" rows="' . $rows . '" cols="10" class="edit">'.$value.'</textarea></label>');
                     break;
+				case 'hidden':
+					$form->addHidden(hsc($opt['label']), $_GET[hsc($opt['label'])]);
+					break;
             }
         }

I also added a line in the en/lang.php for when a script wasn't found at the specified location :

$lang['e_noscript']		 = 'No script was found at that location: ';

Please help! — Andrew Petersen 26/02/2009 15:20

Thanks for this nice plugin. It would be great if the the form sender could have their email address included as the reply-to address on the outbound email. I am looking to have ICT service requests come from a bureaucracy form direct to a ticketing system. In this situation, we want the user's email address to replace the global 'mailto' value. I'll have a poke about in the code, but I'm not sure my coding skills are up to it. — Nick Fahey 26/02/2009 15:20

Hi, I wondered if it is possible to include an image upload option to include an image on a generated userpage. ~ Harriet Lowe, 11/03/2009, 15.39

First I love the plugin. I have a question that someone may have an answer too. How do you create a template off of the form and also email it? It seems to be a one or the other option?? — John Fehr 12/03/2009 10:05

2009-03-19 : I thought someone posted a datepicker patch for this plugin in the mailing list some time ago… true/false? i cannot seem to find it now. thanks in advance!

2009-03-23: Thank you for this plugin. It's very useful for me but I've had some problems when editing the code to add “Thanks Section/Wiki format”. If I edit the form page after this modification, I would obtain a white page where you can not see the form again. Does somebody know to solve this problem? Again, thanks!

2009-03023: Any way to have the plugin append to a wikipage rather than create a new one? Currently you get an error as it tries to overwrite TRY Pagemod

2009-03-23: To the person asking about “Thanks Section/Wiki format” modification: I'm not sure, but I believe the suggested changes were based on an older version of the plugin. When I tried implementing the modification, the plugin broke with similar results to yours.— Andrew Petersen 2009-03-23 21:08

2009-04-15: A definite improvement would be to enable the wiki owner to set a “reply to” mail address in the form, as it is, a mail sent by the form, is sent with a “reply to address”, of the server administrator mail account where the wiki is installed.

This is actually really bad as people might accidentally reply to that address, and not to an address of the server administrators choice, or for that sake the wiki owners choice, these might not be the same entities / persons.

Blankspaces ( i.e. something like </ BR> in order to create spacing between fields would be nice

Also checkboxes - without a forced yes no, i.e. an optional tick would be nice in order to enable one to create a more general form that has multiple useage options.

I also agree with the first suggestion regarding an instruction to set the subject of the email (something like Subject “This is the subject for this email”) - Perfect for SPAM filtering

Where is the donation button for this plugin, it would be a nice way to encourage further development.

Just a few remarks from us and a BIG THANK YOU for a nice plugin that makes our work a little easier.

Best regards - Einar Petersen, Project Manager, The Global Ability Initiative, http://globability.org