DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:form

Formular Plugin Documentation

Compatible with DokuWiki

2008-05-05, Doesn't work on Hrun 2014

plugin Lets you create custom input forms.

Last updated on
2009-03-12
Provides
Syntax
Conflicts with
bureaucracy, bureaucracy-au, bureaucracy

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Similar to contactmodern

Tagged with form

Note: this is the Formular plugin by Ole Rienow, not Form plugin by Esther Brunner.

Recent Changes:

  • 2008-07-20 – Hold Data in Selectboxes, Radiobuttons and Checkboxes as well - also GET-Parameters for this available
  • 2008-07-19 – Added File-Upload for sending MIME-Mails with Attachment
  • 2008-07-18 – Hold old Data if Constraint is not fulfilled
  • 2008-07-09 – Local wikipage language added (Hidden lang “en”;)
  • 2008-07-03 – Constraints for self written Scripts, Username in Mail, Grepnot Constraint
  • 2008-06-29 – You can hand over GET-Parameters as Standard Values for Textfields and Textareas
  • 2009-03-12 – little bugfix of missing quotation mark in textareas / new Italian translation - thanks to Diego Pierotto

Installation:

I advice to use the plugin manager. Simply add http://rienow.eu/dokuwiki/formular.tar. However if you can't use it get the tar file and extract it to your plugin directory lib/plugin/.

Config:

You can set the config parameter using the configuration manager. There you should change the Mail-Address of the sender.
You can change the layout of the forms by changing the style.css in your plugin directory.

Note for Windows user

  1. The Email Sender has to be set
  2. You need an element named submit. For example: Hidden submit “null”;

Create a Form and call PHP-Script:

<FORM "WhereToGo">

WhereToGo can be a PHP-Script, a wiki page or an external link. (www.google.de or http://www.google.de)
The PHP-Script Path should be declared absolutely or relative to the DokuWiki directory.

Create a Mail-Form:

<FORM MAILTO:your@adress.de NEXT:"" PHP:"">
MAILTO: The email address where the formular data should be sent when the submit button is pressed.
NEXT:“” You can declare a wiki Page or an external link (www.google.de or http://www.google.de) where the user will be sent to, after sending a mail.
PHP:“” You can simply include a PHP Script in the Mail-Script created by this plugin. The File-Path can be absolute or relative to the mail-script dir (by default “data/formplugin/”).
This is only possible if the configparameter 'AllowInclude' is set to 1.

Only one MAILTO form per wiki-page is permitted!

Localisation:

If you include a Hidden field named lang you can specify the language-file you want to use on this wikipage. For example if you include the line 'Hidden lang “de”;' the language file lang/de/lang.php is loaded and used even if the global language is set to English. If this localisation-file does not exist the global language-file is used. You should specify the language at the very beginning of your formular.

Body:

Empty lines are ignored. At the end of each element has to be a ;
If you want to use a ; in your line, simply use \;
This makes it possible for you to use PHP tags in the textfields.
The following elements are defined:

Static

Creates a line with static Text.

Static "Shown Text" "Optional Text";
“Shown Text” If this is the only argument the text fills the hold line. DokuWiki syntax to format the text is allowed.
“Optional Text” Optional
The first text is shown in left column, the second in the right.
Empty strings are allowed. DokuWiki syntax to format the text is allowed.

Line

Creates an empty line. Good for spaces between body elements.

Line;

Textbox

Creates a Textbox.

Textbox name "Shown Text" width;
name The name of the element. Should be short and pregnant, without blank.
“Shown Text” The Text shown in the left column. DokuWiki syntax to format the text is allowed.
width Optional Elements width in pixel.

Tip: You can handover a value by setting a Get-Variable which is named like the element. For example add ?subject=Valuetext to your URL to write Valuetext in your Textbox named subject. (From Version 2008-06-29 on)

Passbox

Creates a Textbox for passwords.

Passbox name "Shown Text" width;
name The name of the element. Should be short and pregnant, without blank.
“Shown Text” The Text shown in the left column. DokuWiki syntax to format the text is allowed.
width Optional Elements width in pixel.

Textarea

Creates a Textarea.

Textarea name "Shown Text" rows width;
name The name of the element. Should be short and pregnant, without blank.
“Shown Text” The Text shown in the left column. DokuWiki syntax to format the text is allowed.
rows Number of shown rows.
width Optional Elements width in pixel.

Tip: You can handover a value by setting a Get-Variable which is named like the element. For example add ?subject=Valuetext to your url to write Valuetext in your Textarea named subject. (From Version 2008-06-29 on)

Hidden

Creates an Hidden field. Useful to give constant values to a PHP script.

Hidden name "Value";
name The name of the element. Should be short and pregnant, without blank.
“Value” The Value of the element.

Select

Creates a Selectbox.

Select name "Shown Text" "OptionsList"|OptionsName width;
name The name of the element. Should be short and pregnant, without blank.
“Shown Text” The Text shown in the left column. DokuWiki syntax to format the text is allowed.
“OptionsList” OptionsName You can either give an list with options or give a valid name.
An OptionList should be given like the Following: “listelement1,listelement2”. You can use \, to actually show a comma. Blanks are allowed.
width Optional Elements width in pixel.

How to define names for options.

Create a wikipage with the name you specified in your conf (by default this is the page formplugin:select). There you can define OptionList by following syntax.

name listelement1,listelement2...

Only define one OptionList per line.
You can use \, to actually show a comma. Blanks are allowed.

Checkbox

Creates a Checkbox. This element is created in the left column.

Checkbox name "Shown Text" value;
name The name of the element. Should be short and pregnant, without blank.
“Shown Text” The Text shown on the right of the checkbox. DokuWiki syntax to format the text is allowed.
value Optional This can be set to 0 or 1. If set to 1 the Checkbox is checked by default.
The default value is 0.

Radio

Creates a set of Radiobuttons. The first one is checked by default.

Radio name "Shown Text" "Options";
name The name of the element. Should be short and pregnant, without blank.
“Shown Text” The Text shown in the left column of the first element. DokuWiki syntax to format the text is allowed.
“Options” This is a comma-separated list of Options. Blanks are allowed. You can use \, to actually show a comma.

File

Creates a File-Upload Field. You can use as much as you want in one Formular. You don't have to specify a name for this Element. If you use the MAILTO-Tag in the Header the Files are sent to the given Mail-Address.

File "Shown Text" MAXSIZE [width];
“Shown Text” The Text shown in the left column of the first element. DokuWiki syntax to format the text is allowed.
MAXSIZE With this Parameter you can limit the size of the files which can be uploaded in MB. Values like 0.5 are also allowed.
width Optional Elements width in pixel.

Submit

Creates a single submit Button.

Submit "Submit Text" width;
“Submit Text” The Text shown on the Submit Button.
width Optional Elements width in pixel.

The submit button is placed left of the right column.

Buttons

Creates a submit and a reset button.

Buttons "Submit Text" "Reset Text" [width];
“Submit Text” The Text shown on the Submit Button.
“Reset Text” The Text shown on the Reset Button.
width Optional Elements width in pixel. Each of the buttons has this width.

The buttons are placed left of the right column.

Constraint

You can use this to validate formula data if you use the MAILTO tag in the header or if you specified a PHP script which is writable. In this case the Constraint-Code is written at the beginning of your Script. If you want to use it for your self written Scripts the setting “Use nice URLs” has to be DokuWiki Internal (2) and the setting of “Use slash as namespace separator in URLs” should not be checked.

Constraint name "Error Text" Constraints;
name The name of the element for which this constraint should be checked.
“Error Text” The Text shown if the constraint is not fulfilled.
Constraints One or more valid constraints.

Valid constraints

grep=“” Validates field data by given regular expression.
http://php.net/manual/en/reference.pcre.pattern.syntax.php
grepnot=“” Validates field data by complement of a given regular expression.
minLength=“” Checks if the field data's length is not less than the given value.
maxLenght=“” Checks if the field data's length is not greater than the given value.
length=“” Checks if the field data's length is equal to the given value.
valueType=“eMail” Checks if the field data is a valid E-Mail address using the following grep expression
/^[A-z0-9\._-]+@[A-z0-9][A-z0-9-]*(\.[A-z0-9_-]+)*\.([A-z]{2,6})$/.
valueType=“integer” Checks if the field data is numeric and contains of nothing than digits.
valueType=“float” Checks if the field data is numeric.
evalFunction=“myPHPFunction” Calls the given function which can be declared in a PHP file declared in the header.(Keyword PHP:)

You can define as many constraints as you like for each element. If you want the same error text you can write as many constraints as you like in one line. If you'd like different error texts you have to declare one constraint per line.

Overview

Static “Shown Text” [“Shown Text”] ;
Line ;
Textbox name “Shown Text” [width] ;
Passbox name “Shown Text” [width] ;
Textarea name “Shown Text” rows [width] ;
Hidden name “value” ;
Select name “Shown Text” “Optionslist” or Optionsname [width] ;
Checkbox name “Shown Text” [0 or 1] ;
Radio name “Shown Text” “Options” ;
File “Shown Text” MAXSIZE [width] ;
Submit “Shown Text” [width] ;
Buttons “Submit Text” “Reset Text” [width] ;
Constraint name “Error Text” Constrains ;

Ending Tag:

Use this at the end of your form.

</FORM>

Examples

Simple Mail Form

<FORM MAILTO:your@adress.de NEXT:"intro:formdoku">
Hidden dokupage "formplugin:simplemail";
Textbox name "Your name" 290;
Textbox mail "Your Mail adress";
Checkbox news "We advice you to subscribe to our newsletter" 1;
Line;
Textarea comments "**Comments**" 10 320;
Constraint name "Mind. 3 chars!" minLength="3";
Constraint mail "Not a valid Email-Adress" valueType="eMail";
Submit "proceed" 90;
</FORM>

Extended Mail Form

<FORM MAILTO:your@adress.de PHP:"http://rienow.eu/form/test.php" NEXT:"intro:formdoku">
Hidden hiddenfield "some constant value";
Textbox name "Your name" 290;
Passbox pass "Your password" 290;
Constraint pass "Wrong password!" grep="/^rienow$/";
Static "A combobox declared by a list";
Select country "Your country" "Deutschland,Italien und Österreich\, Schweiz,Schweden" 290;
Static "A combobox declared by a name";
Select country1 "Your country" country;
Line;
Checkbox news "We advice you to subscribe to our newsletter" 1;
Checkbox news2 "We advice you to subscribe to our newsletter";
Line;
Radio zahlmethode "Payment:" "Mastercard,Visa,Cash\, Paypal";
Line;
Textarea comments "**Comments**" 10 320;
Textbox zip "zip" 290;
Textbox mail "e-mail" 290;
Textbox max7 "max 7" 290;
Textbox min7 "min 7" 290;
Textbox greptest "greptest" 290;
Textbox testint "Int test" 290;
Textbox testfloat "Float test" 290;
Textbox functiontest "Function test" 290;
Constraint greptest "GrepTest failed!" grep="/^[A-z0-9\._-]+@[A-z0-9][A-z0-9-]*(\.[A-z0-9_-]+)*\.([A-z]{2,6})$/";
Constraint min7 "Mind. 7 digits!" minLength="7";
Constraint max7 "Max. 7 digits!" maxLength="7";
Constraint zip "5 chars!" length="5";
Constraint mail "Not a valid Email-Adress" valueType="eMail";
Constraint testint "Not a valid integer" valueType="integer";
Constraint testfloat "Not a valid float" valueType="float";
Constraint functiontest "Number hast to be greater than 80..." evalFunction="myPHP_Function";
Buttons "proceed" "clear" 90;
</FORM>
<FORM "www.google.com">
  Submit "Google";
</FORM>

Feedback

Feature Requests

The plugin works great, thanks for it!
One little flaw though: when you check the contents of the form with constraints and get an error (e.g. 'e-mail address not valid'), you are taken back to an empty/blank form which is very annoying - you have to fill in all the text again. Is there any solution to this? Alexander 2007/07/30

This is done from Version 2008-07-19 on.
Ole

I am using the right version but errors are not printed and Forms keep empty. Please notice that the messages were posted (so the main functions working).

Julien 2008/10/15 21:34


Hi, I don't know if I'm in the right area to edit, but, okay, could there be a bug in your application to do with caching in certain instances? with constraints my forms don't seem to be working and certain values seem to 'stick' as if they're cached because there are no URI variables for $_GET to grab onto anymore but the values remain, which could only mean a caching issue, but, I see caching is meant to be switched off… Please think this over.

William 2008/08/13 16:57

Suggestion: Send email message in UTF-8 format

The email message sent by formular does not tell the receiving email client what format (or character set) the message is. Therefore the receiving email client does not display the non-English characters correctly. To fix this I suggest that you should change row 296 (or 295 in older version) in syntax.php like this == Old line 296: ==

.'mail($receipt, \''.$subject.'\', $string, $from);' 

== New line 296: ==

.'mail($receipt, \''.$subject.'\', $string, $from."\nContent-Type: text/plain; charset=UTF-8; format=flowed\n");' 


I found this from PHP manual for mail-function (Search for 'UTF-8').

Ciove 2008/07/01

Added something similar to official version
Ole
Update: From Version 2008-07-19 MIME-Mails are sent because of the file-upload feature.
Ole

Hi, Ole Does the update you've mentioned above mean that the text in e-mail message cannot be charset=UTF-8? According to my tests this does not corrupt the message or the attachment file?

Thanks again for a great plugin. — Ciove 2008/10/01

Suggestion: MailAlsoTo and MailSubject elements

MailAlsoTo-element would be a special Textbox-element and/or Hidden-element, and it would add to address to CC-field (Carbon Copy) of e-mail message.

MailSubject-element would be a special Textbox-element and/or Hidden-element, which would override the mailFrom-setting in /lib/plugins/formular/conf/default.php.

Ciove 2008/10/01

Suggestion: Default values to text elements

One more parameter to text elements 1): Default value. The element syntax could look like this:

Textbox My_field "My field" 16 value="My default text";

This would be generated to HTML like this:

My field <input class="edit" type="text" name="My_field" size="16" value="My default text">

Ciove 2008/10/02

Question about the handover / Get-Variable function for text elements

You wrote that the 2008/06/29 version supports preset values in the text elements. Unfortunately, I don't understand how it works. I tried these unsuccessfully:

  • Add the ?fieldname=value string to the end of the address field of my browser.
  • Modify the code:
Textbox testfield "My test field:" 500 ?testfield=values;

Ciove 2008/07/01

Hi Ciove,
I changed the text so I hope you can understand it better now. You don't have to change anything on the wiki. 
Just handover a Get-Parameter through your URL. The name of the Parameter has to be the name of the 
element and the value is the displayed text in that field.
Greetings Ole

Hi Ole. Thanks for clarification, I understood it now. However, this feature does not work in my wiki. My environment is W2k3/IIS, PHP Version 5.2.4. I've tested with DokuWiki version 2008-05-05.

Ciove 2008/07/10


Hi Ciove,
please check again with the newest version. If it does not work please send me a mail to sort things out.
Ole

Hi Ole.

Thanks for the plugin, it's very useful, but I cannot use the feature described above on my wiki, as well. Seems that the _GET array is every time empty and I cannot see any data inside the elements both when I try to add in the URL and when the page turn back after a constraint not respected. In the second case, any error is displayed and any element hold the data. Am I missing some configuration in PHP? If you need testing, I can give you an URL (by e-mail) to reach mi Wiki testing copy. Thanks in advance.

Daniele 2008/09/03

Question : Select Constraints

  • Q. : How do I setup a constraint to check that a user filled out a Select field? i.e. make it a required one? I tried grepnot for /n\/a/, but it didn't work. thanks in advance! —2008-08-05

suggestion concerning hard-coded styling elements

The styling of most elements of the plugin can easily be influenced via CSS as subelements of <table class=“formular”>.
So that's fine.
However, there are a few hard coded pieces of styling, such as the <span>-tags surrounding error messages:

<table class="formular">
  <tr>
    <td colspan="2"><span style="color:#FF0000;">some error message</span></td>
  </tr>
  ...
</table>

I changed this hard-coded styling in syntax.php for my installation. How about defining it via CSS in the plugin in general?
Cheers.

Thomas 2009/09/21

Bugs / Problems

utf8decode vs utf8_decode

the plugin works only, if I correct utf8decode to utf8_decode in the php-scripts in the folder formplugin/<site>/form_<site>.php

could you correct this?

Thanks

Thomas


Change the syntax.php line 660 from:

. "\n".'  $back .= $key_name . "=". utf8decode($key_value) . "&";'


to:

. "\n".'  $back .= $key_name . "=". utf8_decode($key_value) . "&";'


Christian 2009/06/09

Thanks for clarifying this!
Worked perfectly for me.
Cheers, Thomas
2009/21/09

Tips

Hint. I got the "You don't have permission to access /data/formplugin/form_feedback.php on this serve" on Apache. I solved the problem by adding following to the Apache configuration.

  <Directory "/www/localhost/htdocs/data/formplugin/">
  AllowOverride None
  Order allow,deny
  Allow from all
  </Directory>

Benny 2008/03/19 16:39

Other

Is it possible to use GET method ? Because I've try to build a syntax plugin in order threat data but I couldn't access to $_POST. I wish try with $_GET

Victor Benarbia 2008/09/01


I took the example Simple Mail Form and put it in the playground as a test with my own email address, but no email is sent and instead it takes me to: /data/formplugin/playground/form_playground.php

Does anyone know why it isn't working?


Windows issues

It took me a while to understand the second Note for Windows user;

You need an element named submit. For example: Hidden submit "null";

This means if you don't add the Hidden submit “null”; -line to your form, the Buttons -command does not work. When user clicks the submit button, user gets this error:

Notice: Undefined index: submit in [PathToDokuWiki]\data\formplugin\form_testing.php on line 50

However the Submit -command (or element) works OK without Hidden submit “null”;.

Sendmail

In Windows, to be able to send email from DokuWiki and other .php applications, you need to install software that emulates sendmail in Linux. Here's my suggestion:

  • Copy Fake sendmail for windows and unzip it to your PHP-folder, mine is in C:\php\sendmail.
  • Edit C:\php\sendmail\sendmail.ini to match your SMTP-server.
  • Add C:\php\sendmail -path to path environment variables 2).
  • Edit [mail function] section in C:\php\php.ini:
    • SMTP = your.smtp.domain.com
    • smtp_port = 25
    • sendmail_from = senders.address@domain.com

Add Data

Is there a way to use this plugin to add data to a wiki page? In other words, is there a way to set up the form to show on a wiki entry and when the user fills out the form the data is added to the page in question? In addition is there a way to use the form for editing pages?

Thanks

YES. Post to a PHP form and use fopen(); fwrite(); and fread(); to open the path to the page you want to alter fwrite to write your changes. The PHP manual on php.net has some examples…

UPDATE (03/19/2009, gregory [dot] hall [at] analog [dot] com): Or, throw it back at the wiki itself… In your form:

<FORM doku.php>
Hidden FormType="TestForm";
blah... blah... [your form here]
</FORM>

…and in your doku.php, you'd have to hand edit…

(at top)
  // you will create "inc/form_processor.php" and add the function "TestForm"
  // to process your form
  if ($_REQUEST['FormType']) require_once(DOKU_INC.'inc/form_processor.php'); 

(further down... after "import variables")
  // this calls the function "TestForm", which (of course) lives in form_processor.php
  if ($_REQUEST['FormType']) { $_REQUEST['FormType'](); }

Now you can modify “global $ID” from within form_processor.php, do anything you want to process the form fields (as $_REQUEST['blah'] variables), and return nicely to your wiki.

Problem 403

Hi. I have a problem. When I click “proceed” I get an 403 Error. My formular-file data/formplugin/ and all subfolders have 755 as permission to execute all PHP files.

Help!


I am also getting the 403 error. Hosted on a LAMP server yet the mail never sends and I cant figure out why not! Anyone have any ideas?! Thanks.


me too

—- Hi, I have also the same problem. What is the meaning of data/formplugin? Thanks.


In the data folder there is a .htaccess file, if you change “deny all” to “allow all” you will no longer receive a 403. However this does allow anybody access to your data folder and all files in it. So use this with caution. We are working on a permanent fix for this and will get back with the solution shortlyGary Greyling 2009/07/20 11:17

I implemented a quick fix on Gary's request, which involves adding a proxy php file for form submit and changed the plugin to render the form to submit to the proxy page. After these changes, you can set the .htaccess back to deny all

create a proxy php file called “submit.php” inside the plugin folder

<?
$path = explode('=',$_SERVER['HTTP_REFERER']);
$path = explode('&',$path[1]);
$path = $path[0];
$path = explode(':',$path);
$submitpath = '';
for($i=0;$i<count($path)-1;$i++)
{
        $submitpath.=$path[$i].'/';
}
$submitpath.='form_'.$path[$i].'.php';
include_once('../../../data/formplugin/'.$submitpath);
?>

modify the syntax.php, change the line

$action = DOKU_URL . $this->mailFile;

to

$action = DOKU_URL . 'lib/plugins/formular/submit.php';

James Lin 2009/07/20 12:42

I was unable to get James workaround to function properly. So I just added a .htaccess file to the formplugin data directory that allows all.

Rob Vice 2011/08/02 3:04

Get Variables

Hello! My provider does not support simple get variables, in my special script I have to rewrite each e.g. $subject to $subject=$_POST['subject']; only after that mail($to, $subject, $message) sends me e-mails, but the automatically created PHP file only uses the simple variables. (The conf of the server is register_globals on OFF.) I do not know what to do, because the PHP file seems to be rewritten after every change of the form, so that it is useless to change it by hand via ftp.

Handing over of get variables does not work either, I typed it everywhere e.g: http://roomsixhu.beerdrinkers.eu/doku.php?id=literatur:form2&to=roomsixhu@freenet.de (with quotes, too or literatur:form2&to=roomsixhu [at] freenet [dot] de, to set the address. Probably my PHP skills are too weak. I will read a tutorial these days. Cheers Roomsixhu

Hello, further if I place NEXT before PHP (with my own mail.php) without MAILTO no mail is sent at all, otherwise if PHP is first, redirection does not work. Cheers, Roomsixhu

Problem with Constrains

Hi, i set constrains and they work. Only if there is a email in the adressfield it will be send. But if there is no email it will only reload the startpage and not show a warning message or anything else. How could I change this?

I find the problem and the solution. My first problem is I change the rewrite of DokuWiki to the one with the value 2 and this plugin always insert something like “doku.php” and so my wiki jump to the first site. I change this in the syntax.php at line 723 … I have deactivate this line. Maybe the developer could put in the new version an option to de/activate this in the configuration?

Problem with Caching

Hi, every time one Constrains happen no errormessage was shown. So I prove the url and all things fine. But if I add something like &purge I see an error message. So I activate ~~NOCACHE~~ but nothing change. For this problem is an easy solution to change argument of

Hidden dokupage "<URL>";

to

Hidden dokupage "<URL>&purge";

And then it worked.

I solved it in an even easier way after reading your hint:
<FORM ...>
...
Hidden purge "";
...
</FORM>


This generates the empty entry

purge =>


in the generated mails (if it is a mail form) but I can very well live with that.
Having said that, I would of course be happy about a general solution of the caching problem in the plugin.

Thomas 2009/21/09

GET or Caching problems workaround

It's not clean, but it works for me…

function render($mode, &$renderer, $data) {
    if ($mode == 'xhtml') {

        $renderer->info['cache'] = false;

        if (isset($_GET['error'])) {
            $data = str_replace('<table class="formular">',
            '<table class="formular"><tr><td colspan="2"><span style="color:#FF0000;">'.$_GET['error'].'</span></td></tr>', $data);
        }

        $blacklist=array("error","id");
        foreach($_GET as $key_name => $key_value) {
            if ($key_value == "" || in_array($key_name, $blacklist)) continue;
            $data = str_replace('name="'.$key_name.'"', 'name="'.$key_name.'" value="'.$key_value.'"', $data);
        }
        $renderer->doc .= $data;
        return true;
    }
    return false;
}

Ondra Kotek 2009/08/06 12:16

1)
Static, Textbox, Passbox, Textarea and Hidden, maybe to MailAlsoTo and MailSubject elements if you agree to do them.
2)
Right-click MyComputer, Properties, Advanced, Environment variables, System variables, select Path -variable, Edit, Add ;C:\php\sendmail to the end of the Variable Value field
plugin/form.txt · Last modified: 2017-08-10 03:50 by 125.7.37.86