Help:Transclusion/How Transclusion Works: Difference between revisions

Revision as of 16:40, 14 February 2021

Latest revision as of 08:42, 3 May 2025

(8 intermediate revisions by 6 users not shown)

Line 1:

To '''transclude''' anycontent from a '''source''' page (within a single MediaWiki project, (such as en:English Wikipedia), includeonto thea following''target'' page, use <code><nowiki>{{SOURCEPAGE}}</nowiki></code> in the '''target''' page:'s code.

Whenever a target page with this code (<code><nowiki>{{SOURCEPAGE}}</nowiki></code>) is renderedincluded on a target page, the engineWikiMedia willsoftware includeretrieves and embedes the entire content of <code><nowiki>SOURCEPAGE</nowiki></code> in(i.e., {{Fake link|Template:SOURCEPAGE}}) at that ___location on the target page.

<code><nowiki>{{SOURCEPAGE}}</nowiki></code>

=== Example ===

Whenever a target page with this code (<code><nowiki>{{SOURCEPAGE}}</nowiki></code>) is rendered, the engine will include the entire content of <code><nowiki>SOURCEPAGE</nowiki></code> in the target page.

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 <code><nowiki>{{B}}</nowiki></code> 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).<div style="margipadding: 0.5em;">[[File:Transclusion-multiple-foo.svg]]</div>

In the example below, let us start with target page '''A''' and <code><nowiki>SOURCEPAGE</nowiki></code> '''B'''. <br />

If '''B''' is transcluded in '''A''', then the engine will include ''in that place'' not the code (<code><nowiki>{{B}}</nowiki></code>) itself but the content of source page '''B''' (which consists of only one word, foo).

=== How it works ===

The top row shows how the target page '''A''' renders, while the bottom row shows the code required to transclude the source page within the target page. Note that the position of the code determines how each of the target pages '''A''', '''P''', and '''Q''' will render.

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.

The source page content foo will not be highlighted nor boxed on the target page.

=== Edit source pages with caution ===

<div style="margipadding: 0.5em;">[[File:Transclusion-multiple-foo.svg]]</div>

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]].

A typical use case for transclusion would be if you wanted to place the same welcome message on multiple newcomer talk pages.

Transclusion creates a "live" link between the template page and the target page(s) upon which the template's contents should appear. When the template is edited, the rendering of that template on the target pages is updated as well. Let's say you create a (template) page in Wikipedia with the address of a local Wikimedia event. Next, you transclude that template on your talk page, and also on the talk pages of all local editors to be invited. A week later, the event is moved to a slightly larger place. You would then update the address template, and the ''revised'' address will automatically appear on all the other attendees' pages.

Breaking existing transclusions in a template is called '''breakage'''. It is to be avoided if possible, as the break will propagate through every target page in which the template (source) page was transcluded.