PmWiki | PmWiki / Forms

This page explains how you can embed input forms into wiki pages.

Input forms capability became standard after 2.0.beta44, and further improvements to forms processing can be found in the Cookbook (see below).

Input forms don't actually handle any processing of the form data -- it simply allows creation of forms inside of wiki pages. However, it is extensible and makes it possible for the wiki administrator to create custom form elements (see the example of edit page elements below).

Markup

This recipe defines an (:input:) markup which can be used to create a variety of form controls. For most controls the markup has the form

    (:input type name value option=value:)

where type is the type of input element (described below), name is the name of the control, value is its initial value, and options are used to specify additional attributes to the control. For example, the following creates a text input control with a size of 30 characters:

(:input text authorid "Jane Doe" size=30:)

For convenience, an author can also specify name and value arguments directly using name= and value= attributes (same as HTML):

(:input text name=authorid value="Jane Doe" size=30:)

Form markups

Two directives are used to begin and end forms:

    (:input form "url" method:)
    ...
    (:input end:)

The (:input form:) directive starts a form that will post to url using the supplied method. The url must be in quotes. If the url is omitted, then the current page is assumed. If method is omitted then "POST" is assumed. The (:input end:) directive ends the current form.

Note that this recipe doesn't (yet?) make any attempt to ensure that the form output is correct HTML -- it assumes the author knows a little bit of what he or she is doing.

Standard input controls

The standard input controls are:

    (:input text name value size=n:)
    (:input hidden name value:)
    (:input password name value:)
    (:input radio name value:)
    (:input checkbox name value:)
    (:input select name value label:)
    (:input default default-name default-value:) 
    (:input submit name label:)
    (:input textarea name value rows=n cols=n:)
    (:input reset name label:)
    (:input file name label:)
    (:input image name "src" alt:)

Where name and value are in the HTML syntax: name="addr" value="808 W Franklin"

For the textarea control a value can be set from PmWiki 2.2.0beta45 onwards.

The submit control will more often be written as:

    (:input submit value=label:)

Example

Here's a more complete example, e.g., for a login prompt:

(:input form "http://www.example.com":)
(:input hidden action login:)
||     Name:||(:input text username:)    ||
|| Password:||(:input password password:)||
|| ||(:input submit value="Log In":) ||
(:input end:)

Page edit controls

This feature also defines a number of custom types for implementing page edit controls. These are (more are forthcoming):

    (:input e_form:)     
    (:input e_text rows=n cols=n:)
    (:input e_save:)
    (:input e_saveedit:)
    (:input e_cancel:)
    (:e_preview:)
    (:input e_minor:)
    (:input e_author:)

However, they only display as controls when viewed with ?action=edit. Thus, an edit page could be formatted with something like:

!!Editing {$FullName}
(:input e_form:)
(:input e_text rows=5 cols=40:) \\
Author: (:input e_author:) (:input e_minor:) This is a minor edit \\
(:input e_save value="$[Save]" :) (:input e_preview value="$[View Pre]":)
(:input end:)

Editing PmWiki.Forms

(:input e_form :) (:input e_text rows=5 cols=40:)
Author: (:input e_author :) (:input e_minor :) This is a minor edit
(:input e_save value="Save" :) (:input e_preview value="View Pre":)

Custom input controls

This feature also allows wiki administrators to design custom input controls through the $InputTags array. Documentation of this feature will be forthcoming.

See for a custom input tag for instance: Cookbook:InputJumpBox

Example: Input text box which clears a value set when clicked (using script with onfocus event): Add to your local config file:

# input text box will keep initial value, unless name contains '-clear'
$InputTags['text'][':html'] = "<input type='text' \$InputFormArgs  
    onfocus=\"if(this.name.indexOf('-clear')!=-1) this.value=''\" />";

Now if you want an input textbox, which will be cleared when clicking it, add to the name '-clear', like:

(:input text box1-clear "Value will clear":)

Or alternatively add to local config:

# input text box will clear initial value, unless name contains '-fix'
$InputTags['text'][':html'] = "<input type='text' \$InputFormArgs  
    onfocus=\"if(this.name.indexOf('-fix')==-1) this.value=''\" />";

Now any textbox will clear when clicked, unless its name contains '-fix', like:

(:input text box2-fix "Value will stay":)

`(:input auth_form:)`

When someone hits "Save" on a page, we don't want to lose their edits so, any variables that are posted as part of the save get preserved in the AuthForm, so that when they send the password it's just like they were re-posting the page

This is used in Site.AuthForm. Basically it's <form action='{$_SERVER['REQUEST_URI']}' method='post' name='authform'>\$PostVars where $PostVars is a sequence of <input type='hidden' name='...' value='...' /> tags that encode whatever was posted when the auth_form was generated. Essentially $PostVars takes the contents of $_POST and submits them as part of the auth form.

`(:input select ... :)`

This page (largely reproduced below) is testing the new (:input select ... :) markup in forms, as well as testing the ability to retain values across form submissions.

We'll start with (:input select ...:). The basic form of a select box is a sequence of options:


(:input form:)
(:input form:)
(:input select name=abc value=1 label=alpha :)
(:input select name=abc value=2 label=beta  :)
(:input select name=abc value=3 label=gamma :)
(:input submit:)
(:input end:)

Or, the values can be specified positionally:

(:input select name=abc 1 alpha :)
(:input select name=abc 2 beta  :)
(:input select name=abc 3 gamma :)

We can specify the size of the selection box:

(:input select name=abc 1 alpha size=3 :)
(:input select name=abc 2 beta  :)
(:input select name=abc 3 gamma :)

The "multiple" option works:

(:input select name=abc 1 alpha size=3 multiple:)
(:input select name=abc 2 beta  selected=selected:)
(:input select name=abc 3 gamma :)

So, here's a dropdown list of pages in the Test group:

(:if false:)
[[#dropdownlist]]
(:input select name=n {=$FullName} "{=$Name}":)
[[#dropdownlistend]]
(:if:)

(:pagelist fmt=#dropdownlist group=Test:)

A group page navigator:

>>display=none<<[@
[[#navigator]]
(:if equal {=$FullName} {*$FullName}:)
(:input select name=n  selected=selected {=$FullName} "{=$Name}":)
(:if ! equal {=$FullName} {*$FullName}:)
(:input select name=n {=$FullName} "{=$Name}":)
[[#navigatorend]]
@](:nl:)>><<

(:pagelist fmt=#navigator group=Test:)

[[#navigator]]
(:if equal {=$FullName} {*$FullName}:)
(:input select name=n  selected=selected {=$FullName} "{=$Name}":)
(:if ! equal {=$FullName} {*$FullName}:)
(:input select name=n {=$FullName} "{=$Name}":)
[[#navigatorend]]

In the examples above, setting the name to n ("name=n") will make the form navigate to the page identified in the selected value of the input on submission. If you don't want to navigate to the page, try changing the name to something else.

Notes

Note that as of pmwiki-2.2.0-beta26, to have two select boxes inline, not only should you give them different name= parameters, but also have a separator, like a character,   or even the null sequence [==] between them:

(:input form:)
(:input select name=FIRST value=1:)(:input select name=FIRST value=2:)[==]
(:input select name=SECOND value=3:)(:input select name=SECOND value=4:)
(:input end:)

Comments

Is it possible to fill the dropdown list with the content of a page (where I have written all the options line by line)? A kind of (:include:) but inside the dropdownlist. Such a feature should be nice for long lists! PhilB ? January 29, 2007, at 01:48 AM

What change would be needed in the php script in order to correctly process the "multiple" option in the ? Currently they are listed (thru GET method) as individual name=value1?name=value2 etc and so when the php script processes them it assigns whichever is the last one as the actual value. Thus instead of n values you end up with exactly 1 value, always the last one. The net effect is that form values are not maintained through the submission process. I can figure out how to process it otherwise in php, but I don't know what sort of data structure is being used for that "multiple" option -- is it an array? --Peter Bowers October 28, 2007

Sandbox

Feel free to use the space below to experiment with creating forms.

(:input form vtest :)
(:input select name=test value=1 label=test1:)
(:input select name=test value=2 label=test2:) \\\
(:input text name=comment value="test12":)
(:input submit:)
(:input end:)

(:input textarea "Can a textarea's default value have a line \\
break in it?":)

Guess not! That's too bad!

Forms