Creating boilerplates

From Aeon Garden Software Wiki
Jump to: navigation, search

What is a boilerplate?

Having something like word processing document templates would be very convenient in wiki editing, but in MediaWiki, a template is a related but distinct and more advanced concept. And while MediaWIki templates are certainly useful, they don't provide the same kind of convenience as a document template. Boilerplates, named after the concept of boilerplate text, and are essentially the same as a word processing document template.

In essence, say you have a type of article that always includes the same infobox and has the same structure. It is possible to create a template for such articles that format the entire page, but that isn't generally how wikis operate and wouldn't be desirable in all cases anyway. This is because a change to the template affects all pages that use it, which can be useful but also can limit flexibility to deal with special cases. But having editors starting all such articles from scratch and merely asking them to follow a set structure doesn't work so well when editors don't know about it.

Boilerplates provide a middle ground. They allow editors to easily get boilerplate text into their source edit boxes that sets up the common page structure, but changing the boilerplate later doesn't affect any existing pages like changing a template would. Editors experienced with the difference between transcluding and substituting templates can consider boilerplates more or less a way to do substitution right at the edit page level without saving, though boilerplates are less feature rich.

Where to write boilerplate text

Like templates, boilerplates are really just articles when you come down to it. In this case, they use the <boilerplate> tag to separate the actual boilerplate text from anything else in the article, like categories you want the boilerplate itself in.

Also, like templates, boilerplates have their own namespace. Just as you would likely create, say an infobox template for an item, at Template:Item infobox, you would create a boilerplate for an item article at Boilerplate:Item boilerplate. All articles created in the Boilerplate namespace will appear in the BoilerRoom selector that appears when editing the source of pages, and this is the only way currently to get articles listed in the selector.

But the BoilerRoom box can use any page on the wiki as a boilerplate, just as any page on a wiki can be used as a template.

The source of a boilerplate article

The following demonstrates the structure of a boilerplate article:

Header text describing the boilerplate may be placed here, as well as any other wikicode.
It will appear when directly viewing boilerplates and when transcluding them like templates.
<boilerplate> Text here is simply ignored and will not appear.
This line is where the boilerplate text begins.

<boilerplate>
Since only the first opening and last closing tags are considered,
boilerplate tags inside the boilerplate text are treated as plain text and will be
included as part of the boilerplate without modification.
</boilerplate>

<includeonly> and similar tags are also treated as plain text within the
boilerplate tags and will be included in boilerplate text without modification, so it
even works well for providing a boilerplate (or multiple) for templates.
</includeonly>

This line is where the boilerplate text ends.

Whereas this text is simply ignored.</boilerplate>

You can place any footer text here you wish, and this is a good spot for any categories
you want to include the boilerplate article itself in. That can be done in the header as
well.

The green text is text that will appear when viewing the boilerplate page itself, but it isn't part of the actual boilerplate text. This is a good place for any documentation you might want to provide about the boilerplate itself.

The gray text will simply be ignored and won't show up anywhere except when editing the boilerplate page itself. This happens only with text on the same line after the first <boilerplate> tag and text on the same line before the last </boilerplate> tag. This text is deliberately ignored to make the actual boilerplate article easier to read; the actual boilerplate text will begin on its own line and end on its own line.

And so the black text is the actual boilerplate text. You can see it on the actual boilerplate page, but no templates, categories, links, or anything is processed there. It is treated as ordinary plain text when shown in the article. Note that all lines between the first <boilerplate> and the last </boilerplate> are considered part of the boilerplate text. This feature means you don't have to worry about any workarounds for certain characters; everything in the boilerplate text region is treated exactly as written. The example below demonstrates how this is useful.

An example: the meta-boilerplate

A simple example is to write a boilerplate for boilerplate articles themselves. Color coded as above, this is what such the source of a boilerplate might look like:

This is the meta-boilerplate, used for creating other boilerplates.
<boilerplate>
Boilerplate description
<boilerplate>
...
</boilerplate>
[[Category:Boilerplates]]

</boilerplate>
[[Category:Boilerplates]]

When the boilerplate text is requested when opening a page for editing, or while editing a page, this is what you get:

Boilerplate description
<boilerplate>
...
</boilerplate>
[[Category:Boilerplates]]

This demonstrates why considering only the first <boilerplate> tag and last </boilerplate> tag is useful. The <boilerplate> tags in the actual boilerplate text need no special workaround to be included. They can be included exactly as-is and are interpreted as nothing more than part of the boilerplate text.