Jump to content

Help:Transclusion

Page semi-protected
From Wikipedia, the free encyclopedia

"WP:TRANS" redirects here. For other uses, see WP:TRANS (disambiguation).
For broader coverage of this topic, see Transclusion.

Transclusion means the inclusion of the content of one document within 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 <noinclude>, <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 by 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.

Transclusion runs in advance of parsing the target page at the HTML layer, so it is possible to emit syntax fragments—even fragments of entity references, such as "&a" and "mp;"—that will parse successfully as combined text in the target page. As a design idiom, this tends to violate the principle of least surprise, so it should be used sparingly, when cleaner solution paths do not present themselves. Emitting fragments of template syntax, such as a pair of opening braces, is unlikely to successfully re-parse as template syntax in the target page. Even if this worked, it would be unwise to depend upon this as supported behaviour, unless formally documented.

Additionally, it is possible to transclude content from Wikidata into other wikis.

How transclusion works

Note: this section is transcluded from Help:Transclusion/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.

Transclusion syntax

The general syntax for transclusion on Wikipedia is {{Namespace:Pagename}}, where Namespace:Pagename describes the title of a Wikipedia page.

Using transclusion syntax requires some knowledge of page titles. On Wikipedia, non-article pages have titles with a visible namespace and pagename separated by a colon; for example, the page Wikipedia:Tips has Wikipedia as the namespace, and Tips as the pagename. But encyclopedic articles only have a visible pagename in their titles: for example the article Potato has Potato as the pagename, and the namespace, called main namespace, is not visible.

  • The wikitext {{Namespace:Pagename}} will transclude the page titled Namespace:Pagename. For example, if a page has the wikitext {{Wikipedia:Notability}} in it, it will transclude the page Wikipedia:Notability into it. Please note that {{WP:Notability}} would do exactly the same thing, as WP: is a namespace alias, which is automatically translated by the Wikipedia servers to Wikipedia:.
  • If the namespace is omitted, but the colon is included, like {{:Pagename}}, the encyclopedic article Pagename will be transcluded. For example, {{:Notability}} will transclude the article Notability.
  • If both namespace and colon are omitted, like {{Pagename}}, the Template:Pagename will be transcluded. For example {{Notability}}, and also {{Template:Notability}}, will both transclude the Template:Notability.

So, in summary, an example page having the wikitext {{Pagename}} or {{Template:Pagename}} included, will transclude the Template:Pagename into that example page. But {{:Pagename}} will have a different effect: it will transclude the article Pagename. Also, {{Namespace:Pagename}} will transclude the page Namespace:Pagename, for pages with titles of that format. You also have the option of using template parameters and transclusion modifiers.

Subpages

Subpages are pages separated with a "/" (a slash) from their 'parent' page. For a parent page with the name format Namespace:Pagename, its subpage name would have the format Namespace:Pagename/Subpagename. This feature is disabled in the main, file, and MediaWiki namespaces, but not on their corresponding talk namespaces.

To transclude a subpage:

  • The general syntax is {{Namespace:Pagename/Subpagename}}.
  • On the parent page of a subpage, it is either the general syntax or {{/Subpagename}}.
  • For a template namespace page, it is either the general syntax or {{Pagename/Subpagename}}.
  • Article subpages are disabled on this wiki, but would otherwise be {{:Pagename/Subpagename}}.
  • You also have the option of using template parameters and transclusion modifiers

For example, to transclude Template:Like/doc, it would be either {{Template:Like/doc}} or {{Like/doc}}. Note that subpage names are case sensitive, and {{Like/Doc}} would not work.

Template parameters

Further information: Help:Template § Parameters
For a quick guide to templates, see Help:A quick guide to templates.

The most common application of transclusion is the transclusion of templates. Templates are pages that are written with the prime objective of being included in other pages, either through transclusion or substitution. As shown above, the usual syntax for transcluding a template titled Template:Pagename is {{Pagename}}. However, some templates can also use parameters. Parameters are variables that can be given values (also termed arguments) that can be passed on to certain templates in order for them to work in different ways. Templates can either use no parameters, a fixed number of parameters, or a variable number of parameters. The number of parameters a template can use is from one upwards.

The exact syntax for using parameters with templates can vary greatly, depending on the actual template being used. But, for an example template titled Template:Pagename, which happened to use three parameters, the general form would be:

{{Pagename|parameter1|parameter2|parameter3}}

Shortcuts

with each parameter being substituted with a value, or a parameter name=value, when used in practice. Notice that each parameter is separated with a vertical bar. Parameters that take the form value are called unnamed or positional parameters. Parameters that take the form parameter name=value are called named parameters. With unnamed parameters, the first, second, third etc. parameters are equivalent to parameters '1', '2', '3' etc. in template documentation. Unnamed parameters must be in the correct order, and best placed before named parameters. An example of the syntax using the Template:Collapse top:

{{Collapse top|This is the title text|This is a custom warning line|left=true}}

In this particular example, three parameters are used, but Template:Collapse top can actually use a variable number of parameters. This is the title text and This is a custom warning line are the values of unnamed parameters '1' and '2'; and true is the value of the named parameter left.

For more details, see Help:Template. Also, see Wikipedia:Template index for a list of links to available Main Namespace related templates (usually for encyclopedic articles); and other Namespace related templates (usually for non-article pages); there is also a search function. Template parameters are also used in the parametrization method of selective transclusion.

Substitution

Substitution has a similar double curly-bracket syntax, and its action is similar to transclusion. When you preview a page with substitution wikitext in it, its action is identical to transclusion. But when you save a page with substitution wikitext in it, it differs in that it substitutes that wikitext with the actual wikitext of the template.

For example, when {{subst:Like}} is saved, it would substitute that wikitext with the actual wikitext from the Template:Like. In practice, the main difference that this makes is that if an update happened to the wikitext of the Template:Like, it would not update any pages where {{subst:Like}} had already been saved.

Magic words

Magic words are not examples of transclusion. But some have a similar double curly-bracket syntax and action to transclusion. For example, {{FULLPAGENAME}} renders the Fullpagename of any Wikipedia page. Like templates, some magic words can also take parameters, which are separated using a colon (:); for example {{FULLPAGENAME:value}}.

Templates do exist for some magic words, for example Template:FULLPAGENAME; but these just invoke the related magic word if passing parameters using a vertical bar (|); for example like {{FULLPAGENAME|value}}. But magic words parameters are best passed directly by using a colon, for example like {{FULLPAGENAME:value}}, which bypasses any templates.

Transclusion modifiers

As discussed above, with the example {{subst:Like}}, the subst: code alters the transclusion to substitution. This is a transclusion modifier, a type of specialist magic word for altering transclusion in some manner. Another example is {{:Notability}}, where the : (colon character) forces transclusion to the main namespace. There are additional transclusion modifiers such as safesubst:, int:, msg:, msgnw:, and raw:. For more details on their usage, see mw:Help:Magic words § Transclusion modifiers. Also see the modified commands #section:, #section-x: and #section-h: used for labeled section transclusion.

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

See also a 2005 Village Pump discussion on transcoding article prose as an unusual issue not covered by policy

Composite pages are made up of transcluded component pages, either in part or entirely. The wikitext of a composite page may include HTML tags to embed, or include, component pages. The components are typically full pages in their own right, and are usually not in the template namespace. Composite pages are intended to gather them into a central location for the reader.

Examples of composite pages:

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" links, 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; although 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 editing 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.

Pages with a common section

Shortcut

When two pages need to discuss the same material in the same way, they can share a section. For example, a section of an existing page may be transcluded on other pages. This may also involve 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 – except in article space, where subpages are not allowed (see WP:SUB). The third page may be placed in the same namespace as the other pages or in template namespace – again, except for use in article space, where templates should not store article text (see WP:TG). 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,[disputed – discuss] 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

Shortcut

By using <noinclude>, <includeonly> and <onlyinclude> markup, it is possible to transclude part of a page, rather than all of it. Such partial transclusions can be achieved by transcluding from any pages, including subpages. It is often useful to exclude part of a page in a transclusion, an example being with template documentation.

For an example of how this technique can be applied to simplify the creation of summary articles, see how part of the History of pathology (see the diff here) was transcluded into Pathology (see the diff here) using the {{:History of pathology}} markup. The Pathology article at that time (see here) mainly consisted of transcluded lead paragraphs and other sections from a number of articles. Look at the source to see how this was done. Since then, the Pathology article has been rewritten, and does not include all these transclusions.

Another example can be found in the transclusion of part of HitRecord (introductory paragraph only) into a same-named summary section in Joseph Gordon-Levitt.

Markup

See also: Help:Template § Noinclude, includeonly, and onlyinclude; and Help:Category § Categories and templates

In transclusion, a source page is transcluded into a destination page. But with partial transclusion, only part of that source page will be transcluded into a destination page. But in addition, what is transcluded to a destination page does not have to be visible on the source page.

Page rendering of a source page can be defined as the rendering of that source page when it is saved, which will be the same as the preview. We can call this rendering here.

Transclusion rendering of a source page can be defined as the rendering of a destination page that has a source page transcluded into it; but only that part of the destination page that was transcluded from the source page. The preview of the transclusion rendering will again be identical. We can call this rendering there.

There are three pairs of tags involved in cases where page rendering here should differ from transclusion rendering there. As described earlier, these are <noinclude>, <includeonly> and <onlyinclude>. These tags are invisible, but affect both page rendering here and transclusion rendering there. These tags pair-off to demarcate sections that will create differences. Each tag will describe exceptions to transcluding the whole page named. 

<noinclude>  This section is visible here; but this section is not visible there. Sections outside of these tags will be visible both here and there. </noinclude>

<onlyinclude> This section is visible here; this section is also visible there. Sections outside of these tags will be visible here, but will not be visible there. </onlyinclude> 

<includeonly> This section is not visible here; but it is visible there. Sections outside of these tags will be visible both here and there. </includeonly>
Wikitext What is rendered here (source page) What is transcluded there (destination page)
<noinclude>text1</noinclude> text2 text1 text2 text2
<onlyinclude>text1</onlyinclude> text2 text1 text2 text1
<includeonly>text1</includeonly> text2 text2 text1 text2

An important point to note is that <noinclude> and <onlyinclude> do not affect what is page rendered here at all, unlike <includeonly>. The <noinclude> tags stops text inside the tags being transcluded there, while <onlyinclude> has the opposite effect: it stops text outside of the tags from being transcluded there.

Only <includeonly> stops text from being page rendered here. But naturally enough it is transcluded there. Text outside of the tags will be both rendered here and transcluded there.

There can be several such sections. Also, they can be nested. All possible differences between here and there are achievable.

One example is a content editor who picks an <onlyinclude> section, and then takes a <noinclude> section out of that; but then picks out yet another <onlyinclude> section to append to there; but none of this affects their article in any way.

Another example is the template programmer, who will <includeonly> the code section and <noinclude> the documentation section of a page.

Selective transclusion

Shortcuts
See also: Template:Excerpt and Template:Transcluded section

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 a second page and/or a different section of the same 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. There are three ways of doing this: (1) Section header-based transclusion, (2) Labeled section transclusion, and (3) the parametrization method.

Standard section transclusion

Standard section transclusion uses {{#section-h:PAGENAME|SECTIONNAME}}. One can easily transclude the content within a section from one page to another using the ubiquitous headline-based section headers used throughout Wikipedia. To transclude the lead section of an article with this method, one can use {{#section-h:PAGENAME}}. This method is simpler than other selective transclusion methods, which require special markup in the source article or page to specify what content should be included or excluded.

Standard section transclusion may introduce a leading or trailing line break or newline, depending on the markup in the source and target pages. To prevent this, wrap the transclusion code in a {{trim}} template. For example:

  • To transclude the section of an article: {{trim|{{#section-h:PAGENAME|SECTIONNAME}}}}
  • To transclude the lead of an article: {{trim|{{#section-h:PAGENAME}}}}

Hatnote on the target page

To indicate on the target page where selectively transcluded content originates (its source), a {{Transcluded section}} hatnote must be placed at the top of the corresponding section in the target page where the content is being transcluded to.[a][b] Use either of the following, depending on whether the transcluded content is the entire section or only part of it:

  • If an entire section in the target page is transcluded the source: {{transcluded section|source=PAGENAME#SECTION}}, which renders as:
This section is transcluded from PAGENAME#SECTION. (edit | history)
  • If only part of a section in the target page is transcluded the source, specify |part=yes: {{transcluded section|source=PAGENAME#SECTION|part=yes}}, which renders as:
Part of this section is transcluded from PAGENAME#SECTION. (edit | history)

Hidden comment on the source page

It is recommended to include a hidden comment at the beginning of the transcluded section in the source page. This comment informs editors that the content is being used elsewhere and serves as a reminder to consider the broader audience when modifying the wording. Additionally, it helps maintain the integrity of the transcluded material on the target page. For example (replace [[PAGENAME#SECTION]] with the name of the target page):

<!-- The content of this section is transcluded to [[PAGENAME#SECTION]]. Please be aware that changes made to the original source here will affect the transcluded version on the target page mentioned. -->

No hatnote should be placed on the source page, in other words no hatnote is needed on the page being transcluded from, as readers do not need to know where else the content appears.

Using the labeled section method

Main page: Help:Labeled section transclusion

Labeled-section selective transclusion uses the parser functions listed in mw:Extension:Labeled Section Transclusion, which are enabled on all Wikimedia wikis, to selectively transclude content. See Help:Labeled section transclusion for how labeled section transclusion works.

Parametrization method

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.

Additional markup for selectively transcluded sub-article leads
Further information: Wikipedia:Summary style § Using excerpts for article synchronization

Per MOS:LEAD#Format of the first sentence, the first instance of the sub-article title should appear in bold in the first lead sentence of that article; this is often not desirable for a transclusion to a section of the parent article. In addition, the parent article is often wikilinked in the lead of a sub-article; when transcluded to the parent article, this wikilink will appear as bold text. The wikitext markup listed below can be used to address both of these problems.

To ensure that the article title is bolded in the first sentence of the sub-article, but unbolded and wikilinked in the transclusion to the parent article, make the following replacement in the sub-article's first lead sentence:

Replace
SUB-ARTICLE_PAGENAME
with
<noinclude>'''</noinclude>{{No selflink|{{var|SUB-ARTICLE_PAGENAME}}}}<noinclude>'''</noinclude>

If there is a wikilink to the parent article in the lead section of the sub-article, replacing the wikilink to the parent article with a {{no selflink}} template will ensure that it is wikilinked in the sub-article's lead but not in the transclusion to the parent article. In other words:

  1. If the wikilink to the parent article is not a WP:Piped link, replace [[PARENT_ARTICLE]] with {{no selflink|PARENT_ARTICLE}} in the sub-article's lead
  2. If the wikilink to the parent article includes a pipe (e.g., this link), replace [[PARENT_ARTICLE|Piped link wikitext]] with {{No selflink|PARENT_ARTICLE|Piped link wikitext}} in the sub-article's lead

Drawbacks

Shortcut
Further information: Wikipedia:Transclusion costs and benefits

Like many software technologies, transclusion comes with a number of drawbacks. The most obvious one being the cost in terms of increased machine resources needed; to mitigate this to some extent, template limits are imposed by the software to reduce the complexity of pages. Some further drawbacks are listed below.

Special pages

See also: Wikipedia:Special pages § Miscellaneous

Some pages on Special:Specialpages can be transcluded, such as AllPages, PrefixIndex, NewFiles, NewPages, RecentChanges, WhatLinksHere (see help page), and 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".
  • {{Special:Contribs/Larry Sanger|offset=20021108002158|limit=50}} – user contributions prior to November 2002, limited to 50.

Attempting to transclude {{Special:Categories}} will not result in an actual list of categories, but {{Special:PrefixIndex/Category:}} can be used for this purpose.

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

URL parameters can be given like template parameters:

  • {{Special:RecentChanges|namespace=10|limit=5}} – the five most recent changes in the "Template" namespace.
  • {{Special:PrefixIndex/Jimbo Wales/|namespace=2|stripprefix=1}} – the subpages for User:Jimbo Wales, but without the user page prefix.

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

Notes

  1. ^ No hatnote should be placed on the source page, in other words no hatnote is needed on the page being transcluded from, as readers do not need to know where else the content appears.
  2. ^ That is the hatnote should be placed below the header but above the content, per MOS:Layout.

See also

MediaWiki transclusion

Templates

Other

This page is referenced in the Wikipedia Glossary.
Retrieved from "https://en.wikipedia.org/w/index.php?title=Help:Transclusion&oldid=1255546870"