Extension:Simple Forms

Note: this is still in development

We've needed forms for quite a number of things in our Organic Design wiki such as for creating or editing articles which are based on templates or for making DynamicPageList queries. Instead of making specific code for each form instance, we decided to create a generic set of simple mechanisms which could be re-used to make the creation of all forms and their processing much simpler. Here's a list of the features this extension adds to help with it.

Form Construction & Posting
We wanted forms to be able to be created or and modified by unprivileged users, so we decided against making form articles use raw HTML and instead added two parser functions, which allow forms to be made with normal wiki-markup.

#form
The first parser function is #form which defines the main form container. Three parameters can be supplied, method and action, which serve the same purpose as usual, except that action can be the name of a javascript function if it's not GET or POST. The third parameter is target which either has the normal meaning, or if the action refers to a function, then the target property refers to a part of the document the result should be sent to.

The JavaScript functions which the form can execute should return a URL (including an optional query-string component) which will then be asyncronously requested from the server using an xmlhttp object. The returned content will replace the content (innerHTML property) of the document element having the id specified in the form's target property.

There's currently just one JavaScript function which is called live, using this as the action of the form requests the URL usign an asyncrounous xmlhttp-POST request and adds all the form's input values to the request.

#input
Form inputs are made with the #input parser function, no JavaScript is allowed in the values, except for names of the functions which are registered in the global $wgJavaScriptFunctions array.

Select-lists and textareas can be created using the #input function with type set to select, textarea rather than having their own magic.

Here's an example which dynamically posts the form contents to an imaginary special page for creating articles, by using method=live in the form definition. action=render is used so that the result has no surrounding skin or head/html/body tags. The div below the form will dynamically receive the newly created article content after the button is clicked.

Your new article will be shown in here...

Form Processing
We've also added a couple of features which are useful for the processing of forms.

#request
This allows values from the query-string (GET) or POSTed data to be included in the article to be used by other parser functions when calculating or rendering their results. For example, an article could be made something like the following example which would list the items in a category if its been specified, or render a form otherwise.

The form which is rendered also exhibits a DPL query which creates a list of all categories for the dropdown select-list. The #input function expects to have a standard wikitext bullet list supplied for its list of options, so the DPL query sets the mode and listseparators parameters appropriately.

Parsing content directly
Another thing we've added to this extension is the ability to specify wikitext content directly in the posted data or query string using the content item. This is useful for adding default content to newly created articles, but the main reason we created it was so that forms could use their JavaScript functions to compose wikitext from the form's inputs and then request the parsed result. This effectively allows forms to execute dynamic, transient queries without having to adjust any article content. It's similar to doing a page-preview, but doesn't use any edit form.

The content query-string item can be used in conjunction with the usual actions, but would usually only be used with action=edit, action=render (or maybe action=raw&templates=expand).

Article creation
One of the most common kinds of form are those that result in a new article being created, such as creating articles from templates, enquiry forms or order forms. As described above, the content item can be used with action=edit to produce the initial content for a newly created article, but it can also be used in conjunction with an existing title without any action (i.e. action=view) or with action=render, in this case the article will be created and returned if it doesn't already exist, or if it does exist, the content will be appended. This can be restricted to logged in users or to particular groups.

Form Style
Class and id attributes can be added to customise form design and metrics. By default forms will have class=form and the inputs will have their class set to the value of their type attribute preceeded by "form-".

JavaScript Functions
A global has been added which is also used by all our functions using JavaScript which is the $wgJavaScriptFunctions global array. This uses the function name as its key and the function definition as its value and allows each functions definition to be included only once even if it's used in other extensions.