Formular Plugin Documentation

• 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 Attachement
• 2008-07-18 – Hold old Data if Constraint is not fullfilled
• 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

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

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.

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

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

<FORM MAILTO:your@adress.de NEXT:"" PHP:"">

Only one MAILTO form per wiki-page is permitted!

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.

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:

Creates a line with static Text.

Static "Shown Text" "Optional Text";

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

Line;

Creates a Textbox.

Textbox name "Shown Text" width;

Tipp: 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)

Creates a Textbox for passwords.

Passbox name "Shown Text" width;

Creates a Textarea.

Textarea name "Shown Text" rows width;

Tipp: 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)

Creates an Hidden field. Usefull to give constant values to a php Script.

Hidden name "Value";

Creates a Selectbox.

Select name "Shown Text" "OptionsList"|OptionsName width;

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.

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

Checkbox name "Shown Text" value;

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

Radio name "Shown Text" "Options";

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

Creates a single submit Button.

Submit "Submit Text" width;

The submit button is placed left of the right column.

Creates a submit and a reset button.

Buttons "Submit Text" "Reset Text" [width];

The buttons are placed left of the right column.

You can use this to validate formular data if you use the MAILTO tag in the header or if you specified an own 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;

/^[A-z0-9\._-]+@[A-z0-9][A-z0-9-]*(\.[A-z0-9_-]+)*\.([A-z]{2,6})$/.

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.

Use this at the end of your form.

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

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

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, Don't know if I'm in the right area to edit, but, ok, 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

I which to get user information (name and email from profile) in the mail (Received By). Would be great. Thanks for the plugin.

— Benny 2008/03/19 16:57

This is included since Version 2008-07-19. Either $_SERVER['LOGON_USER'] or $_SERVER['REMOTE_USER'] has to be set.
Ole

This works in my W2k3/IIS DokuWiki too:

Hidden MessageSentBy "<php>Echo $_SERVER['LOGON_USER']\;</php>" ;

To get this working, I've enabled the phpok -parameter at my /conf/dokuwiki.php

$conf['phpok']       = 1;

— Ciove 2008/07/01

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

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

One more parameter to text elements ¹⁾: 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

I cannot understand these instructions – does this plugin allow embedding a form described in a separate PHP file into a DokuWiki page?

No it embeds a form in the DokuWiki page. 
The created separate PHP file is just for dealing with the form-data send by a user using your form.
Ole Rienow

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

• 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

I am having problems including ComboBox names from a seperate Wiki page. No matter what i do i get “ComboBox name thename is not defined!” whenever i try and use them. I have a Wiki page created called testform:lists and have set that in my conf file for the plugin. The “lists” Wiki page contains “thename value1,value2,value3” and that is it. I have tried lots of different things but it will not work, can anyone help?

— Rich 2008-02-25 15.59

Thank you Ole after downloading your newest one this seems to work OK. Now the only problem i have is if i use too many comma's (For\, example\, if\, i\, use\, this\, many) in a combobox most of the sentence is not shown. For example, if i put this into the formplugin:select page: address Test - Mr Tester\, 15 Test Street\, Testtown\, New Testshire\, AA12 1AA The combobox displays only “New Testshire, AA12 1AA” on the page, rather than the full line?

— Rich 2008-03-03 16.07

This Problem is solved.
Ole 2008-03-30

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

Just updated this plugin with some minor modifications:

• make compatible with configuration plugin
• localize [include only the En, Fr translations]
• add default styles [borrowed from Esther's form plugin]
• rename to Formular (not to confuse with Esther's Form plugin) and to keep compatibility with previous versions settings

Apparently I'm not allowed to upload it on this server.
As soon as I'm allowed to upload I'll post a link.
Or best, maybe the author of the original plugin could include these mods in his version!

In the mean time you can contact me to get the updated plugin.
Update: The plugin author [Ole Rienow] included the modifications into the official version. You may thus download it using the link on this page [above].

— stephanec 2008-02-17 21:17

I included the mods of Stephane. This includes the rename of the plugin. From now on it is named formular again. Therefore the new download location is http://rienow.eu/dokuwiki/formular.tar . Sorry for the inconvenience.
If anybody could send me more translations that would be great.

Ole Rienow 2008/02/28

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

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

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 ²⁾.
• Edit [mail function] section in C:\php\php.ini:
  • SMTP = your.smtp.domain.com
  • smtp_port = 25
  • sendmail_from = senders.address@domain.com

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…

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