User:Badon/Extension:Semantic Forms/Manual/Multiple values for the same field

Multiple values for the same field

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

The generic call for this function is:

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

The function splits the 'value' by the 'delimiter', then for each one, it applies the same mapping that 'formula' does to 'var', 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|}}}|,|var|[[Has author::var]]}}

Essentially this function maps the property tag onto each comma-delimited value in the field. The user can thus enter all the values for the "author" property in the same form field, with or without spaces around the commas. For example each of these lines would work the same when entered by the user, with or without spaces after the commas:

• Stephen King, William Faulkner, Aldous Huxley, Anne Frank
• Stephen King,William Faulkner,Aldous Huxley,Anne Frank

The 'delimiter' defaults to a comma "," and 'new_delimiter' defaults to a comma followed by a space ", " if they are not set. The following example is equivalent to the first example, but specifies the 'new_delimiter' as ", " using an w:ISO-8859-1 entity number for the space (see also:HTML character entities :

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

If 'formula' is something that is expected to produce no visible output, such as a category, then the 'new_delimiter' must be specified as empty, like this:

{{#arraymap:{{{author|}}}|,|var|[[Category:var]]|}}

Note that "var" is used in arraymaps as an internal variable. If the property name itself contains "var", that will lead to problems, and you should replace "var" with some character or string that does not appear in the property name, for example "VariableValue" or "@@@@".

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 added to the generated template.

arraymaptemplate

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, create a template that takes in a single field 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 both #arraymap and #arraymaptemplate, the escape character 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

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:CreateTemplates really should be defined somewhere other than in Semantic Forms. However, again there is no current plan to move them.