From Ocean Teacher Library

Adding data

Adding data is usually structured as a two-step process: first the user inputs a page title, and then he/she is sent to a form for either adding or editing that page, depending on whether or not the page already exists; this ensures that users don't accidentally overwrite existing pages. 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.
The two-step process

There are two ways to let users add data in this way:

• Use 'AddPage' - the user can go to /Special:AddPage; a form name can optionally be specified in the URL, so it looks like /Special:AddPage/form-name. If no form name is specified, a dropdown of all available forms in the wiki will appear next to the input for the page name, letting the user choose. (This approach is no longer recommended.)

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. If you're using the 'forminput' tag, the "query_string" value should include 'namespace=namespace-name'. If you're using 'AddPage', you can do so by setting the URL to something like "http://mywiki.com/Special:AddPage/form-name/Namespace:namespace-name".

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=How do I add and edit data using Semantic Forms?". 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 be created 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 field:

• '<TemplateName[FieldName]>' - gets replaced with the value for the specified field in the specified template
  * '<unique number>' - 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 "<unique number;start=1>". Note that the parameter is delimited by a semicolon.

For example, the form described above could have a declaration of "page name=<Item[Author]> opinion item <unique number;start=1>". This would include the author's name in the name of every opinion item, as well as a number to guarantee the uniqueness of every opinion-item page added. A user could then go to the URL "http://discoursedb.org/wiki/Special:AddData/Item" and fill out the form; if they set the author to be "Ernest Hemingway", and no other opinion items in the wiki had him as an author, then hitting the "Save page" button would result in a new page called "Ernest Hemingway opinion item 1".

Note that users must be sent to the page "Special:AddData/form-name" for this automatic page-setting to work; if they go instead to the regular form page, or to "Special:AddPage", they will be prompted for a page name, which will override whatever the automatic page name would be. (Though it should be noted that you can also change the form page to link to "Special:AddData/form-name", in place of having the #forminput input.)

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

link_text

The first, second and fourth arguments work much the same way that their equivalents in "#forminput" work (see above). The "link_type" 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 blank or anything else, it will show up as a regular link.
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" field, 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 an 'AddPage' or 'AddData' 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.
  * Similarly, you can add a value for a specific field to the URL query string for 'AddPage' or 'AddData'.

The 'edit with form' tab

There are two ways to get the 'edit with form' tab to appear for specific pages:
Based on category

The first, and recommended, way, is to use categories. To enable a page to have a tab in this way, you must first define that page as belonging to a specific category - categories are the standard Semantic MediaWiki approach to defining a page's type. The best way to match pages with a category is to place a 'Category' tag inside the main template that defines this page type; that way, every page that uses this template will become part of this category.

Once you have done that, you should place the semantic property 'Has default form' in the page for that category; the tag should look like Form:form-name. You can do this automatically if you create the category using the 'CreateCategory' page.

As an example of this approach, see the "Magazine" template source code on Discourse DB, which defines any page that includes it to be of category "Magazines"; then the "Magazines" category source code, which specifies the "Magazine" form as the default form for this category. Then, see the page for Newsweek magazine, which uses the "Magazine" template, and thus belongs to category "Magazines", and thus gets an "edit with form" tab at the top; this tab then links to editing with the "Magazine" form. And there you have it.
Based on namespace

The second possible way is to match the pages' namespace to a form. You can do that by placing a 'Has default form' property in the page defining that namespace. If, for instance, your wiki is called 'MyWiki', and the namespace you want to associate with a form is 'User', the page in which you need to add the property will probably be called 'MyWiki:User' (you may need to create this page). If the namespace you want a default form for is the main one (i.e., the one with no name, you will need to create and add this property to the page called 'MyWiki:Main', or whatever the main namespace is called in the language of this wiki. Once you've added this property, every page within that namespace will have that form associated with it, unless it already belongs to a category that has an associated form (categories take precedence over namespaces).

If a user is not allowed to edit a page that is form-editable, the tab will show up for them as "view form" instead; clicking on the tab will show the disabled form.
Configuring the editing tabs

For pages that have an "edit with form" tab, you may want the regular "edit" tab to be renamed or even removed altogether. There are flags you can set in either "LocalSettings.php" or "SF_Settings.php" to change the appearance of the editing tabs:

• $sfgRenameEditTabs - renames the "edit with form" tab to "edit", and the "edit" tab to "edit source" (in whatever language the wiki is being viewed in)
  * $wgGroupPermissions[...]['viewedittab'] - can be set, for different types of viewers, to toggle whether each type will see the regular edit tab. One common modification is to set it to false normally (i.e. for viewer type '*'), and to true for 'sysop' viewers.

If these settings are added to LocalSettings.php, they should be placed in the file after the include of Semantic Forms.
Pointing red links to 'add data' form

On 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 this article to the wiki using the standard edit form. However, if such an article is the object of a semantic property, it's possible to get such a link to point to the correct Semantic Forms 'add data' form instead.

This is done in one to three parts:

• if your version of MediaWiki is older than 1.13, you must make a small modification to a file in the main MediaWiki code - the code change can be found here.

• you can add the semantic property 'Has default form' (see "The 'edit with form' tab") to the page for the property that such an article is the object of.

• if it's possible for a property to point to more than one kind of page (i.e., pages that should be created with different forms), you can also add one or more 'Has alternate form' properties to that page, so that the user gets other possibilities when they click on the red link.

You can set either a default form, or alternate forms, or both, for a property.

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 made that MediaWiki code change, and 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.

Sometimes, when a page with red links is first created, the red links will point (incorrectly) to the standard edit URL, and not to the form URL; the correct URL will only appear at some point later. That happens because of caching on the wiki. You can very easily disable caching, if you want to get around this problem; see the instructions here.

References

The content of this page uses material from the article Extension:Semantic Forms published by Semantic MediaWiki (retrieved on 2008-07-28).
This article is licensed under the GNU Free Documentation License.