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.

The SimpleForms extension extends the functionality of MediaWiki in two ways, by addding extra parser functions (accessed using curly-brace syntax in an article's wikitext), and by adding additional parameters to index.php which allows articles to be updated and created directly from HTTP requests without having to process HTML content.

Installation & configuration
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. There are also a number of global configuration variables for enabling, disabling and setting up the various features of the SimpleForms extension. Here is a description of the valid variables.

Form Style
Class and id attributes can be added to the #form or #input parser-function syntax, or to surrounding div elements etc to customise form design and layout from your wiki's CSS stylesheet.

Ajax
The SimpleForms extension can use Ajax technology to allow forms to be posted asyncronously (i.e. not involving a page reload). The content in the server's response can be directed to replace a particular portion of the page containing the form. I've used the Ajax object from the Mootools Javascript framework, so that needs to be downloaded first from mootools.net/download (put a tick in ajax and then click download) and saved in your extensions directory. The $wgSimpleFormsUseAjax global configuration variable must then be set to the relative URL of the location you saved the Javascript. Your SimpleForms inclusion code in your LocalSettings.php file should then look something like the following example,
 * You may need to change the filepaths to suit your own set up
 * Don't forget to ensure that the Javascript file is readable by the webserver

SimpleForms parser functions
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 some parser functions, which allow forms to be made and posted results captured using normal wikitext notation.

#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 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 will only render when editing an article, or when creating a new article from the CreateArticle specialpage. 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 them consuming their own magic.

Input types
In addition to the normal input types list text, image or checkbox, there are the following additional types and properties:

type=select: this is used for dropdown selection lists instead of having a dedicated #select parser function.

type=textarea: this is used for textareas instead of having a dedicated #textarea parser function.

type=submit: this does the same as usual, but can also be combined with method=ajax to make the form submission asyncronous.

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

SimpleForms index.php parameters
The SimpleForms extension adds a number of extra parameters to index.php which allows articles to be updated and created directly from HTTP requests without having to process HTML content. Following is an explanation of each of the additional parameters available.

content
The SimpleForms extension offers the ability to specify wikitext content directly in the posted data or query string using the content parameter. 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.

If the content parameter is used without any title parameter, then it will be parsed and the result returned without any article being access at all. This feature is used by the search example shown below. If there is a title parameter, but the article doesn't exist, then the article will be created from the content (subject to the $wgSimpleFormsAllowCreate variable). And finally if there is both a content and title parameter and the article does already exist, then what happens to the content depends on the caction (content-action) parameter which is described below.


 * 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).
 * Currently the content query-item does not work with action=raw
 * There is a MediaWiki API under development to allow adjustment of content via the request variables inherently, which this extension will make use of when it is ready.

caction = replace | append | prepend
The content item can be used with another item called caction (content-action) which defines how the content should be incorporated into an existing article specified by the title parameter.
 * replace (default)
 * prepend
 * append

templates = update
This query-string parameter is usually used with action=raw to cause the raw wikitext to have its double-braces (templates, variables and parser-functions) expanded first.

The SimpleForms extension allows the templates parameter to also be used with content. The only applicable value for the templates parameter when used with content is update which causes any templates in the content update their counterpart in the current content. Ant template having no match, will be appended. Any having more than one match will cause SimpleForms to try and reduce the matches to a single result by comparing values of the first named parameter. The following table helps to illustrate this. In this example, the content supplied has an unambihuous match with the bar template definition which gets replaced.

In this case the content has been appended because there were no template matches.

''Here all the templates match by name, so an attempt is made to reduce this ambiguous state by comparing the first parameters, in this case the "name" parameter which matches "Jane". The contact entry for "Jane" gets replaced, the phone number has been removed because it was not supplied in the new content. If none of the first parameters matched, the update would be appended to the article as in the previous example.''

''This example shows content to update containing more than one template definition (both the items from the previous two examples). As can be seen, the result is the same as if the two were processed one at a time, i.e. the first updates the "Jane" entry, and the second appends since there's no unique match.''

summary
If a more specific edit summary is preferred to the default, then it can be supplied in this parameter.

minor (not done yet)
If any changes are made, they will be marked as minor edits.

pagename
If the content parameter is used without a title parameter, then the returned page containing the parsed content will, by default, have no title, but if a title for the page is desired it can be set using this parameter. The search-form exmaple below uses this feature to add a "search results" title to the page.

username
If the client is autoauthenticated as being the server (The requesting IP address is one of those contained in the $wgSimpleFormsAllowRemoteAddr array), then it can be changed to a different name by setting this parameter. This allows the server to forward edits to the wiki from other sources and protocols on behalf of the wiki users.

returnto
Set this to an article title that should be returned after processing the request, this is useful if the page being updated is very large and doesn't need to be returned.

Ajax example
This example renders a form with a dropdown list containing all the categories in the wiki, when one of them is selected and the submit button clicked, an Ajax request is generated which returns a list of all articles in the selected category. This list is then put into the content of a div element below the form. To see the example working, see 18 June 2007. Here's the wikitext source of the example,

empty list The first hidden value, action=render tells MediaWiki to return only the rendered wikitext, but not any skin or other surrounding HTML (see Manual:Parameters to index.php for more info on the render parameter).

The second hidden value, content contains the DPL query which produces the list of article in the category. Notice that the curly braces have to be changed to &amp;#123;'s and &amp;#125;'s so that the wikitext query can be assigned to the hidden value without being parsed prematurely by the wiki parser.

The last input, with type=ajax works just like a normal submit button, but will work asyncronously using Ajax. the update parameter is used to direct the content of the server response to the element having id of "listcat-result" which is the div below the form.

Improved search form
This example uses SimpleForms to create a replacement searchform which allows DPL queries and has additional buttons for sending the search to Wikipedia or Google. You can put it in a template and embed it in any article from which you'd like to have a form for finding articles. If your side bar is made from wikitext (see Extension:Tree view for info about how to do that) then you can replace your wikis searchform.
 * You'll need to replace the URL's with ones appropriate for you own wiki's setup
 * Go to OrganicDesign wiki to see this example in use.

Change log

 * Version 0.2.0 (2007-06-18): added Ajax functionality using MooTools
 * Version 0.1.1 (2007-06-16): returnto parameter added
 * Version 0.1.0 (2007-06-15): templates parameter working
 * Version 0.0.9 (2007-06-11): Rendering of content without associated title working
 * Version 0.0.3 (2007-05-10): Main form and input parser-functions working, ready for basic use