Extension:Simple Forms

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 (JS currently removed)
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 method 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.

#edit (in progress)
This parser-function is used to create forms in exactly the same way as #form but is used specifically for the kind of form which is used to populate a template's values. The edit-form is added to a &lt;noinclude> section in the template, and will be rendered when an article using the template is edited. This way a user can edit an article like usual, and if it happens to contain any templates having associated edit-forms, the user can use the specifically designed form instead of the usual content textarea.

The CreateArticle specialpage adds all the templates having an edit-form into it's dropdown list to allow the selection of what kind of article to create.

#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...
 * Note: This example is not currently functional, forms only use GET method currently, not POST or JS

#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.
 * Note1: Indenting is optional, but must use tabs not spaces, because spaces at he start of the line cause &lt;pre> sections
 * Note2: This example works, but requires the ParserFunctions and DynamicPageList extensions.

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.


 * Notes
 * 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).
 * NOTE: Currently the content query-item does not work with action=raw

Appending, prepending, replacing or creating content (in progress)
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 prepended, appended or replaced depending on the value of the caction query item (the default is replace). 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-".

Installation
This extension is a single script which is included in the end of your LocalSettings.php file. Download the current version from OrganicDesign:Extension:SimpleForms.php and save in your extensions directory.