OpenSimulator:Transclusion

From OpenSimulator

Jump to: navigation, search

Transclusion means the inclusion of the content of one document in another document by reference. In Wikipedia, it refers to a function of the MediaWiki software which allows the content of one page to be included in the content of another page, by placing a reference to the source page in the wikitext of the target page. A page which is intended to be transcluded into other pages is called a template. Changes made to a template are automatically reflected on all pages into which that template has been transcluded.

The basic syntax used to produce transclusion in wikitext is {{Template name}}. It is also possible to pass parameters to a template, using the expanded syntax described at Help:Template.

An alternative to transclusion is substitution, whereby the current content of the template is automatically copied into the wikitext of the target page on saving, and will then be independent of any later changes made to the template. The syntax for this is {{subst:Template name}}


Contents

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

The wikitext of a page may (partly or fully) consist of tags for the inclusion of component pages. The component pages are usually not in the template namespace, and are often full pages in their own right. Composite pages are intended to gather the material on them into a central location.

Examples are:

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" link, 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, though 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 at the page for 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.

See also Wikipedia talk:Template namespace/Archive 1#transcluding prose.

Pages with a common section

When two pages need to discuss the same material in the same way, they can share a section. This involves 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, and if the first it may be placed in the same namespace as the other pages or in template namespace. 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. They can easily confuse editors and readers alike if they aren't.

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 which contains the repeating text, and then call that template multiple times. For example, Template:List of Languages calls Template:Lang def repeatedly with different parameters in order to generate the visible text.

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 Template:3x.

There is no real looping functionality built into the Mediawiki software as of this time (see, however, {{for loop}}), but there are some tricks for mimicking them. For instance, repeatedly calling a template which repeatedly calls a different template can mimic a double loop (see e.g. Template:Tiw, Template:Tiw, and Template:Tiw). Templates can also be coerced into calling themselves (normally prohibited by the Mediawiki software past a single instance, to prevent infinite loops), by the artful use of redirects (see Template:Tim) See also m:Help:Recursive conversion of wikitext.

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 useful not to transclude some information, such as template documentation.

For an example of how this technique can be applied to simplify the creation of summary articles, see this revision of Pathology, which consisted of a collection of transcluded lead paragraphs from several main articles.

Markup

Template:Also

There are three pairs of tags that can be used in wikitext to control how transclusion affects elements of a template or article. They determine whether or not wikitext renders, either in its own article, which we will call "here", or in another article where it is transcluded, which we will call "there".

  • <noinclude> this content will not be rendered there </noinclude> . These tags have no effect here.
  • <includeonly> this content will render only there, and will not render here </includeonly> (like invisible ink made visible by means of transclusion).
  • <onlyinclude> this content will render here and will render there </onlyinclude> but the rest of the article will be excluded from rendering there.

There can be several such section elements. Also, they can be nested. All possible renderings are achievable. For example, to render there one or more sections of the page here use <onlyinclude> tags. To append text there, wrap the addition in <includeonly> tags above, within, or below the section. To omit portions of the section, nest <noinclude> tags within it.

As a memory aid insert the phrase in transclusion between the two words to get "noInTransclusionInclude", "includeInTransclusionOnly" and "onlyInTransclusionInclude".

See, for example, the wikitext of the wiki news thread.

Selective transclusion

Shortcuts:
WP:SELECTIVETRANSCLUSION
WP:SELTRANS
Selective transclusion is the process of partially transcluding one selected section of a document which 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. But to transclude one section from a template or document into one page, and another section from the same template or document into another page, that's selective transclusion, which requires a way to uniquely mark each section to be transcluded, and a way to specify which section is to be transcluded. The section describes how to accomplish this.

Insert the following line into the document being 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; the identifier used for each section must be unique to that document):

<onlyinclude>{{#ifeq:{{{transcludesection|SECTIONNAME}}}|SECTIONNAME|
Also, each such transcludable section needs to end with this:
}}</onlyinclude>
Thus each section is 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 as shown below), and will be rendered by transclusion that uses that parameter and sets it to this 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 this section.<p>For example, if we want to make the principal criteria and common name sections of WP:TITLE be independently transcludable, we enclose the Principal Criteria for selective transclusion as follows:
<onlyinclude>{{#ifeq:{{{transcludesection|principalcriteria}}}|principalcriteria|
...
(text of principal naming criteria)
...
}}</onlyinclude>
Similarly, we enclose the Common Name section:
<onlyinclude>{{#ifeq:{{{transcludesection|commonname}}}|commonname|
...
(text of common name section)
...
}}</onlyinclude>
Then, to transclude the Principal Criteria section into another page, use the following line on that page, substituting FILENAME for the document to be transcluded and SECTIONNAME with the name of the section you want to transclude:
{{FILENAME|transcludesection=SECTIONNAME}}
So, to transclude the principal naming criteria section:
{{WP:TITLE|transcludesection=principalcriteria}}
Or, to transclude the common name section:
{{WP:TITLE|transcludesection=commonname}}
Of course, the same page can translude 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 unique keyword name.

Subpages

One can cut and paste the text to be transcluded into a subpage, then use the name of the subpage in the transclusion template. This approach can only be used with subpages from User, Talk or Wikipedia pages; currently, subpages cannot be created from main article pages.

Example: you want to discuss the deletion and redirecting of Pussycat to Cat. First, create the subpage Talk:Pussycat/Let's delete Pussycat!, write your comment into it, then transclude it in Talk:Pussycat and Talk:Cat using the template {{Talk:Pussycat/Let's delete Pussycat!}}. Comments posted in either talk pages will be shown in both.

Special pages

Some pages on Special:Specialpages can be transcluded, such as Special:Allpages, Special:Prefixindex, Special:Newfiles, Special:Newpages, Special:Recentchanges and Special: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"

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

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

Retrieved from "http://opensimulator.org/index.php?title=OpenSimulator:Transclusion&oldid=26279"
Personal tools
General
About This Wiki