Using Wikibooks/Advanced Techniques

Templates

We already mentioned templates briefly in our section on tagging. Now we're going to get into some of the more advanced features of them. Templates, their features, and their uses is a huge topic of discussion and is far too big for the scope of this book alone. The book Editing Wikitext will include more information about Templates than this book does, but even that isn't comprehensive resource. The best way to learn is to see other templates in action, or to ask some of our active users for help and see what solutions they come up with.

Templates have several benefits. First is that templates help to hide large, complex features from the page. That means that when new users contribute to a page, they don't need to dig through large quantities of formatting first. Second, templates can be used to apply very similar markups to multiple pages (or to multiple points in a single page) without having to copy and paste large amounts of code. Finally, through the use of parameters, templates can help to automate many tasks that otherwise would need to be performed by hand.

Templates are a special case of including pages. To include, or transclude, a page in the current one, the syntax is {{namespace:page name}}. For the main namespace, you leave the namespace part blank and just use {{:page name}}. The default namespace is Template:, so just putting in {{page name}} will try to include Template:page name, which is good if you are using templates.

Try including a page in the sandbox, E.g. include the main page using

{{:Main Page}}

This is how print versions of books are created. Each page is included in order on the print version page. Anything that shouldn't show up on the print version is put between <noinclude> </noinclude> in the code of the pages being included, which stops it being included when the page is included in another one. This is used to hide the navigation links and other stuff that only people looking at the book online would be interested in. Conversely if you want something to only appear for people viewing your print version, you use <includeonly> </includeonly>.

Templates use the same idea, only for different purposes and with some added features. An example of a simple template, which is used with just {{page name}}, could be

{{incomplete}}

which makes

This is an example of a standard template just to save time. Tags like this can also be used to generate lists of books which are incomplete. If you go to Template:incomplete and click on the "What links here" link in the toolbox, the pages which have "(inclusion)" listed after them are pages which have included the template. For the {{incomplete}} template, an editor could use this to get a list of pages which are incomplete.

When you type {{incomplete}}, you are actually including the code from Template:incomplete, which looks like:

'''The text in its current form is incomplete.'''

That's pretty boring. You can use <includeonly> ... </includeonly> to mark sections of a template that should appear when transcluded, but should not appear on the template page itself. You can use <noinclude> ... </noinclude> to mark sections that should not be included. You can use this, for instance, to include the template in one category, but include pages that template is transcluded onto in another category. You can also display documentation on the template page about proper use of the template, without that documentation appearing everywhere you use the template. So if you wanted someone who went to look at the template page for {{incomplete}} to see what its purpose was after "The text in its current form is incomplete." you could replace the code with

'''The text in its current form is incomplete.'''
<noinclude>
'''Purpose:'''
:This template is used to designate a page as incomplete
</noinclude>

which would show people

The text in its current form is incomplete.

Purpose:

This template is used to designate a page as incomplete

When they looked at the template page but only The text in its current form is incomplete. when they included it.

You can also be tricky with your categories:

<includeonly>
'''The text in its current form is incomplete.'''
[[Category:Pages that are incomplete]]
</includeonly>
<noinclude>
'''Purpose:'''
:This template is used to designate a page as incomplete
[[Category:Templates that do tricky things]]
</noinclude>

Template Parameters

The {{Message Box}} template is a little more complex because it uses parameters. Parameters are values which a template will use when making its code for a page including it. When you include Template:Message_box, You need to pass it parameters. If you just do

{{Message box}}

you get

Huh? This template actually has 2 parameters which we need to pass arguments to. If we include the template like

{{Message box|heading = hello|message = goodbye}}

you get

When including Templates, you don't need to worry about spaces or capitalizing the first letter, but the page names are still case sensitive for all the other letters, so if you type

{{Message Box|heading = hello|message = goodbye}}

you get

Because of the "Box" instead of "box".

Back to the example... heading and message are the names of the parameters of Template:Message_box. The actual code for the template looks like

<center class="metadata">
<table style="width: 60%; background: {{{backgroundcolor|transparent}}}; border: 1px solid #aaa; padding: 0.5em;"><tr>
<td style="width: 70px;">[[Image:{{{image|Wikibooks-logo.svg}}}|60px|{{{alt|logo}}}]]</td>
<td>'''{{{heading}}}'''<br /><small>{{{message}}}</small></td>
</tr></table>
</center>

Wow, now that is complicated. Everything with three pairs of braces around it is a parameter. So there are 5 parameters, which are backgroundcolor, image, alt, heading, and message. The first 3 parameters have pipe characters in them. These create default values for the parameters, so that even if we only pass values for heading and message, the background is still transparent, the image shown is still the Wikibooks logo and the alternate text of that image is still "logo". If a parameter doesn't have a default value and you don't pass a value to it, it just shows the parameters name in 3 pairs of braces, which is why it made {{{heading}}} and {{{message}}} the first time.

But that doesn't mean we can't change these values. Say we want to get a green background, with a smiley image, and the alternate text "smile", with the same heading and message we used last time. To get this you would type

{{Message box|backgroundcolor = green|image = Face-smile.svg|alt = smile|heading = hello|message = goodbye}}

and get

It doesn't matter what order you pass arguments to the parameters in, as long as they are named. It does matter if the parameters use numbered parameters like {{{1}}}. If the parameter is numbered then you need to put it in the right place, so if it is {{{1}}} it would be the first value you pass.

The only thing limiting what you can achieve with templates is your imagination and your knowledge of HTML and CSS (used to make things look pretty), as well as a knowledge of variables and parser functions. That, and the template limits of the mediawiki software to avoid large workloads on the server, but this only really matters if you are transcluding a page which transcludes a page which transcludes a page, and will probably only bug you if you are a book writer trying to sort all your pages into chapter pages, and then trying to include those chapter pages in a print version, or something like that. When you try to include a page which includes other pages and it goes over the include limit, a link will just be placed onto the page pointing to the page you wanted to transclude, and I think there is some kind of error message generated in the HTML code as a comment.

Advanced Editing

There are a number of advanced tools that an editor can use to create better pages and templates. Many of these features are extensions to the MediaWiki software. New extensions can be added to Wikibooks, on occasion. If you can think of a feature that we don't have here, you can check out the list of available extensions on Mediawiki.org. Before anything gets installed, however, you need to get community approval on the Technical Reading Room.

Extensions that We Can't Get

There are a number of extensions that Wikibookians have asked for in the past, but that we cannot have installed. Frequently, this is because of performance issues: Some extensions take up too many server resources. Sometimes, it's because of security: some extensions just haven't been rigourously tested enough to go live on a big site like Wikibooks. Here is a list of extensions and functionality that we have asked for and have not been able to get:

DPL

We do have an old version of DPL installed, but the new version has many more options and much more power. Unfortunately, all that power comes at the price of increased server load. Until the efficiency of this extension goes up, we are unlikely to see an upgraded version here on Wikibooks.

GNU LilyPond

Lilypond is an extension for allowing all sorts of LaTeX-based markups, including graphics, music, etc. Unfortunately, this extension has multiple components, many of which have not been rigourously security-tested.

StringFunctions

Like the parser functions, these are parser hooks that can be used to manipulate string data. This includes tokenizing, manipulating, etc. This extension also requires too much server power, and so it can't be installed here on Wikibooks.

HTML and CSS

Wikitext is converted to HTML by the MediaWiki software. We use wikitext because it is easier to read and edit than plain HTML. However, there are plenty of occasions where we need to use HTML and CSS to perform a variety of tasks.

CSS Classes

Here are some common CSS classes that are used around wikibooks. Making use of these classes in your own work will help to keep everything standardized, and can save a lot of effort if you are trying to duplicate complicated styles.

PrettyTextBox

PrettyTextBox is a CSS class that produces a box with a grey background and a grey border. Examples of this textbox are {{SideBox}} and {{TextBox}}. A common implemention of this is <div class="PrettyTextBox">...</div>.

wikitable and wikitable

These classes are used for tables that are similar to the PrettyTextBox color theme, above. The regular table cells are grey, header cells are darker grey, and all the cells have a grey border around them. This format is commonly used in many places, such as The Reading Room.

metadata, noprint

These classes cause items on your page not to appear when you print a book. This is useful for certain message or note templates that are intended more for writers than for readers.

printonly

Like those above, but opposite. Objects with class printonly will only appear when you print a page, but will not appear when you view the page online.

plainlinks

When you create an external link, the software automatically includes a little icon next to the link to indicate what type of resource that link points to. Using the plainlinks class will hide these little icons.

Parser Functions

Parser functions are powerful but complicated. They are best served in the template namespace, where their complexity can be hidden from people who edit books and pages. Using parser functions in a book page will make the code more difficult to read and understand. Therefore, the page will be more difficult for regular contributors to edit. The version of the parser functions that we have is not the complete, nor the most recent version. Documentation for our version is located here:

http://www.mediawiki.org/wiki/Help:Extension:ParserFunctions

We do not have the "Extended" version of the parser functions, nor the "StringFunctions" extension, nor any of the other related extensions.

Math Tags

Visit the sciences, math, or engineering subject pages, and you are likely to see mathematical formulae. These are rendered using a LaTeX variant specifically designed for mathematics. You can see the complete markup help sheet at meta:Help:Displaying a formula. A more comprehensive version of this page can be found on meta and Wikipedia.

Dynamic Page Lists

Dynamic page lists (DPL) is an extension that automatically generates a list of pages based on the category and namespaces of those pages. Complete documentation for our version of DPL (which is not the most recent version, see the note above) is located at:

mw:Extension:DynamicPageList/old

This feature is used mostly on organizational pages, such as the Wikibooks stacks, and other places. It is not commonly found in books, but it can be.

Flattening DPL Lists

DPL Lists, by default, appear in a vertical bulleted list. However, using the CSS class DPLFlat we can force the list to be horizontal instead. For example:

<div class="DPLFlat"><dynamicpagelist>...</dynamicpagelist></div>

This use is demonstrated on {{New}}.