Wikipedia:Transclusion costs and benefits

There are some concerns that the template transclusion feature of the MediaWiki software may not always be used wisely. Transclusion is a simple idea, but all of its consequences may not be immediately apparent to users with a less technical background. Although templates make many tasks easier, there are risks associated with their use—as there are with any tool. Therefore there is a cost that is paid for the benefits of templates. This includes a direct cost in terms of increased machine resources; because of this, template limits are imposed by the software. Even within those limits, there are some additional costs. This article is an explanation of these costs and benefits.

Transclusion background

To transclude any source page (within a single MediaWiki project, such as en:Wikipedia), use the following code in the target page:

{{SOURCEPAGE}}

Any time you write the code ({{SOURCEPAGE}}) in a target page, you are telling Wikipedia software to put the entire content of SOURCEPAGE in the target page.

In the example below, look at target page A and SOURCEPAGE B.

If B is transcluded in A, Wikipedia software will include in that specific place not the code ({{B}}) itself but the content of source page B (which is just the word foo).

The top row shows how target pages A, P, and Q will look with the changes in code seen in the bottom row to transclude source page B. Note the position of the code in each example target page.

The source page content, foo, will not be highlighted or boxed on the target page. (Foo is in a light blue box here for ease of illustration and understanding.)

Transclusion creates a "live" link between a source page and the target page(s) where the source page's contents appear. This means that when you edit a source page, you will be updating its content across all the target pages that include it. Let's say you create a source page in Wikipedia with the address, date, and time of a local Wikimedia event that you want to invite 50 local editors to. Next, you transclude the invitation source page onto your talk page as well as the talk pages of the other 50 editors. A week later you discover the place for the event must be moved. You would then update the source page, and the new address will automatically appear on all the other attendees' talk pages. You could also tell the editors to invite people you may have missed. They could then simply transclude the invitation source page into other editors' talk pages themselves.

Remember to be extremely careful about editing any source page, especially if it contains transclusions from other source pages. Breaking existing transclusions in a source page is called breakage. Please avoid breakage(s) because not only the larger source page you are editing and all the target pages that include it will be affected. So will both the already embedded (now broken) source page that was used to add content to the larger source page, as well as every target page where the embedded source page was transcluded.

Costs and benefits

Further information: H:TRANSDRAWBACKS

Transclusion is a tool, and like any tool, provides benefits and incurs costs. The exact values of these costs and benefits vary according to wise or foolish design and use, and is the subject of debate. It is not possible to pretend that anyone can give a perfectly neutral statement of these costs and benefits; both are largely subjective and extremely difficult to measure.

Social

There is a social cost of transclusion, the total expectation over time of the risk that a transcluded template page may be vandalized. If a popular template's content is replaced by gibberish, that same gibberish may momentarily appear on every page in which the template is transcluded—just as would any edit. This also adds to the burden borne by the engine—as does any edit. Most very heavily used templates are protected to prevent vandalism usually with this.

Offsetting this cost is the fact that template vandalism is as easy to revert as to commit. The offending material is removed and the former content restored. There is, again, another imposition on the engine.

If a great deal of text, appearing on many pages, is kept in a template and transcluded in all of the targets, then there are some savings in storage, but generally there is little, if any, benefit to the machine granted by transclusion.

Users, however, may find transclusion very useful, and in many ways, some of them quite unexpected. Almost any type of text, markup, HTML or CSS code can be transcluded; if that text or code is used in several places, templates make manual labor much easier. Not only that, but by reducing errors in otherwise repetitive typing, templates help to lower Wikistress and reduce the amount of janitorial work.

Comparison

A basic principle of graphic design—of almost any design—is to standardize presentation. For example, if on several pages it is thought to be desirable to present a certain list of items, then all such lists should look alike. Even if the items vary somewhat from page to page, there is often a clear advantage to making them appear similarly.

There is no technical reason to do this, as the engine will function just as well if every list is a little bit different from the last. But a standard appearance contributes greatly to a professional impression on human readers. Changes to the mere layout of the lists are easy to implement across all occurrences of the list by simply changing the layout as opposed to changing every list.

The same Wikipedia logo and other basic site navigation elements, for example, are all transcluded onto every page in order to create a consistent look and feel across millions of pages. Changes to the logo, navigational, or other language elements of the site can be performed from a central location and take effect on every page at the cost of rendering time for every page. However, this social functionality outweighs the resource costs of maintaining the uniform look.

Double transclusion

Since almost any page can be transcluded, why can't we transclude one page in another, and then transclude that page in a third? The answer is, we can.

Some master templates are designed to be used with other subtemplates. When master template B is transcluded within target page A, the subtemplate C is transcluded, too.

Since both links are "live", if the subtemplate is edited, the target page is also changed. This could be carried even further; page C could transclude some page D, and the content on page A would be an instance of triple transclusion. When page D is edited, page C changes, so page B changes, so page A changes—right on down the line.

Geometric effect of multiple transclusion

Costs and benefits of double transclusion increase geometrically (in a loose sense of the term). Say a template X is transcluded on 5 other templates; and say each of those templates is itself transcluded on 5 target pages. The template X is doubly transcluded onto 25 pages. An edit to X appears on a total of 31 pages: X, the 5 templates, and the 25 targets.

There is no limit to the number of targets for a given template, nor to levels of transclusion, so it is possible that X be doubly or triply transcluded over hundreds, thousands or even millions of pages. Thus double transclusion is extremely powerful and the technique in itself has become an object of dispute.

How substitution works

MediaWiki provides the subst: command, which simply substitutes one page within another. This is very different from transclusion, although the difference will usually be invisible on the first edit.

To substitute a page, use this code instead:

{{subst:SOMEPAGE}}

(The same syntax applies as in the case of transcluded pages.)

When you preview a page containing a substitution, you will still see the code in the edit box; you can change it if you like. But when you save the target page, the engine substitutes, or replaces, the code with whatever is on the source page. If you edit the target again, then you will see that the substitution code is gone; the content of the source page has replaced it directly.

The link from the target to the source is not merely broken; it does not exist at all. Now, if the source page changes, the target page will not change. The substituted content is frozen in time, in the form it had at the moment the page was saved.

Substitution and transclusion can be used together, and often this is a good idea. Instead of using double transclusion, you might substitute one page in another, then transclude that page in a target page. Or, you might find that a page transcludes another; you choose to substitute the transcluding page in a target, rather than force a double transclusion.

On the other hand, double transclusion can be very useful, and may be justified or even demanded in certain contexts. Each case is different, and can only be decided after careful, informed consideration of the technical and social situation.

Tagging

A very common use of templates is to "tag" a page—to insert on it some snippet of text, often boxed, often seen at the very top or bottom of a page. A tag does not contain content, but metacontent: information about the page itself. An example is {{FAC}}.

There are hundreds of tags, each with a different function, many transcluded onto hundreds of pages. Thus tags represent a non-negligible fraction of server resources devoted to transclusion (conversely, tags are, by design pretty lightweight - offsetting the number of transclusions). Many tags include category references, which automatically include pages on which they are transcluded within a category.

Article pages are rarely transcluded, so tagging them presents few problems—the same goes for Talk pages, Wikipedia namespace pages, and indeed most pages. When a page is so tagged, the tag appears only in that one place; if it refers to "this page", it is clear what is meant.

However, Template namespace pages are intended to be transcluded and substituted, so tagging them—for any reason—is problematic.

• Whatever tag is applied to a template page is applied to every target where the template is used. If the tagged template is substituted, then the transclusion code of the tag will "fall out loose" into the markup of the target page—including any category reference. This results in such inanity as users being nominated for deletion. Note that modern template design has largely obviated this problem.
• No matter whether the tagged template is transcluded or substituted, it may be visible on the target for all to see. This may be embarrassing, destructive, annoying, or merely appear childish. Depending on the text of the template so tagged, it may be quite impossible to see, when looking at the target, what has been tagged. In general, the casual reader will have no idea what is meant.
• Any text or markup may be transcluded, within very broad bounds; and some templates are highly technical, especially those intended as sub- or master templates, with nested parameter calls, or used to manage other templates. Altering even a single character within such a template may not only cause it to break, but cause a cascade of broken templates and damaged pages. Tagging such a template almost guarantees it will no longer function as intended.
• Tagging templates is a class of double transclusion, at the least; if either tag or template are already involved in double transclusion, the result—as seen on a target page—may be triple or quadruple transclusion. All the costs of double transclusion apply in these cases, and may be intensified.

There are cases in which tagging a template may be less destructive; however, it is very difficult to isolate them—to ensure that a tag will cause no problems.

Therefore: Most tags should not be placed on most Template namespace page bodies. If a certain tag seems to apply to a template, there are various options: sometimes the tag can be placed on its associated Talk page or /doc page (if any), or it can be <noinclude>d onto the template. Some tags, such as {{tfd}}, are specifically designed to be visibly included on templates in order to draw editorial attention.

Other kinds of inclusion

Other types of markup and engine function also cause content to be included in a rendered page, similar in effect to transclusion or substitution:

• Images are transcluded in rendered pages.
• Signatures and datestamps (generated with multiple tildes) are substituted in pages when saved.

  If the signature markup contains a template call, the template call is substituted and the template contents transcluded on each appearance of the sig. If the signature markup contains an image call, the image is transcluded on each appearance. Template calls are currently (2011) prevented from being included in signatures by the software configuration.

• The main site logo Image:Wiki.png is on every page rendered with some skins. All pages transclude some standard links and text.

See also

• Help:Transclusion
• {{User transclusion}} and {{User copy and paste}} – userboxes for declaring one's stance on transclusion
• Wikipedia:Avoid using meta-templates
• Previous discussions on this topic
  • Wikipedia_talk:Template namespace/Archive 1#transcluding prose
• Help:Substitution
• Wikipedia:Template limits
• Wikipedia:Don't worry about performance