Help/Transclusion

Transclusion is the inclusion of the content of a document into another document by reference. Beyond template transclusion, it is particularly useful in full text division in multiple parts and annotations along the text.

Syntax

If the source is a template, just use the name itself, alone:

• {{Infobox-fr}} or {{Infobox-hu}} (See Texts and Authors)
• {{Image}} (See Image pages)

If the source is in not a template, a colon (:) must be added in front of the name. This is the case when you assemble multiple parts of a full text into one page. For example, the page Du côté de chez Swann/Texte intégral assembles (partially) three pages: {{Du côté de chez Swann/Partie 1}}, {{Du côté de chez Swann/Partie 2}} and {{Du côté de chez Swann/Partie 3}}.

Partial transclusion

By using "noinclude", "onlyinclude" and "includeonly" markup, it is possible to transclude part of a page rather than all of it. Such partial transclusions can also be achieved by transcluding from other pages such as subpages. It is often desirable not to transclude some information, such as categories.

Transclusion markup

• noinclude - The markup <noinclude>...</noinclude> means that the text between the tags will not be transcluded onto another page and will appear only on the page itself. This is useful for categories and interlanguage links.
• includeonly - The markup <includeonly>...</includeonly> means that the text between the tags will only be used when the page is transcluded onto another page, and will not appear on the page itself.
• onlyinclude - The markup <onlyinclude>...</onlyinclude> indicates that only text surrounded by "onlyinclude" markup should be transcluded onto another page, but will appear on the page itself if not accompanied by "includeonly" tags as well. This is the most subtle of the partial transclusion tags because it often overrules the others. If there is at least one pair of "onlyinclude" tags on a page, then whenever this page is transcluded, it is only the material within the "onlyinclude" tags which gets transcluded. There can be several such sections, and within each such section, some material might be further excluded by "noinclude" tags, and might also be surrounded by "includeonly" tags so that it does not appear on the original page itself. But material outside the "onlyinclude" tags will be ignored when the page is transcluded onto another page. This can be useful, for example, to repeat a small part of one page on a second one: just surround the small part by onlyinclude tags, and transclude it onto the second page. Note that unlike <noinclude> and <includeonly>, <onlyinclude> will take precedence over enclosing <nowiki> tags. In other words, <nowiki> <onlyinclude>My content</onlyinclude> </nowiki> produces only "My content" when transcluded.

For example, Du côté de chez Swann/Texte intégral partially transcludes three pages. The <div> block on the top of each part ("Du côté de chez Swann/Partie 1", "Du côté de chez Swann/Partie 2", "Du côté de chez Swann/Partie 3"), containing basic information about the text, is between <noinclude> tags, and a <div> block, with relevant information about the whole text, is on the top of the full text page, before transclusion tags.

Labeled section transclusion

The Labeled section transclusion allows selective transclusion of marked-off sections of text. Its functionality is similar to an enhanced version of the <onlyinclude> tag with normal transclusion, which selects sections for inclusion.

While normal transclusion is primarily intended to transclude large portions of small templates, labeled section transclusion is intended for small portions of large pages.

However, there are some differences. In the native transclusion, sections are marked by behavior; thus you can have only one (possibly non-contiguous) section to be included or skipped.

Here, sections are marked by name, and behavior is chosen by the caller, which can include or skip sections as needed. Different pages can include or exclude selected sections; there can be arbitrary numbers of sections, which can also overlap arbitrarily.

Marking sections by name rather than behavior allows edit section links to be rendered more appropriately for getting excerpts from larger texts, since the extension can now account for sections that are skipped in the beginning of the page, allowing transcluded sections to be offset appropriately.

How it works

Step 1: Mark off sections
Mark off sections in the text using <section> tags like this:

<section begin=chapter1 />this is a chapter 1<section end=chapter1 />

Note that these tags are not HTML/XML, and do not use the normal attribute syntax. For this reason, and because the begin and end markers are individual, rather than normal XML open/close tags, this allows nested or overlapping sections. This allows you to insert section tags without worrying about interfering with other sections.

Step 2a: Transclude the section
Call the parser function #lst to transclude it, i.e. to transclude a section called chapter1 from a page called articleX:

{{#lst:articleX|chapter1}}

The target article defines the location of the section; its behavior is determined by the parser function.

Step 2b: Transclude the page but excluding the section
To transclude a page, but exclude a specified section, use the #lstx function:

{{#lstx:articleX|chapter1}}

Optionally, you may add replacement text to the excluded section.

{{#lstx:articleX|chapter1|replacement_text}}

Example:

{{#lstx:articleX|chapter1|See chapter 1 in [[articleX]].}}

The replacement text will appear in the area where the section is skipped (excluded).

Other functions

Discontiguous sections: It is possible to have multiple sections with the same name; in this case, every section with that name will be included/excluded. This is especially useful to mark various discussions.

Section ranges: These functions have an additional, optional argument to specify a section range; i.e. {{#lst:articleX|chapter1|chapter3}}, to include everything from the beginning of chapter 1 to the end of chapter 3. This allows using empty marker pairs to mark one end of the section.

Back to contents