Undid revision 511325564 by Stormy650 (talk) vandalism |
ce lead |
||
Line 1: | Line 1: | ||
{{redirect3|WP:TRANS|You may be looking for [[Wikipedia:Transwiki log]], [[Help:Transwiki]], [[Wikipedia:Translation]] or [[Wikipedia:WikiProject Transwiki]]}} |
{{redirect3|WP:TRANS|You may be looking for [[Wikipedia:Transwiki log]], [[Help:Transwiki]], [[Wikipedia:Translation]] or [[Wikipedia:WikiProject Transwiki]]}} |
||
{{shortcut|WP:TRANS}} |
{{shortcut|WP:TRANS}} |
||
'''[[Transclusion]]''' |
'''[[Transclusion]]''' is a function of the [[MediaWiki]] software that allows the content of one page to be included in the content of another page. In general, transclusion means ''any inclusion of the content of one electronic document into the content of another document''. It is accomplished by markup language elements. Wikitext uses curly-brackets in the target and tags in the source. These specify the reference precisely. When placing such a reference, the transclusion is automated so that any subsequent change made to a source page is reflected whenever the target page is rendered by the user. |
||
At the target document where the basic wikitext syntax <code><nowiki>{{Namespace:Name}}</nowiki></code> is indicated, there will render on the user's display the source of the transclusion that is the content of the page named ''Namespace:Name''. If the referenced (target) page name does not begin with a namespace identifier (''Namespace:''), it is assumed to be in the Template namespace. (A [[Help:Template|template]] is a page whose sole purpose is to be the source of a transclusion, hence the curly-brackets.) To refer to a page in the "Main" (article) namespace, it is necessary to prefix it with a colon (''':'''). Examples: |
|||
* '''<tt><nowiki>{{Like}}</nowiki></tt>''' will transclude from the page [[:Template:Like]] - specifically: {{Like}} |
* '''<tt><nowiki>{{Like}}</nowiki></tt>''' will transclude from the page [[:Template:Like]] - specifically: {{Like}} |
||
* '''<tt><nowiki>{{Stochastic processes}}</nowiki></tt>''' will transclude from the page [[:Template:Stochastic processes]] |
* '''<tt><nowiki>{{Stochastic processes}}</nowiki></tt>''' will transclude from the page [[:Template:Stochastic processes]] |
||
Line 9: | Line 9: | ||
* '''<tt><nowiki>{{WP:Assume good faith}}</nowiki></tt>''' will transclude from the page [[Wikipedia:Assume good faith]] |
* '''<tt><nowiki>{{WP:Assume good faith}}</nowiki></tt>''' will transclude from the page [[Wikipedia:Assume good faith]] |
||
The markup that may be needed to accomplish a [[#partial transclusion]] of the source document is completely explained below. |
|||
It is also possible to pass parameters to a template, using the expanded syntax described at [[Help:Template]], which can affect what text in the template is rendered. For example, to highlight text like {{highlight|this}}, the text-to-be-highlighted is passed as a parameter to the ''highlight'' template: <code><nowiki>{{highlight|this}}</nowiki></code>. |
|||
Concerning template language in general, it is also possible to pass parameters to a template, using the expanded syntax described at [[Help:Template]], which can affect what text in the template is rendered. For example, to highlight text like {{highlight|this}}, the text-to-be-highlighted is passed as a parameter to the ''highlight'' template: <code><nowiki>{{highlight|this}}</nowiki></code>. |
|||
An alternative to transclusion is [[Help:substitution|substitution]], whereby the current content of the template is automatically copied into the wikitext of the target page on saving, and will then be an indistinguishable part of the saved page, independent of any later changes made to the template. The syntax for this is <code><nowiki>{{subst:Template name}}</nowiki></code> |
|||
Considering alternative to transclusion, there is [[Help:substitution|substitution]]. Substution causes the wikitext template to be overwritten by the source when the editor saves a page. The references is included by copying at the document-saving process, rather than transcluded by the document-rendering process. The source becomes an indistinguishable part of the saved page, independent of any later changes made to the template (source). The syntax for this is <code><nowiki>{{subst:Template name}}</nowiki></code> |
|||
==How transclusion works== |
|||
{{/How Transclusion Works}} |
|||
==Applications of transclusion== |
|||
The most common application of transclusion is in the use of [[Help:Template|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: |
|||
*[[m:Help:A simple composite example]] |
|||
*[[Wikipedia:Village pump]] with six component pages, e.g. [[:Wikipedia:Village pump (technical)]] |
|||
*A daily page like [[Wikipedia:Votes for deletion/Log/2005 May 31]] where each component page consists of the discussion on the deletion of one Wikipedia page, e.g. [[Wikipedia:Votes for deletion/Sp3tt]] (for this day there are 75 such component pages) |
|||
*[[m:Meta:Translation/Coordination]], mainly containing |
|||
**[[m:Meta:Translation/Coordination/List/Meta]] |
|||
**[[m:Meta:Translation/Coordination/List/Main]] |
|||
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 [[Help:Section#Editing sections of included templates|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 [[Help:Interwiki linking#Interlanguage links|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: |
|||
*{{pim|Help|Editing sections of included templates}} |
|||
*{{pim|Help|Alphabetic order}} |
|||
===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 that 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., {{tl|3x}}, where <nowiki>{{3x| howdy!}}</nowiki> produces {{3x| howdy!}}. |
|||
There is no real looping functionality built into the Mediawiki software as of this time (see, however, {{tl|for loop}}), but there are some tricks for mimicking them. For instance, repeatedly calling a template that repeatedly calls a different template can mimic a double loop (see, e.g., {{tiw|ld}}, {{tiw|l2d}}, and {{tiw|l3d}}). 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 {{tim|Loop1}}) |
|||
<!-- hiding technobabble till I can figure out what it's trying to say. :) |
|||
An example where the same template is used for different loop levels is {{tim|Loop 2}}. Because the software has a built-in protection against infinite nesting (if there is, there will be an error e.g. <code>Fatal error: Maximum execution time of 30 seconds exceeded in /w/includes/Parser.php on line 775</code>), a redirect is used for each level. The number of levels that the template can handle is determined by the number of parameters specified in the two template calls it comprises (because going up a level requires an extra parameter) and the number of existing redirects. |
|||
Likewise, [[Template:Lanlp 1]] is used for both the inner and the outer of a double loop. Adding an item (here a language) adds to each row and also adds an extra row. |
|||
'''Providing effective repetition without repetition of similar template calls in the wikitext''' |
|||
A technique for repetition of similar template calls without actually putting this list in the wikitext is demonstrated in {{links-small|template|for}}, and a more primitive method described below. |
|||
Example {{ut1|t2demo}}: |
|||
<nowiki>{{for loop|; |call=t2demo|pc1n=2|pc1v=constant|abc|def|ghi}}</nowiki> gives: |
|||
{{for loop|; |call=t2demo|pc1n=2|pc1v=constant|abc|def|ghi}} |
|||
Description of the old {{tim|List of template calls}}: |
|||
For an arbitrary template with up to three nameless parameters, it is equivalent to calling the template repeatedly, with the first parameter varying, and the possible other parameters fixed: One specifies the name, the values of the fixed parameters, and the list of values the first parameter should have in consecutive template calls, with a sequential number each, and ending with "end". The technique requires redirects like {{tim|List of template calls 3}}, as many as the maximum number of repetitions. |
|||
If, for example, the second parameter varies, or two parameters, then a similar template can be made, but each version requires its own set of redirects. |
|||
Example {{ut1|t2demo}}: |
|||
<nowiki>{{List of template calls|t2demo|constant||abc|1|def|2|ghi|end|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||}}</nowiki> |
|||
gives (see the master copy [[m:Help:Template#Repetition within a page]]): |
|||
{{List of template calls|t2demo|constant||abc|1|def|2|ghi|end|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||}} |
|||
The empty parameters are needed in accordance with the maximum number of parameters the repeated template can have (currently three) and the maximum number of repetitions. Putting more empty parameters than needed at the end does not matter, but the number of empty parameters in the beginning of the list should be correct. |
|||
--> |
|||
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 [[WP:SS|summary articles]], see how [[History of pathology]] [http://en.wikipedia.org/w/index.php?title=History_of_pathology&diff=prev&oldid=207668817] was transcluded into [[Pathology]],[http://en.wikipedia.org/w/index.php?title=Pathology&diff=prev&oldid=207669487] which consisted of a collection of transcluded [[WP:LEAD|lead paragraphs]] from several main articles. |
|||
{{anchor|Transclusion markup}} <!--Temp anchor |
|||
until renamed section is checked for link breakage via ''what links here''--> |
|||
===Markup=== |
|||
{{also|Help:Template#Noinclude, includeonly, and onlyinclude|Help:Category#Categories_and_templates}} |
|||
There are three pairs of [[html element|tags]] that can be used in [[wikitext]] to control how transclusion affects '''''[[HTML#Elements|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'''". |
|||
*'''<nowiki><noinclude></nowiki>''' this content '''will not be rendered ''there''''' '''<nowiki></noinclude></nowiki>''' . These tags have no effect ''here''. |
|||
*'''<nowiki><includeonly></nowiki>''' this content '''will render only ''there''''', and will not render ''here'' '''<nowiki></includeonly></nowiki>''' (like [[invisible ink]] made visible by means of transclusion). |
|||
*'''<nowiki><onlyinclude></nowiki>''' this content will render ''here'' and will render ''there'' '''<nowiki></onlyinclude></nowiki>''' 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 '''<nowiki><onlyinclude></nowiki>''' tags. To append text ''there'', wrap the addition in '''<nowiki><includeonly></nowiki>''' tags above, within, or below the section. To omit portions of the section, nest '''<nowiki><noinclude></nowiki>''' 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, [[m:template:information thread|the wikitext of the wiki news thread]]. |
|||
===Selective transclusion=== |
|||
{{shortcut|WP:SELECTIVETRANSCLUSION|WP:SELTRANS}} |
|||
<b>Selective transclusion</b> is the process of [[#Partial transclusion|partially transcluding]] one selected section of a document that 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 '''<tt><nowiki><onlyinclude> … </onlyinclude></nowiki></tt>''' tags, and transcluding the whole page. However, 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: |
|||
:a) uniquely mark each transcludable section in the source document; and |
|||
:b) in the target document(s) (those to show the transcluded sections), a way to specify which section is to be transcluded. |
|||
This section describes how to accomplish this. |
|||
====Source Document Markup==== |
|||
Insert the following line into the "source" document (the one from which text is to be 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 and must be unique within that document: |
|||
:<tt><nowiki><onlyinclude>{{#ifeq:{{{transcludesection|SECTIONNAME}}}|SECTIONNAME|</nowiki></tt> |
|||
End each such transcludable section with: |
|||
:<tt><nowiki>}}</onlyinclude></nowiki></tt> |
|||
====Target Document Markup==== |
|||
To transclude a section marked as above into another page (the "target page"), use the following line on that page, substituting PAGENAME for the "source" document from which text to be transcluded, and SECTIONNAME with the name of the section you want to transclude: |
|||
:<tt><nowiki>{{PAGENAME|transcludesection=SECTIONNAME}}</nowiki></tt> |
|||
Thus each section is enclosed within '''<tt><nowiki><onlyinclude> … </onlyinclude> </nowiki></tt>''' tags will always be rendered when the '''<tt>transcludesection</tt>''' parameter is not set (when the document is viewed ordinarily, or when the document is transcluded without setting the '''<tt>transcludesection</tt>''' parameter as shown below), and will be rendered by transclusion on any page that does set '''<tt>transcludesection</tt>''' to the section's name. It will ''not'' be rendered by transclusion that uses the '''<tt>transcludesection</tt>''' parameter but sets it to anything other than the name of the section. |
|||
Also, when providing PAGENAME, without providing a [[Wikipedia:Namespace|Namespace]], the wiki will assume that the PAGENAME belongs in the [[Wikipedia:Template_namespace|Template Namespace]]. To transclude from a [[Wikipedia:Main_namespace|Mainspace]] article, use :PAGENAME. |
|||
:<tt><nowiki>{{:PAGENAME|transcludesection=SECTIONNAME}}</nowiki></tt> |
|||
====Example==== |
|||
If we want to make the "Principal Criteria" and "Common Name" sections of [[WP:TITLE]] be independently transcludable, we edit the WP:TITLE page and enclose the "Principal Criteria" section as follows: |
|||
:<tt><nowiki><onlyinclude>{{#ifeq:{{{transcludesection|principalcriteria}}}|principalcriteria|</nowiki></tt> |
|||
:... |
|||
:''(text of "Principal Criteria" section)'' |
|||
:... |
|||
:<tt><nowiki>}}</onlyinclude></nowiki></tt> |
|||
Similarly, we enclose the "Common Name" section with: |
|||
:<tt><nowiki><onlyinclude>{{#ifeq:{{{transcludesection|commonname}}}|commonname|</nowiki></tt> |
|||
:... |
|||
:''(text of "Common Name" section)'' |
|||
:... |
|||
:<tt><nowiki>}}</onlyinclude></nowiki></tt> |
|||
Then, to transclude the "Principal Criteria" section into another page, we insert into that page: |
|||
:<tt><nowiki>{{WP:TITLE|transcludesection=principalcriteria}}</nowiki></tt> |
|||
To transclude the "Common Name" section into another page, we insert into that page: |
|||
:<tt><nowiki>{{WP:TITLE|transcludesection=commonname}}</nowiki></tt> |
|||
Of course, the same page can transclude 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 '''<tt>transcludesection</tt>''' be given a value that is unique within that page. |
|||
===Subpages=== |
|||
One can cut and paste the text to be transcluded into a [[Wikipedia:Subpages|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 [[Wikipedia:Subpages#Articles do not have sub-pages (main namespace)|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 '''<nowiki>{{Talk:Pussycat/Let's delete Pussycat!}}</nowiki>'''. Comments posted in either talk pages will be shown in both. To ease editing of the subpage, it may be helpful to precede the transcluded talk with {{tl|lat}}, e.g. {{lat|Pussycat/Let's delete Pussycat!}}. Transcluding in this way will ''not'' preserve a fixed record of the discussion at the time of any archiving, so discussions should be closed in conjunction with archiving. An alternative is to centralise discussion in the normal manner on a single talk page and point to it using by [[WP:SUBST|substituting]] {{tl|Pls}} templates, per [[WP:MULTI]]. |
|||
===Special pages=== |
|||
{{see also|Wikipedia:Special pages#Miscellaneous}} |
|||
Some pages on [[Special:Specialpages]] can be transcluded, such as [[Special:Allpages]], [[Special:Prefixindex]], [[Special:Newfiles]], [[Special:Newpages]], [[Special:Recentchanges]] and [[Special:Recentchangeslinked]]. |
|||
Samples: |
|||
*<nowiki>{{Special:Allpages/General}}</nowiki> – a list of pages starting at "General" |
|||
*<nowiki>{{Special:Prefixindex/General}}</nowiki> – a list of pages with prefix "General" |
|||
*<nowiki>{{Special:Newfiles/4}}</nowiki> – a gallery of the four most recently uploaded files |
|||
*<nowiki>{{Special:Newpages/5}}</nowiki> – a list of the five most recently created pages |
|||
*<nowiki>{{Special:Recentchanges/5}}</nowiki> – the five most recent changes |
|||
*<nowiki>{{Special:Recentchangeslinked/General}}</nowiki> – 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 [[Wikipedia:Page name|displayed title]] of the page. |
|||
==Pages related to [[MediaWiki]] [[transclusion]]== |
|||
* [[m:Help:A simple composite example]] |
|||
* [[Wikipedia:MediaWiki namespace]] |
|||
** [[m:Help:MediaWiki namespace]] |
|||
* [[m:Help:Variable]] |
|||
*[[Wikipedia talk:Template namespace#transcluding prose]] |
|||
==Templates== |
|||
* [[Help:Template]] |
|||
* [[Wikipedia:Template namespace]] |
|||
* [[Wikipedia:Template limits]] |
|||
== See also == |
|||
{{Wikipedia glossary}} |
|||
* [[Wikipedia:Transclusion costs and benefits]] |
|||
* [[Wikipedia:Substitution]] (the opposite of transclusion) |
|||
* [[Wikipedia:WikiProject Modular Articles]] |
|||
* [[MediaZilla:4547|Bugzilla:Request for template transclusion from Commons]] (interwiki templates, etc.) |
|||
[[Category:Wikipedia editing]] |
|||
[[Category:Wikipedia templates]] |
|||
[[Category:Wikipedia page help]] |
|||
[[ar:ويكيبيديا:تضمين]] |
|||
[[fa:ویکیپدیا:تراگنجانش]] |
|||
[[fr:Aide:Inclusion]] |
|||
[[ko:위키백과:문서 끼워넣기]] |
|||
[[it:Aiuto:Inclusione]] |
|||
[[mk:Википедија:Превметнување]] |
|||
[[mzn:ویکیپدیا:تراگنجانش]] |
|||
[[pl:Wikipedia:Transkluzja]] |
|||
[[pt:Wikipédia:Transclusão]] |
|||
[[simple:Wikipedia:Transclusion]] |
|||
[[yi:װיקיפּעדיע:אריבערשליסן]] |
|||
[[zh:Wikipedia:嵌入包含]] |
Revision as of 22:28, 12 September 2012
Transclusion is a function of the MediaWiki software that allows the content of one page to be included in the content of another page. In general, transclusion means any inclusion of the content of one electronic document into the content of another document. It is accomplished by markup language elements. Wikitext uses curly-brackets in the target and tags in the source. These specify the reference precisely. When placing such a reference, the transclusion is automated so that any subsequent change made to a source page is reflected whenever the target page is rendered by the user.
At the target document where the basic wikitext syntax {{Namespace:Name}}
is indicated, there will render on the user's display the source of the transclusion that is the content of the page named Namespace:Name. If the referenced (target) page name does not begin with a namespace identifier (Namespace:), it is assumed to be in the Template namespace. (A template is a page whose sole purpose is to be the source of a transclusion, hence the curly-brackets.) To refer to a page in the "Main" (article) namespace, it is necessary to prefix it with a colon (:). Examples:
- {{Like}} will transclude from the page Template:Like - specifically: Like
- {{Stochastic processes}} will transclude from the page Template:Stochastic processes
- {{:Calculus}} will transclude from the page Calculus (in the Main namespace)
- {{WP:Assume good faith}} will transclude from the page Wikipedia:Assume good faith
The markup that may be needed to accomplish a #partial transclusion of the source document is completely explained below.
Concerning template language in general, it is also possible to pass parameters to a template, using the expanded syntax described at Help:Template, which can affect what text in the template is rendered. For example, to highlight text like this, the text-to-be-highlighted is passed as a parameter to the highlight template: {{highlight|this}}
.
Considering alternative to transclusion, there is substitution. Substution causes the wikitext template to be overwritten by the source when the editor saves a page. The references is included by copying at the document-saving process, rather than transcluded by the document-rendering process. The source becomes an indistinguishable part of the saved page, independent of any later changes made to the template (source). The syntax for this is {{subst:Template name}}