Wikipedia:Transclusion

From Wikipedia, the free encyclopedia
Jump to: navigation, search
Shortcut:

Transclusion means the inclusion of the content of one document in another document by reference. In Wikipedia transclusion, the MediaWiki software will refer to the content of one page, the template, for inclusion into the content of any other page, the target page. Similar to the way any page name can become a link by placing its name in double square brackets, any page name can become a template by placing it in double curly braces, {{Namespace:Pagename}}. Changes made to the template are then automatically reflected on all pages into which that page has been transcluded (though a purge may sometimes be necessary).

If the template's page name does not begin with a namespace, it is assumed to be in the Template namespace. To refer to a page in the "Main" (article) namespace, it is necessary to prefix it with a colon (:). Examples:

What will transclude from a page can be controlled with the tags <include>, <onlyinclude> and <includeonly> placed in the source page wikitext. (See markup, below.) The use of tags enables the template to transclude partially, otherwise the double curly braces will always transclude all content. For selective transclusion the <includeonly> parts of the template are named (with the help of parser functions) and that template is then called with the parameter transcludesection=name.

Transclusion events occur every time the page is loaded, when the template is rendered. Another use of the same mechanism is a one-shot substitution of the template call itself with its transcluded source page. A template call {{fullpagename}} with the "subst:" prefix {{subst:fullpagename}} is transcluded once but never again, because the wikitext of that call is replaced (substituted) when its page is saved. What was a one-time template call becomes the actual wikitext of the template at the time of its call.

How transclusion works

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

{{SOMEPAGE}}

Whenever the target page A with this code is rendered, the engine will include in that place not the code itself, but the entire content of the source page B, SOMEPAGE.

Transclusion-multiple-foo.svg

For example, you might decide to place a welcome message on every newcomer's Talk Page. Transclusion creates a "live" link between the template-page and the target-page(s) upon which the message should appear. When the template is edited, all the target-pages are edited too.

For example, you create a (template) page in Wikipedia with your home mailing address and then include that template not only on your page, but all your friends' pages, too. Later, after moving to a new house, you then update your address template and the new address will automatically appear on all your friends' pages.

Applications of transclusion

The most common application of transclusion is in the use of templates. However, other pages are also sometimes transcluded, mainly within project space.

Composite pages

The wikitext of a page may (partly or fully) consist of tags for the inclusion of component pages. The component pages are usually not in the template namespace, and are often full pages in their own right. Composite pages are intended to gather the material on them into a central location.

Examples are:

This allows the choice between viewing the component pages separately or together. Viewing a composite page is convenient when there are many small, related component pages, in that it allows an overview of all the components without the effort of following numerous links.

In general, each component page and the composite page are treated separately. While the actual changes on the component pages will be transcluded onto the composite page, the edit history, recent changes, page-watch settings, page protection, TOC, "what links here" link, and other features of the composite page do not reflect or affect the histories, watch settings, protection levels, what links here lists of the component pages. The composite page is a page in its own right. The talk page of a composite page is used to talk about the composition and the page in general, not the component pages, though it in turn could be a composite of the talk pages of the component pages.

Editing a section of a component page can be done directly from the composite page, see editing sections of included templates. After saving, one ends up at the page for the component page to which the section belongs.

On projects with the interlanguage link feature the composite page shows the combined interlanguage links of all component pages, hence possibly multiple links for one language or even for one page.

See also Wikipedia talk:Template namespace/Archive 1#transcluding prose.

Pages with a common section

When two pages need to discuss the same material in the same way, they can share a section. This involves creating a third page and transcluding that page onto both pages. This third page may be a page in its own right or a subpage of either of the other two, and if the first it may be placed in the same namespace as the other pages or in template namespace. Common sections like this should be marked with an explanatory header, and/or given a special layout, to inform the reader that this section of the page is in a different location, since transcluding shared article sections can easily confuse novice editors and readers alike if left unmarked.

This can be very useful when two disambiguation pages share content, or a list page and a disambiguation page share content (see third example below).

Examples:

Repetition within a page

On pages where there is a lot of repetitive information — various kinds of lists, usually — it is sometimes useful to make a template that contains the repeating text, and then call that template multiple times. For example, Template:EH listed building row is used repeatedly to construct tables in many articles.

Simple repetition of the same text can be handled with repetition of a parameter in a single template: e.g., {{3x}}, where {{3x| howdy!}} produces howdy! howdy! howdy!.

For more information on repetition see also m:Help:Recursive conversion of wikitext.

For more information on the current template system, see Wikipedia:Template namespace.

Partial transclusion

By using "noinclude", "onlyinclude" and "includeonly" markup, it is possible to transclude part of a page rather than all of it. Such partial transclusions can also be achieved by transcluding from other pages such as subpages. It is often useful not to transclude some information, such as template documentation.

For an example of how this technique can be applied to simplify the creation of summary articles, see how History of pathology [1] was transcluded into Pathology,[2] which consisted of a collection of transcluded lead paragraphs from several main articles.

Markup

There are three pairs of tags involved in cases where rendering should differ between the wikitext and 1) its preview rendering, and 2) its transclusion rendering. Tags are the invisible elements that affect how a page renders. Let's call a preview "rendered here", and a transclusion "rendered there".

A transcluded page name is no different than its preview. But the tags pair-off to demarcate sections that will affect differences. Each tag name will describe its invisibility exception to transcluding the whole page named.

<noinclude>material invisible there </noinclude>
<includeonly>material invisible here </includeonly>
<onlyinclude>material outside this section invisible there </onlyinclude>

"Only" is not a term to reckon with because it means "only there" in the one, but "only this" in the other.

There can be several such sections. Also, they can be nested. All possible differences between here and there are achievable. The one example is a content editor who picks an onlyInclude section and takes a noInclude section out of that, picks out yet another onlyInclude section to append to there, while none of this effects their article in any way. The other example is the template programmer who will includeOnly the code section and noInclude the documentation section of a page. A mis-example is the user page includeOnly section: it might "comment out" sections here, but such invisible ink may prove to be troublesome, and transcluded the comments would be revealed commenting on nothing.

NoInclude as a name about transcluding is pretty straightforward. A mnemonic for the other two transclusions there is: InclusionONLY; and Yet Another ONLYInclusion.

Selective transclusion

Shortcuts:

Selective transclusion is the process of partially transcluding one selected section of a document that has more than one transcludable section. As noted above, if only one section of a document is to be transcluded, this can be done by simply surrounding the section of interest with <onlyinclude> … </onlyinclude> tags, and transcluding the whole page. However, to selectively transclude one section from a template or document into one page, and another section from the same template or document into another page, requires a way to:

a) uniquely mark each transcludable section in the source document; and
b) in the target document(s) (those to show the transcluded sections), a way to specify which section is to be transcluded.

This section describes how to accomplish this.

Labeled section transclusion

Labeled section transclusion uses mw:Extension:Labeled Section Transclusion which is enabled on all Wikimedia wikis. See Help:Labeled section transclusion for how it works. The following subsections are about a more complicated way to make selective transclusion without using the extension.

Source document markup

Insert the following line into the "source" document (the one from which text is to be transcluded), immediately preceding the first line of each section to be transcluded, substituting SECTIONNAME (twice) with the unique name of the respective section. The section name can be any identifier and must be unique within that document:

<onlyinclude>{{#ifeq:{{{transcludesection|SECTIONNAME}}}|SECTIONNAME|

End each such transcludable section with:

}}</onlyinclude>

Target document markup

To transclude a section marked as above into another page (the "target page"), use the following line on that page, substituting PAGENAME for the "source" document from which text to be transcluded, and SECTIONNAME with the name of the section you want to transclude:

{{PAGENAME|transcludesection=SECTIONNAME}}

Thus each section enclosed within <onlyinclude> … </onlyinclude> tags will always be rendered when the transcludesection parameter is not set (when the document is viewed ordinarily, or when the document is transcluded without setting the transcludesection parameter as shown below), and will be rendered by transclusion on any page that does set transcludesection to the section's name. It will not be rendered by transclusion that uses the transcludesection parameter but sets it to anything other than the name of the section.

Also, when providing PAGENAME, without providing a Namespace, the wiki will assume that the PAGENAME belongs in the Template Namespace. To transclude from a Mainspace article, use :PAGENAME.

{{:PAGENAME|transcludesection=SECTIONNAME}}

Example

If we want to make the "Principal Criteria" and "Common Name" sections of WP:TITLE be independently transcludable, we edit the WP:TITLE page and enclose the "Principal Criteria" section as follows:

<onlyinclude>{{#ifeq:{{{transcludesection|principalcriteria}}}|principalcriteria|
...
(text of "Principal Criteria" section)
...
}}</onlyinclude>

Similarly, we enclose the "Common Name" section with:

<onlyinclude>{{#ifeq:{{{transcludesection|commonname}}}|commonname|
...
(text of "Common Name" section)
...
}}</onlyinclude>

Then, to transclude the "Principal Criteria" section into another page, we insert into that page:

{{WP:TITLE|transcludesection=principalcriteria}}

To transclude the "Common Name" section into another page, we insert into that page:

{{WP:TITLE|transcludesection=commonname}}

Of course, the same page can transclude two or more sections this way by including multiple such lines.

There is no limit to how many selectable sections for transclusion a document can have. The only requirement is that each transcludesection be given a value that is unique within that page.

Subpages

One can cut and paste the text to be transcluded into a subpage, then use the name of the subpage in the transclusion template. This approach can only be used with subpages from User, Talk or Wikipedia pages; currently, subpages cannot be created from main article pages.

Example: you want to discuss the deletion and redirecting of Pussycat to Cat. First, create the subpage Talk:Pussycat/Let's delete Pussycat!, write your comment into it, then transclude it in Talk:Pussycat and Talk:Cat using the template {{Talk:Pussycat/Let's delete Pussycat!}}. Comments posted in either talk pages will be shown in both. To ease editing of the subpage, it may be helpful to precede the transcluded talk with {{lat}}, e.g. Talk:Pussycat/Let's delete Pussycat! (edit|article|history|links|watch|logs). Transcluding in this way will not preserve a fixed record of the discussion at the time of any archiving, so discussions should be closed in conjunction with archiving. An alternative is to centralise discussion in the normal manner on a single talk page and point to it using by substituting {{Pls}} templates, per WP:MULTI.

Special pages

Some pages on Special:Specialpages can be transcluded, such as Special:Allpages, Special:Prefixindex, Special:Newfiles, Special:Newpages, Special:Recentchanges and Special:Recentchangeslinked. Samples:

  • {{Special:Allpages/General}} – a list of pages starting at "General"
  • {{Special:Prefixindex/General}} – a list of pages with prefix "General"
  • {{Special:Newfiles/4}} – a gallery of the four most recently uploaded files
  • {{Special:Newpages/5}} – a list of the five most recently created pages
  • {{Special:Recentchanges/5}} – the five most recent changes
  • {{Special:Recentchangeslinked/General}} – recent changes to the pages linked from "General"

Except for Special:Recentchangeslinked, the slash and the word/number after the slash can be omitted, giving a list of pages without a specific starting point, or a list of the default length.

Note: Transcluding certain special pages (such as Special:Newpages) can change the displayed title of the page.

Pages related to MediaWiki transclusion

Templates

See also