How to use the Script Mode in the Bureaucracy Plug-in
Hello,
The Bureaucracy Plug-in (
https://www.dokuwiki.org/plugin:bureaucracy) is an easy to use tool to create forms quickly. For beginners, the Mail Mode is both powerful and easy to use.
The description of the Plug-in gives a very short example of how to use a script processing with the entered data – Script Mode – yet this is not suitable for programmers on beginner's level. I want to give a more lengthy example here, covering how to pre-fill the form with data from a database, show the form itself, and save the data using a script.
Pre-filling the form
Pre-filling a form is easy using a Wiki link where the field names are enclosed by @-signs:
[[playground:bureaucracy_test?@name@=Säßerich&@username@=saserich]]
Here, the form is on the page
playground:bureaucracy_test[/m], and the transmitted fields are [m]name[/m] and [m]username[/m]. The field [m]name[/m] will be filled with “Säßerich”, the field [m]username will be filled with “saserich”.
However, this won't help if you want to pre-fill the form dynamically from a database. The trick is: We can generate an URL directly which should look somewhat like:
http://localhost/dokuwiki/doku.php?id=playground:bureaucracy_test&@name@=S%C3%A4%C3%9Ferich&@username@=saserich
We have to use rawurlencode() to encode the variable content. Here is a tiny script that encodes all variables, creates the full URL, and finally redirect to the form which will appear pre-filled. This script should be placed somewhere outside the DokuWiki folder, for example, in the root folder of the website (e.g., /httpdocs).
<?php // filename: put_data_for_bureaucracy_form.php
// Switch on error reporting on display. Remove in production!
error_reporting(E_ALL);
ini_set('display_errors', 'On');
// We can fetch some data from somewhere, such as, a database
$data = array(
'name' => 'Säßerich',
'username' => 'saserich'
);
$baseurl = 'http://localhost/dokuwiki/doku.php?id=playground:bureaucracy_test';
$get_vars = "";
foreach ($data as $key => $value) {
$get_vars .= '&@' . $key . '@=' . rawurlencode($value);
}
$url = $baseurl . $get_vars;
// Now redirect to the pre-filled form
header("Location: $url");
We simply call
http://localhost/put_data_for_bureaucracy_form.php[/m] and the form will open which was stored at [m]http://localhost/dokuwiki/doku.php?id=playground:bureaucracy_test:
====== Bureaucracy Plug-in Example ======
<form>
action script get_data_from_bureaucracy_form.php
labels :lang:namespace:form_labels
fieldset "Account"
textbox "username" /^[A-Z]{1,8}$/ "**Username must have 8 characters A~Z"
password "password"
fieldset "Limit access by IP addresses"
select "ip_action" "list|add|remove"
fieldset "Add new IP addresses" "ip_action" "add"
textarea "ip_addresses" x3
fieldset "Remove IP addresses" "ip_action" "remove"
textarea "ip_addresses" x3
fieldset ""
submit "submitbutton"
</form>
The translations for the labels should be stored at
:lang:namespace:form_labels [/m] where [m]lang[/m] can be the language, e.g. [m]eo[/m] for Esperanto, see the wonderful translation plug-in, [m]https://www.dokuwiki.org/plugin:translation[/m]. [m]namespace[/m] can be any DokuWiki folder (better: namespace). We can skip that by now, this just generates an error message and will display the “naked” label names as given. Tip: The last fieldset has no title, giving a nice separated box containing just the submit button. This example shows a tiny example of Regular Expressions: The entered username must be DOS-like: 8 letters A~Z only. The "Add new IP addresses" or "Remove IP addresses" sections are only shown when the corresponding [m]ip_action[/m] has been selected. To achieve this, the 3rd parameter of the fieldset ("add", "remove") must match with [m]ip_action contents.
Now let's look at the script storing the form data. This script has to be stored in
conf/plugin/bureaucracy/, e.g.
/home/user/public_html/dokuwiki/conf/plugin/bureaucracy/get_data_from_bureaucracy_form.php
<?php // filename: get_data_from_bureaucracy_form.php
// Switch on error reporting on display. Remove in production!
error_reporting(E_ALL);
ini_set('display_errors', 'On');
use dokuwiki\plugin\bureaucracy\interfaces\bureaucracy_handler_interface;
class bureaucracy_handler_get_data_from_bureaucracy_form implements bureaucracy_handler_interface {
public function handleData($fields, $thanks)
{ // extracts the form data into an PHP array and into a JSON string
$data = array();
foreach($fields as $field) {
if ($field->getFieldType() == 'fieldset') { } else {
$value = $field->getParam('value');
$label = $field->getParam('label');
if($value === null || $label === null) { } else { $data[$label] = $value; }
} // if
} // foreach
// Just for demonstration, we will display the array. Remove in production!
echo '<hr><p>$array=</p>';
print_r($data);
echo "</p><hr>";
// If you work entirely locally, you can now call e.g. a routine storing this $array in your SQL database.
// Preparing JSON. The data given by DokuWiki are already UTF-8 encoded which is required by JSON.
$json_string = rawurlencode(json_encode($data));
// Save data on some server
$result = file_get_contents('https://www.example.com/?q=' . $json_string);
// After receiving the data, the other server sends back "1" if successful.
if ($result == 1) { $thanks = "Your profile has been updated."; } else { $thanks = "Something went wrong."; }
return $thanks;
} // function handleData
} // class
Some remarks: I did not include any variable check / data filtering.
Always make sure that data posted by an evil user cannot cause any harm:
http://php.net/manual/de/function.filter-var.php For example, you shouldn't rely on the username just having 8 letters, although it should be filtered by DokuWiki this way.
I hope this example will be helpful for hobby programmers like me :-)
My special thanks to user Michaelsy who pointed me to the dynamic pre-filling of the forms!
Greetings,
Gunnar