Kulemba Module:Transcluder/doc

{{Module rating|beta}}
{{#ifeq:{{SUBPAGENAME}}|sandbox||{{High-use}}}}

This module is a general-purpose '''transclusion engine''', able to transclude any part of any page and with many options that normal transclusion doesn't provide.

== Usage ==

=== Modules ===

The main entry point for modules is the <code>get</code> method.

* <code>get( 'Title' )</code> — Get the requested page (exact same result as normal transclusion)
* <code>get( 'Title#' )</code> — Get the lead section of the requested page
* <code>get( 'Title#Section' )</code> — Get the requested section or <nowiki><section></nowiki> tag (includes any subsections)

<nowiki><noinclude></nowiki> and <nowiki><onlyinclude></nowiki> tags are handled [[mw:Transclusion#Transclusion markup|the usual way]] and there's also an optional second parameter to exclude various elements from the result:

* <code>get( 'Title#Section', { files = 0 } )</code> — Exclude all files
* <code>get( 'Title#Section', { files = 1 } )</code> — Exclude all files except the first
* <code>get( 'Title#Section', { files = 2 } )</code> — Exclude all files except the second
* <code>get( 'Title#Section', { files = '1,2' } )</code> — Exclude all files except the first and second
* <code>get( 'Title#Section', { files = '1-3' } )</code> — Exclude all files except the first, second and third
* <code>get( 'Title#Section', { files = '1,3-5' } )</code> — Exclude all files except the first, third, fourth and fifth
* <code>get( 'Title#Section', { files = -2 } )</code> — Exclude the second file
* <code>get( 'Title#Section', { files = '-2,3' } )</code> — Exclude the second and third files
* <code>get( 'Title#Section', { files = '-1,3-5' } )</code> — Exclude the first, third, fourth and fifth files
* <code>get( 'Title#Section', { files = 'A.png' } )</code> — Exclude all files except A.png
* <code>get( 'Title#Section', { files = '-A.png' } )</code> — Exclude A.png
* <code>get( 'Title#Section', { files = 'A.png, B.jpg, C.gif' } )</code> — Exclude all files except A.png, B.jpg and C.gif
* <code>get( 'Title#Section', { files = '-A.png, B.jpg, C.gif' } )</code> — Exclude A.png, B.jpg and C.gif
* <code>get( 'Title#Section', { files = { [1] = true, [3] = true } } )</code> — Exclude all files except the first and third
* <code>get( 'Title#Section', { files = { [1] = false, [3] = false } } )</code> — Exclude the first and third files
* <code>get( 'Title#Section', { files = { ['A.png'] = false, ['B.jpg'] = false } } )</code> — Exclude A.png and B.jpg
* <code>get( 'Title#Section', { files = '.+%.png' } )</code> — Exclude all files except PNG files (see [[mw:Extension:Scribunto/Lua reference manual#Patterns|Lua patterns]])
* <code>get( 'Title#Section', { files = '-.+%.png' } )</code> — Exclude all PNG files

The very same syntax can be used to exclude many other elements:

* <code>get( 'Title#Section', { sections = 0 } )</code> — Exclude all subsections
* <code>get( 'Title#Section', { sections = 'History, Causes' } )</code> — Exclude all subsections except 'History' and 'Causes'
* <code>get( 'Title#Section', { lists = 1 } )</code> — Exclude all lists except the first
* <code>get( 'Title#Section', { tables = 'stats' } )</code> — Exclude all tables except the one with id 'stats'
* <code>get( 'Title#Section', { paragraphs = '1-3' } )</code> — Exclude all paragraphs except the first, second and third
* <code>get( 'Title#Section', { references = 0 } )</code> — Exclude all references
* <code>get( 'Title#Section', { categories = '0' } )</code> — Exclude all categories
* <code>get( 'Title#Section', { templates = '-.+infobox' } )</code> — Exclude infobox templates
* <code>get( 'Title#Section', { parameters = 'image' } )</code> — Exclude all parameters from all templates except the one named 'image'

Options can be combined at will. For example:

* <code>get( 'Title#Section', { sections = 0, files = 1, paragraphs = '1-3' } )</code> — Exclude all subsections, all files except the first, and all paragraphs except the first three

You can also get only some elements like so:

* <code>get( 'Title#Section', { only = 'files' } )</code> — Get only the files
* <code>get( 'Title#Section', { only = 'lists', lists = 1 } )</code> — Get only the first list
* <code>get( 'Title#Section', { only = 'tables', tables = 'stats' } )</code> — Get only the table with id 'stats'
* <code>get( 'Title#Section', { only = 'paragraphs', paragraphs = '1,3-5' } )</code> — Get only the first, third, fourth and fifth paragraph
* <code>get( 'Title#Section', { only = 'templates', templates = 'Infobox' } )</code> — Get only the infobox
* <code>get( 'Title#Section', { only = 'parameters', parameters = 'abstract', references = 0 } )</code> — Get only the parameter called 'abstract' and remove all references from it

The output can be further modified with a few special options:

* <code>get( 'Title#Section', { noFollow = true } )</code> — Don't follow redirects
* <code>get( 'Title#Section', { linkBold = true } )</code> — Link the bold title or synonym near the start of the text
* <code>get( 'Title#Section', { noBold = true } )</code> — Remove bold text
* <code>get( 'Title#Section', { noComments = true } )</code> — Remove all HTML comments
* <code>get( 'Title#Section', { noLinks = true } )</code> — Remove all links
* <code>get( 'Title#Section', { noSelfLinks = true } )</code> — Remove self links
* <code>get( 'Title#Section', { noBehaviorSwitches = true } )</code> — Remove [[mw:Help:Magic words#Behavior switches|behavior switches]] such as <code><nowiki>__NOTOC__</nowiki></code>
* <code>get( 'Title#Section', { noNonFreeFiles = true } )</code> — Remove non-free files (identified by having the words "non-free" in their local description or in Commons)
* <code>get( 'Title#Section', { fixReferences = true } )</code> — Prefix reference names with 'Title ' to avoid name conflicts when transcluding and rescue references defined outside the requested section to avoid undefined reference errors

Besides the <code>get</code> method, the module exposes several other methods to get specific parts of the wikitext. This allows other modules to combine elements in more advanced ways.

=== Templates ===

The main entry point for templates is the <code>main</code> method. It's essentially a wrapper of the <code>get</code> method to make it usable for templates. See the documentation of the <code>get</code> method for more details and options.

* <code><nowiki>{{#invoke:Transcluder|main|Title}}</nowiki></code> — Transclude the requested page
* <code><nowiki>{{#invoke:Transcluder|main|Title#}}</nowiki></code> — Transclude the lead section of the requested page
* <code><nowiki>{{#invoke:Transcluder|main|Title#Section}}</nowiki></code> — Get the requested section or <nowiki><section></nowiki> tag (includes any subsections)
* <code><nowiki>{{#invoke:Transcluder|main|Title#Section|sections=0}}</nowiki></code> — Transclude the requested section, excluding subsections
* <code><nowiki>{{#invoke:Transcluder|main|Title|only=files|files=1}}</nowiki></code> — Transclude only the first file of the page
* <code><nowiki>{{#invoke:Transcluder|main|Title#Section|only=tables|tables=2}}</nowiki></code> — Transclude only the second table of the requested section
* <code><nowiki>{{#invoke:Transcluder|main|Title#|only=paragraphs|linkBold=yes}}</nowiki></code> — Transclude only the paragraphs of the lead section and link the bold text

=== See also ===

* [[Module:Transcluder/testcases]]