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 not all of its consequences may 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 content from a source page (within a single MediaWiki project, such as English Wikipedia) onto a target page, use {{SOURCEPAGE}} in the target page's code.

Any time the code {{SOURCEPAGE}} is included on a target page, Wikipedia software places the entire content of SOURCEPAGE into that spot on the target page.

Example

Consider an example, complemented by the illustration below, with target pages A, P, and Q, and source page B.

If source page B is transcluded into A, the content from B (for instance, the word "foo") will appear in place of the {{B}} code in page A. When transcluded, this content is not highlighted or boxed on the target page – it is integrated directly into the page's text (highlighted here only for illustration).

How it works

Transclusion creates a 'live' link between a source page and all target pages where its content is transcluded to and used. Editing the source page automatically updates its content on all target pages that include it.

For example, if you create a source page with details about a Wikimedia event and transclude it onto the talk pages of 50 editors you wish to invite, any updates you make to the source page (such as changing the event location) will immediately reflect on all 50 talk pages.

Edit source pages with caution

Edits to a source page can impact all target pages using it. If a source page also contains its own transclusions from other source pages, avoid changes that may break these links, as this would affect the source page you are editing and all target pages that transclude it. This is known as 'breakage', and it is best to ensure any updates maintain the integrity of transcluded content across all pages. For example, Main Page is a large page that transcludes its content from multiple embed source pages such as Wikipedia:Today's featured list.

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