View source for Help:Labeled Section Transclusion

{{Notice|You need to use [[Enhanced editor]], not [[VisualEditor]] when adding or editing LST.}}[[File:Transclusion-multiple-foo.svg|thumb|An illustration of the scope of [[Help:Transclusion#How Transclusion Works|transclusion]].|404x404px]]{{Clear right}}'''Labeled Section Transclusion''' (LST) allows you to show part of the contents of one page in one or more places across the wiki.  This allows editors to maintain content in one place.  If the content was copied instead of using LST, a single change to the original text could require numerous edits around the wiki to fix it in all the places it was copied.

LST is different than traditional [[Help:Transclusion|transclusion]] in that allows a specific section of a page to be shown other places, rather than an entire page.  In short, it is a specialized form of a template.  

==Documentation==
{{Breadcrumbs|url=|page=Extension:Labeled Section Transclusion|wikipedia=no|mediawiki=yes|openei=no|imwiki=no}}[[mediawikiwiki:Extension:Labeled Section Transclusion|Mediawiki's Labeled Section Transclusion]] contains the full range of options available with this extension.

==Best practice usage within USApedia==

The Labeled Section Transclusion extension provides two primary mechanisms which needed to be done in [[Enhanced editor]] (not [[VisualEditor]]) for transcluding information:
# Using section section heads.  Examples
#* '''<nowiki>{{#lsth:YouTube|Embedding videos}}</nowiki>''' will transclude the "Embedding videos" section.
#* '''<nowiki>{{#lsth:YouTube}}</nowiki>''' will transclude the introduction (the info above the first section head).
# Adding section tags to relevant parts of a document.  Example: 
#* '''<nowiki><section begin=givethesectionaname /> what do you want to include <section end=givethesectionaname /></nowiki>''' in the source page documents what is to be transcluded
#* '''<nowiki>{{#lst:articleX|givethesectionaname}}</nowiki>''' would then be used to call that section and transclude it to the location of your choice. 

The lead [[Gardener]] recommends using the section head approach to help keep the edit window as clean as possible on all related pages.  This approach is not without drawbacks, namely if the section head changes, the transclusion will break, but we feel this is the most pragmatic approach.   

=== Example: Test Transclude the intro of YouTube} ===
<pre>{{#lsth:YouTube}}</pre>
{{#lsth:YouTube}}

==Transcluding sections by headings==
There is optional support for transcluding sections of text marked with the normal headings, i.e. <code>==this section==</code>.  If installed, this is done with the ''lsth'' function.  This is not currently enabled on wikisource or Meta.

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

 <nowiki>{{#lsth:pagename}}</nowiki>

===Transclude a specific section===
You can also transclude the whole content of the ''sectionX'' (which includes all its sub-sections but excludes the heading of ''sectionX'' itself). 

 <nowiki>{{#lsth:pagename|sectionX}}</nowiki>

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 <u>in wiki code</u>, not how it is displayed. For example if the heading of the section is <code><nowiki>==List of [[Extension]]==</nowiki></code>, you should type "<code><nowiki>List of [[Extension]]</nowiki></code>" not "<code><nowiki>List of Extension</nowiki></code>".
# The matching is case '''in'''sensitive, 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''.

 <nowiki>{{#lsth:pagename|sectionX|sectionY}}</nowiki>

==Explicitly marking content to be transcluded==

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

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

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'':

  <nowiki>{{#lst:articleX|chapter1}}</nowiki>

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:
 <nowiki>{{#lstx:articleX|chapter1}}</nowiki>

Optionally, you may add replacement text to the excluded section.
 <nowiki>{{#lstx:articleX|chapter1|replacement_text}}</nowiki>

Example:
 <nowiki>{{#lstx:articleX|chapter1|See chapter 1 in [[articleX]].}}</nowiki>

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

=== Example: Transclude a specific section of YouTube ===
<pre>{{#lsth:YouTube|Embedding videos}}</pre>
{{#lsth:YouTube|Embedding videos}}

== Limitations ==
Labeled Section Transclusion appears to ignore [[noinclude]] (<code><nowiki><noinclude></noinclude></nowiki></code>).  Please keep this in mind when using it.

==External links==

=== Example uses on other wikis ===
The Wikimedia foundation is using this function to create an elegant process for status updates.   See:
* [[Mediawikiwiki:Visual editor]] as an example of tracking status (see [[Mediawikiwiki:Visual_editor/status|its status page]]).   

This process uses the following templates to make it all work (we think this is all of them):
* [[Mediawikiwiki:Template:Wikimedia project status line]]
* [[Mediawikiwiki:Template:Wikimedia project status line/blue link]]
* [[Mediawikiwiki:Template:Wikimedia project status line/red link]]
* [[Mediawikiwiki:Template:LST section begin]]
* [[Mediawikiwiki:Template:close tag]]
* [[Mediawikiwiki:Template:LST section end]]
* [[Mediawikiwiki:Template:close tag]]

The status history for each project is maintained in a subpage. In this example, it is at [[Mediawikiwiki:Visual editor/status]]

{{USApedia}}