Help:Transclusion/How Transclusion Works: Difference between revisions

Revision as of 14:53, 3 November 2007

Latest revision as of 08:42, 3 May 2025

(108 intermediate revisions by 86 users not shown)

Line 1:

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

== How transclusion works ==

Whenever <code><nowiki>{{SOURCEPAGE}}</nowiki></code> is included on a target page, the WikiMedia software retrieves and embedes the entire content of <code>SOURCEPAGE</code> (i.e., {{Fake link|Template:SOURCEPAGE}}) at that ___location on the target page.

<div style="{{divstylenone}} float:left; width:258px;">

[[Image:TC-simple.PNG|left]]

</div>

=== Example ===

<div class="boilerplate metadata" id="Template syntax" style="{{divstylegreen}} float: right; width: 35%; "><center><b>Template syntax</b></center>

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>

If the source is in the Main article namespace (e.g., "[[Cat]]"), you must put a colon (:) in front of the name, thus: <code><nowiki>{{:Cat}}</nowiki></code>

=== How transclusionit works ===

If the source is in the Template namespace (e.g., "[[Template:Villagepumppages]]"), just use the name itself, alone, thus: <code><nowiki>{{Villagepumppages}}</nowiki></code>

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.

If the source is in any other namespace (e.g., "[[User:Oog]]"), you must use the full name, including the namespace, thus: <code><nowiki>{{User:Oog}}</nowiki></code>

</div>

=== Edit source pages with caution ===

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

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

<code><nowiki>{{SOMEPAGE}}</nowiki></code>

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.

{{clear}}

<div style="{{divstylenone}} float:left; width:544px;">

[[Image:TC-mult.PNG|left]]

[[Image:TC-mult-twit.PNG|left]]

</div>

{{clear}}

This would be a pretty neat trick if it only meant that you didn't have to copy-and-paste from one page to another. For example, you might decide to copy a welcome message to every newcomer's Talk page; you could do this with transclusion (though it might not be the best thing to do!).

But transclusion creates a "live" link between the "template" page and the target page where it appears. When the template is edited, all the other pages change, too.

For example, you ''might'' decide to create a (template) page with your mailing address and include that template on not only your page, but all your friends' pages, too. When you move your [[television]] and couch to another apartment, you will ''change'' your address template, and automatically, that ''new information'' will appear on all your friends' pages.

{{clear}}