Extension:Semantic Forms/Semantic Forms and templates

From MediaWiki.org
Jump to: navigation, search
Semantic Forms - navigation (view)
Basics Main page (talk) · Download and installation · Quick start guide · Hosting · Special pages
Using Semantic Forms SF and templates · Defining forms · The "edit with form" tab · Linking to forms · Creating query forms
Resources for help Common problems · Known bugs and planned features · Getting support · Developers' documentation
About Semantic Forms Authors and credits · Version history · Sites that use Semantic Forms · Related extensions

Semantic Forms is, at its heart, a system for editing template calls within wiki pages. (Though it can also edit page sections.) See Help:Templates for a full explanation of templates within MediaWiki.

Why does Semantic Forms support editing templates and page sections, but not, say, free-form Semantic MediaWiki property tags within pages? That's because the philosophy of Semantic Forms is that all true data in MediaWiki - including semantic data, category information and anything else - should be stored within templates. That's for several reasons:

  • templates provide a clear guideline for what information belongs in which pages, avoiding ambiguity about the data structure
  • templates hide the complex syntax involved in displaying and storing information, making editing easier
  • templates allow for easier changes to the structure and display, since a change across a large group of pages can potentially be done just in one place, instead of requiring edits to all of them.

Multiple values for the same field[edit | edit source]

Semantic Forms makes one main contribution to the operating of templates: it defines the parser functions #arraymap and #arraymaptemplate, which provide support for having multiple values for a single field, delimited by a comma or other character. These parser functions "map" some text processing onto each value. In the standard case, what is mapped is a Semantic MediaWiki property tag - but "Category" tags, "Image" tags, and other, more complex processing are also sometimes done.

#arraymap and #arraymaptemplate can also be used outside of a template context. In fact, the ideal place for these functions to be defined might be in the ParserFunctions extension, or even in core MediaWiki itself. At the moment, however, there is no plan to move these functions.

arraymap[edit | edit source]

The generic call for this function is:

{{#arraymap:value|delimiter|variable|formula|new_delimiter}}

The function splits the 'value' by the 'delimiter', and then, for each one, applies the same mapping that 'formula' does to 'variable', and finally joins all the values again using the 'new_delimiter'. For example, if you have a form that populates the field 'author', and you want the values for that field to be separated by commas and to each get the semantic property 'Has author', you could add the following to the template code, in place of a regular semantic tag:

{{#arraymap:{{{author|}}}|,|x|[[Has author::x]]}}

Essentially this function 'maps' the property tag onto each comma-delimited value in the field. (The 'delimiter' parameter defaults to "," and 'new_delimiter' defaults to ", " (note the extra space) if they are not set.) The user can thus enter all the values on the same line, with or without spaces around the commas. (Note, by the way, that the "x" is used here as an internal variable: if the property name itself contains the letter "x", that will lead to problems, and you should replace the letter "x" with some character or string that does not appear in the property name, like "@@@@".)

The 'new_delimiter' parameter is especially helpful if none of the resulting values are actually displayed, because by default such a thing would show up as a string of commas. A common example of that is if the original value holds a list of category names, and each name gets turned into a category tag, but is not actually displayed. To avoid displaying commas in that case, you should set the 'new_delimiter' value equal to a space, using something like " ", the HTML encoding for a space. (Using just "| " at the end won't work, because the MediaWiki parser will ignore it.) Here is how such a thing would be called:

{{#arraymap:{{{categories|}}}|,|x|[[Category:x]]| }}

If you use the 'CreateTemplate' or 'CreateClass' pages to create a template, and you specify that a field that can take more than one value, then an #arraymap call will be automatically added to the generated template.

arraymaptemplate[edit | edit source]

There are some kinds of mapping that are complex enough that they cannot be placed in the #arraymap function. For this purpose, you can instead use the similar #arraymaptemplate function.

To use this function, first create a template that takes in a single field (it should be referred to in the template as {{{1}}}) and applies the mapping you would like to that field. Then apply #arraymaptemplate onto the main template field just as you would with #arraymap, using the following format:

{{#arraymaptemplate:value|template|delimiter|new_delimiter}}

...where 'template' is the name of the mapping template in question.

For example: to display a (comma-separated) list of authors as a numbered list, you could first create a template called "Numbered author", with the following contents:

# [[Has author::{{{1}}}]]

...then call the following:

{{#arraymaptemplate:{{{authors|}}}|Numbered author|,|\n}}

\n delimiter[edit | edit source]

For both #arraymap and #arraymaptemplate, the string "\n" in the value of either 'delimiter' or 'new_delimiter' will get converted into a newline. It should be noted that, if you want an actual line break to appear between values, you should have two newlines (i.e, "\n\n") as the delimiter, since MediaWiki requires two newlines in order to display a line break.

Template-based special pages[edit | edit source]

Semantic Forms defines three special pages that relate to templates: Special:Templates, which lists all the templates in the wiki, and Special:CreateTemplate and Special:CreateClass, both of which can be used to generate templates automatically. As with the #arraymap and #arraymaptemplate functions, there is a case to be made that Special:Templates and Special:CreateTemplate really should be defined somewhere other than in Semantic Forms. However, again there is no current plan to move them.