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

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

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.

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

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