Transclusion means the inclusion of the content of one document in another document by reference. In Wikipedia, it refers to a function of the MediaWiki software that allows the content of one page to be included in the content of another page, by placing a reference to the source page in the wikitext of the target page. Changes made to a page are automatically reflected on all pages into which that page has been transcluded. A page that is intended to be transcluded into other pages is called a template.
The basic syntax used to produce transclusion in wikitext is {{Namespace:Name}}, which will be replaced by the content of the page named Namespace:Name when it is rendered on the user's display. If the referenced page name does not begin with a namespace identifier (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:
- {{Like}} will transclude from the page Template:Like - specifically: Like
- {{Stochastic processes}} will transclude from the page Template:Stochastic processes
- {{:Calculus}} will transclude from the page Calculus (in the Main namespace)
- {{WP:Assume good faith}} will transclude from the page Wikipedia:Assume good faith
It is also possible to pass parameters to a template, using the expanded syntax described at Help:Template, which can affect what text in the template is rendered. For example, to highlight text like this, the text-to-be-highlighted is passed as a parameter to the highlight template: {{highlight|this}}
.
An alternative to transclusion is substitution, whereby the current content of the template is automatically copied into the wikitext of the target page on saving, and will then be an indistinguishable part of the saved page, independent of any later changes made to the template. The syntax for this is {{subst:Template name}}
How transclusion works
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.
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:
- m:Help:A simple composite example
- Wikipedia:Village pump with six component pages, e.g. Wikipedia:Village pump (technical)
- A daily page like Wikipedia:Votes for deletion/Log/2005 May 31 where each component page consists of the discussion on the deletion of one Wikipedia page, e.g. Wikipedia:Votes for deletion/Sp3tt (for this day there are 75 such component pages)
- m:Meta:Translation/Coordination, mainly containing
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.
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:List of Languages calls Template:Lang def repeatedly with different parameters in order to generate the visible text.
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.
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.
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.
- m:Help:A simple composite example
- Wikipedia:MediaWiki namespace
- m:Help:Variable
- Wikipedia talk:Template namespace#transcluding prose
Templates
See also
- Wikipedia:Transclusion costs and benefits
- Wikipedia:Purge (to force transclusion of newly updated templates)
- Wikipedia:Substitution (the opposite of transclusion)
- Wikipedia:WikiProject Modular Articles
- Bugzilla:Request for template transclusion from Commons (interwiki templates, etc.)