Extension:Page Forms/Linking to forms

How do you get users to forms? The standard way is via the #forminput parser function call, which displays a single input for users to enter the name of a page; if they enter such a name and click the button, they are sent to a form to create that page - unless a page with that name already exists, in which case they are sent to a form for editing the existing page. This is what is known as the "two-step process". The reason for the initial step, of having the user first enter the page name, is to ensure that users don't accidentally overwrite existing pages. This process is so standard that it is built into the default forms produced by Semantic Forms' "Special:CreateForm" and "Special:CreateClass" helper pages: any form-definition page created by Semantic Forms includes, at the top, a call to #forminput, so that users who go to that form page can automatically start to use the form.

However, it's also possible to skip the first step, if the form contains a formula for setting the page title based on the user input; this is the "one-step process", which uses the parser function #formlink instead of #forminput.

The two-step process
The two-step process, i.e. the standard way to get users to forms, is done using the #forminput parser function.

Using #forminput
Here is a the syntax of the #forminput parser function:



All arguments are optional. An explanation of the parameters:
 * - the name of the SF form to be used; if it is left empty, a dropdown will appear, letting the user choose among all existing forms.
 * - the size of the text input (default is 25).
 * - the starting value of the input (default is blank).
 * - the text that will appear on the "submit" button (default is "Create or edit page").
 * - the set of values that you want passed in through the query string to the form. It should look like a typical URL query string; an example would be "query string=namespace=User&User[Is_employee]=yes".
 * - adds autocompletion to the input, using the names of all pages in a specific category.
 * - adds autocompletion to the input, using the names of all pages in a specific namespace (only one of these two can be used).
 * - specifies that autocompletion values should be retrieved dynamically the server, instead of directly from a list of values hidden in the page's HTML (thus allowing many more values)
 * - opens the form in a popup window.

Adding pages of a specific namespace
You can have a page-input form create pages within a specific namespace (like 'User:') by default, without forcing users to type in that namespace every time. To do that, add 'namespace=namespace-name' to the "query string=" parameter.

Adding sub-pages
In MediaWiki, you can create sub-pages by including a slash in the page name. To have the page that's added automatically be a sub-page, you can add a value for "super_page=" in the query string. To make it a sub-page of the current page, you can set this value to "super_page=". This will prepend a "current-page-name/" onto the beginning of the page name that the user types in.

The one-step process
You can have the name of the page created by the form to be set automatically, by adding a "page name" parameter within the form definition's "info" tag. There are two types of "variables" one can include in the value for this parameter:
 * '< TemplateName[FieldName] >' - gets replaced with the value for the specified field in the specified template.
 * ' ' - by default, gets replaced by the lowest number for which the page title that's generated is unique. Normally, this value starts out as blank, then goes to 2, then 3, etc. However, one can manually set the starting number for this value, by adding a "start=" parameter; this number must be 0 or higher. For instance, to have the number start at 1 and go upward, you should set the tag to be "  ". You can also instead set it to be a random six-digit number, by adding the "random" parameter, so that the tag looks like "  ". Note that the parameter in either case is delimited by a semicolon.
 * Note that the "page name=" value cannot start with " " (due to a bug in Semantic Forms), and cannot contain the character "#", because MediaWiki does not allow pound signs in page titles.

For example, imagine a form for storing notable quotes. Its tag could have a parameter of "page name= quote ". This would include the author's name in the name of every quote page, as well as a number to guarantee the uniqueness of every opinion-item page added. A user could then go to the URL " http://mywiki.com/Special:FormEdit/Quote " and fill out the form; if they set the author to be "Ernest Hemingway", and no other quotes in the wiki had him as an author, then hitting the "Save page" button would result in a new page called "Ernest Hemingway quote 1".

The "start" value can have leading zeroes; a value of "001", for instance, would lead to pages that had the value "001", then "002", etc.

The "page name=" value gets parsed by the MediaWiki parser, so you can also add parser functions, pre-defined variables, etc. into the value.

Note that users must be sent to the page "Special:FormEdit/form-name" for this automatic page-setting to work; if they somehow end up at a #forminput call and are prompted for a page name, that name will override whatever the automatic page name would be.

Using #formlink
If you want, you can generate this link using the "#formlink" parser function, instead of creating the URL directly. This function is called as:



The " ", " " and " " arguments work much the same way that their equivalents in "#forminput" work, and " " works like " " (see above). The " " argument sets the display of the link: if it's set to "button", the link will show up as a button; if it's set to "post button", it will be a button that sends the query-string value(s) using "POST" instead of via the URL - this is helpful when a lot of data has to be preloaded, and it is more robust with special characters like line breaks in the query string; if it's set to blank or anything else, it will show up as a regular link. The " " parameter shouldn't usually be used, but it sets the "target" page to be edited, if you want to link to the editing of a specific page. The " " parameter displays a "tooltip", displayed if a user hovers the link.

An example call to #formlink would be:



This will link from the page, via a button, to a form, and specifically the form's "Summary" tab (assuming you've set up tabs in the form using the Header Tabs extension).

You may want to have the link to the form be an image, instead of text or a button. For that, you could call something like:

Pointing red links to a form
In MediaWiki, links to nonexistent pages are called 'red links', because they are usually colored red. By default, these links go to a page for adding the article to the wiki using the standard edit form. However, if the red link results from a new value for a semantic property, it can point to the correct Semantic Form to add the page.

The standard way to point red links defined by a property to a certain form is to simply add the special property 'Has default form' (see "The 'edit with form' tab") to the page for that property.

Setting the default form can be done directly within the 'CreateProperty' page.

In addition, or instead, you can also add one or more 'Has alternate form' special properties to the property page, so that the user gets other possibilities when they click on the red link.

As an example, see this page. Both the author and the source are red-linked, but the links take you to forms for adding these two pages (please do not actually fill out and submit these forms, because that would ruin the example). When you get to the forms for each page, you can see, at the top, that there are alternative forms that you can select for adding each page. That is enabled by 'Has default form' and 'Has alternate form' properties in the pages for both the properties 'Was written by' and 'Was published by'.

Note also that, if you've defined a namespace as having a default form, red-links that go to a page within that namespace will also go to the right 'add data' form, without any extra work needed.

By default, Semantic Forms checks, for every red link, for the existence of properties across the wiki pointing to that page in order to find default forms. However, for pages with a large number of red links, this can slow down page loading. If that's an issue for you, you can change the behavior so that SF only checks properties on the page in question, instead of throughout the whole wiki. To do that, add the following to LocalSettings.php, after the inclusion of Semantic Forms:

Populating red-linked pages automatically
It's nice to have red links point to the right form for creating the page, but this still calls for work on the part of users - they have to click to the form, fill out the fields and save the page. This is especially bothersome when the form contains few or no fields, and/or if there are many such pages to be created. You can instead have such red-linked pages get automatically created by the system.

To do this, instead of using "Has default form" or "Has alternate form", you should add the special property "Creates pages with form" to the property that you want pointing to those automatically-created pages. For instance, if you have pages that point with the property "Has country" to other pages, and you want those other pages to automatically be created using a form called "Country". You just need to add the following to the "Has country" property's page:

Creates pages with form::Country

It should be noted that it may take a while for each page to be created, since page creation is done through MediaWiki "jobs", which can take anywhere from a few seconds to several hours or more to run, depending on the length of the job queue.

Preloading data
You may want a form to already contain some data when the user goes to it. (Note that this only applies to adding new data; for editing an existing page, there is no way to set the contents of the form to anything other than the current contents of that page.) There are various ways to do this:


 * Specify a "default" value for whatever fields you want to have a value for in the form.
 * Specify a "preload" page for the "free text" input, which will preload the free text field with the contents of that page.
 * Add 'preload=preload-page-name' to the 'query string=' value in the 'forminput' call; this will preload the entire form with the contents of that page.
 * Similarly, you can add a "preload=..." value to the query string for a 'FormStart' or 'FormEdit' URL.
 * Add "template-name[field-name]=field-value" to the 'query string=' value in the 'forminput' call, to set the value for a specific field. To preload values for more than one field use "&": "template-name[field-name-1]=field-value-1&template-name[field-name-2]=field-value-2"
 * Similarly, you can add a value for a specific field to the URL query string for 'FormStart' or 'FormEdit'.
 * Finally, you can create your own custom handling, using the 'sfEditFormPreloadText' hook. If another extension calls this hook, it can preload data however it wants. The function registered with this hook should have a header like "function-name(&$page_contents, $page_title, $form_title)".

Modifying pages automatically
You can create links that, when clicked on, create or edit pages automatically in the background, with a preloaded set of values, using the #autoedit parser function. This function is called, and is displayed, in a very similar manner to #formlink - the difference is that the link only performs an action in the background, instead of bringing the user to a form. The syntax for #autoedit is:



All these parameters but 'reload' work in the same way as they do in #formlink; 'reload', if added to the call, reloads the current page after the link is clicked.

As an example, let's say you want to create a simple voting scheme, letting users vote between "Vanilla", "Chocolate" and "Strawberry". You have a page for each, and each one contains a template called "Flavor", with a field called "Num votes" - that field, in turn, sets a semantic property called "Has number of votes". And there is also a form, also called "Flavor", to edit such pages. To create a link that, when clicked, increments the number of votes in the "Vanilla" page by one, you could place the following call on the page:



This functionality is also available via the MediaWiki API, as the "sfautoedit" action - this enables outside scripts, and bots, to easily modify template calls within wiki pages. You can find the full documentation on this by searching for "sfautoedit" here.