LIMSWiki:Transclusion

Transclusion is the process of including the content of one document in another document by reference. It differs from substitution, which is a one-time, permanent copying of any content.

When transcluding on LIMSwiki, 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:

{{Purge}} will transclude from the page Template:Purge (Purge)
{{Saved book}} will transclude from the page Template:Saved book
{{:ELab}} will transclude from the page ELab (in the Main namespace)
{{LIMSWiki:Books}} will transclude from the page LIMSWiki:Books

What will transclude from a page can be controlled with the tags <noinclude>, <onlyinclude> and <includeonly> placed in the source page wikitext. 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 with 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.

Usage

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

On LIMSwiki, non-article pages have titles with a visible Namespace and Pagename. But encyclopedic articles only have a visible Pagename in their titles: for example, the article ELab has ELab as the Pagename; the Namespace, called Main Namespace, is not visible.

Having the wikitext {{Namespace:Pagename}} in a page, will transclude the page titled Namespace:Pagename into that page. For example, if a page has the wiki markup {{LIMSWiki:Vandalism}} in it, it will transclude the page LIMSWiki:Vandalism into it.

If the namespace is omitted, but the colon is included, like {{:Pagename}}, the encyclopedic article Pagename will be transcluded. For example, {{:ELab}} will transclude the article ELab.

If both namepace and colon are omitted, like {{Pagename}}, the Template:Pagename will be transcluded. For example, {{Purge}}, and also {{Template:Purge}}, will both transclude Template:Purge.

For transcluding subpages, the general syntax is {{Namespace:Pagename/subpagename}}. If it is a subpage of the page you are editing, then it is the general syntax, or {{/subpagename}}. For an encyclopedic article it is {{:Pagename/subpagename}}, although article subpages are normally disabled. For a template, it is the general syntax, or {{Pagename/subpagename}}. Note that subpages can only allowed in certain namespaces, such as User, Talk or LIMSwiki pages.

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 be achieved by transcluding from any pages, including subpages. It is often useful not to transclude some of a page, an example being with template documentation.

For a Wikipedia-based example of how this technique can be applied to simplify the creation of summary articles, see how part of 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.)

Markup

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 it 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 at all 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 both be 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.

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

A mis-example is, on a the user page, to use <includeonly> to "comment out" a section. While it might comment out sections here, such invisible ink may prove to be troublesome; if transcluded, the comments would be revealed. Use  instead.

NoInclude as a name about transcluding is pretty straightforward. A mnemonic for the other two transclusions there is: InclusionONLY; and Yet Another ONLYInclusion.

Labeled Section Transclusion

As of November 2015^[update], the Labeled Section Transclusion extension has been added to LIMSwiki. This means that one or more designated sections of a LIMSwiki page can be transcluded into another LIMSwiki page. Note, however, that this currently doesn't work with interwiki transcluded content. (See the interwiki transclusion section below for more.)

How it works - By section tag

Step 1: Mark off sections

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

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

Note that this uses two individual markers, rather than normal XML open/close tags, which simplifies 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).

How it works - By headings

There is optional support for transcluding sections of text marked with the normal headings, i.e. ==this section==. If installed, this is done with the lsth function.

Transclude the introduction

To transclude the introduction of a page (i.e. the content before the first heading), use

{{#lsth:pagename}}

Transclude a specific section

You can also transclude the whole content of the <tvar|section1>sectionX</> (which includes all its sub-sections but excludes the heading of <tvar|section2>sectionX</> itself).

{{#lsth:pagename|sectionX}}

Things to note:

Only the first occurrence of the sectionX is transcluded if you have more than one section with the same name.
Make sure you type what the heading of sectionX is in wiki code, not how it is displayed. For example if the heading of the section is ==List of [[Extension]]==, you should type "List of [[Extension]]" not "List of Extension".
The matching is case insensitive, to prevent links from breaking due to case changes.

Transclude multiple sections

You can also transclude from the first occurrence of sectionX (excluding the heading of sectionX itself) until it reaches the next occurrence of sectionY. Note that sectionY acts as a stop point so the transclusion doesn't contain the content of sectionY.

{{#lsth:pagename|sectionX|sectionY}}

Notes about the extension

The following are considerations concerning this extension. For the complete documentation, see the Labeled Section Transclusion page on MediaWiki.

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, possibly in a template. A similar mechanism is currently used at the French Wikisource.

Substitution

This also works with substitution; it's even possible for an article to substitute a section of itself. One use of this provides a neat way to archive talk pages: Mark the text to be archived using <section begin=archive />, etc. Then create an archive page with the text, using {{subst:#lst:talk_page|archive}}, which copies archived sections. Lastly, replace the contents of talk_page with {{subst:#lstx:talk_page|archive}} to remove those sections.

Limitations

While it is possible to use this extension across namespaces, interwiki references are not resolved. It is not yet possible, for example, to include part of a Wikipage page into a remote MediaWiki installation.
Section tags cannot themselves be transcluded in order to work on other pages. This means, for instance, that these tags cannot be embedded in a template using template parameters and parser functions. The #tag magic word does not work with section tags. #tag produces balanced tags, while the section tags uses singular tags. See T39256.
As of 2014, section tags don't have any effect when used inside a template parameter. If page A contains a text {{B|X}}, there's no way {{#lst:A|...}} can access X.

Interwiki transclusion

Interwiki transclusion — sometimes known as scary transclusion — is the process of including the content of a page on a separate wiki in this wiki by reference.

When using interwiki transclusion on LIMSwiki, the MediaWiki software will refer to the content of one page or template on another wiki and attempt to render it in your wiki page. This functionality becomes available by enabling both $wgEnableScaryTranscluding and the iw_trans bit in the interwiki table. Once enabled, several options become available for interwiki transclusion.

Pure transclusion

On LIMSwiki, most of the time you'll use pure transclusion. With this type of transclusion you'll be transcluding the foreign wiki page content to your wiki, not the wikicode of templates, etc. If you use pure transclusion to transclude a template, for example, you will see the documentation, if any, but the template will not function; it will be as if you were viewing the template page on the foreign wiki. Wikilinks on the transcluded page will appear to be blue links but will link to locations on the foreign wiki.

To use pure transclusion for a wiki page: {{wiki::main namespace page name}} e.g. {{wikipedia::Biology}}

To use pure transclusion for a wiki template: {{wiki:template name}} e.g. {{wikipedia:Purge}}

Note two things:

1. Purely transcluding a wiki page requires two colons while purely transcluding a template (which you probably don't want to do unless you need the documentation) only requires one.

2. Names of available wikis that can be transcluded from can be found in the "Prefix" column of the Special:Interwiki page.

For additional help, see the MediaWiki page Manual:$wgEnableScaryTranscluding.

Other methods

On rare occasions a wiki you want to transclude from has custom templates affecting the page, and those templates are not available on LIMSwiki. In this case, you can try raw transclusion and see if the results are acceptable. Raw transclusion expands all templates on the foreign page as if they come from your wiki instead of the other wiki. This will display the results of the wikicode on your wiki. Templates function to the extent required pages exist locally: i.e. where the template displays a link that doesn't exist on the local wiki, the link will be red; where the template includes other templates nested within its code, local templates by those names will be called, and unless the required templates exist in the required form, the template will be broken.

However, this will also have the result of wikilinks on the transcluded page appearing to be red if a corresponding page isn't found on the target wiki. Therefor, this is typically not a good solution. It's often better to attempt to manually add templates from the foreign wiki and then use pure transclusion.

For additional help, see the MediaWiki page Manual:$wgEnableScaryTranscluding.

Interwiki linking

Though not technically transclusion, interwiki linking is included here anyway as it's somewhat related. Interwiki linking is the process of placing a link to another foreign wiki page within a local wiki page using internal wikilink formatting. nterwiki links are hosted in the interwiki table of the Mediawiki database. Names of available wikis that can be transcluded from can be found in the "Prefix" column of the Special:Interwiki page. Choose a wiki name from the "Prefix" column and append it to a pagename on that wiki using internal link formatting.

Example 1: [[mediawikiwiki:Manual:Interwiki table]] will create an internal link that goes to the page "Manual:Interwiki table" on the MediaWiki wiki site. Note, however, this will result in showing the wiki prefix as well: mediawikiwiki:Manual:Interwiki table

To avoid this, also add a pipe (|) and the display text you want to appear, e.g. [[mediawikiwiki:Manual:Interwiki table|interwiki table]] will yield interwiki table.

Example 2: [[lablynxwiki:ELab|ELab]] will yield ELab.

Example 3: [[wikipedia:Template:Purge|purge template on Wikipedia]] will yield purge template on Wikipedia.

For additional help, see the MediaWiki page Manual:Interwiki.

Transclusion and associated limitations on wiki/interwiki functions

Transclusion is definitely a useful tool, as noted in the above documentation. However, using transclusion on this and other related wikis has an unintended side effect that must be pointed out, specifically with how PDFs on the wiki and on Pediapress are rendered.

Interwiki transclusion of transcluded content can't be properly printed to PDF

We call this the ol' "transclusion of a transclusion" problem. Specifically, problems arise when taking content from one wiki that is itself intrawiki transcluded and attempt to use interwiki transclusion to place it in another wiki. For example, Wiki X's page titled "Widget A" has text from another Wiki X page titled "History of Widget A" transcluded to it. Then the "Widget A" page is interwiki transcluded to Wiki Y. The problem isn't that the "Widget A" page material won't show up properly on Wiki Y, because it does in fact appear there in total without issue. The problem is specifically with the MediaWiki Collection extension, which allows users to create books and download wiki content in PDF format. If you interwiki transclude content that includes intrawiki transcluded content, the PDF generated on the wiki and on Pediapress will be incomplete because the extension is not designed to be able to drill down that far. Avoid interwiki transclusion of a transclusion if you must be able to generate a PDF/Pediapress copy of the interwiki transcluded page.