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 Templat
this
is
SPARTAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
207669487] which consisted of a collection of transcluded lead paragraphs from several main articles.
Markup
There are three pairs of tags that can be used in wikitext to control how transclusion affects elements of a template or article. They determine whether or not wikitext renders, either in its own article, which we will call "here", or in another article where it is transcluded, which we will call "there".
- <noinclude> this content will not be rendered there </noinclude> . These tags have no effect here.
- <includeonly> this content will render only there, and will not render here </includeonly> (like invisible ink made visible by means of transclusion).
- <onlyinclude> this content will render here and will render there </onlyinclude> but the rest of the article will be excluded from rendering there.
There can be several such section elements. Also, they can be nested. All possible renderings are achievable. For example, to render there one or more sections of the page here use <onlyinclude> tags. To append text there, wrap the addition in <includeonly> tags above, within, or below the section. To omit portions of the section, nest <noinclude> tags within it.
As a memory aid insert the phrase in transclusion between the two words to get "noInTransclusionInclude", "includeInTransclusionOnly" and "onlyInTransclusionInclude".
- See, for example, the wikitext of the wiki news thread.
Selective transclusion
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 transclude one section from a template or document into one page, and another section from the same template or document into another page, that's selective transclusion, which 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.
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 is 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! ( | 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.
- 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:Substitution (the opposite of transclusion)
- Wikipedia:WikiProject Modular Articles
- Bugzilla:Request for template transclusion from Commons (interwiki templates, etc.)