View source for Portable Infoboxes

{{Feature/Developing}}
{{Infobox/Feature
|image = Information_person.jpg
|name = Portable Infobox
|description = A box containing a structured summary of facts that can be viewed in multiple platforms
|type = Information
|implementation = XML (Parser function)
|stage= release
}} 
FANDOM's push towards a more inclusive wiki ecosystem now includes a "good practice" (not yet a [[Portable Infoboxes/Best practices|best practice]]) to use [[Help:PortableInfoboxes|Portable Infoboxes]] (see also help for [[Help:PortableInfoboxes/CSS|CSS]] and [[Help:PortableInfoboxes/Tags|Tags]]). These continue to evolve, and are the next generation after InfoboxBuilder-driven templates. Many Portable Infoboxes have already been created! This document is an alternative to the current official documentation.

'''If you do not typically create or modify templates, this guide is not necessarily for you.'''

You may want to start by reading the [[Portable Infoboxes/FAQ|FAQ]].

== Background ==
Like most [[Help:Infobox|Infoboxes]], a format is developed inside a [[Help:Templates|<tt>Template:</tt>]] article (eg. <tt>[[Template:Infobox character]]</tt>). Unlike most other templates, however, a Portable Infobox template is written in a special [[wikipedia:XML|XML]] format instead of [[Help:Wikitext|wikitext]] or the [[Help:Lua|Lua templating language]]. This type of markup is more typical of [[Help:HTML|HTML]] or [[Help:Extensions|Extensions]] inside wikitext, and Portable Infobox syntax is indeed the script for an extension; this allows it to format the rendered Infobox well on multiple platforms.

Once the Template: has been created, it can be used just like any other Template in articles. For many, this means a drop-in replacement is possible for most wikis without having to change what is written in articles. The Migration tool is intended for just such a purpose; the resultant Drafts will require tweaking in many cases and are not usable as-is for a minority of wikis. In these cases, a more thorough refinement using syntax is required. It bears noting that in most cases where the Migration tool does not work well in approximating a good result, the templates being migrated are either very old (and tend to not render well across devices), very complex (using Lua or elaborate [[Help:ParserFunctions|ParserFunctions]]), or very atypical Infoboxes (with designs that often will not render well on all devices).

== Basics ==
{{Main|Help:PortableInfoboxes}}
Inside an article, an infobox is used the same way as has been typically done.
<pre>
{{infobox character
 | title         = Daisy
 | image         = Example.jpg
 | imagecaption  = Daisy, blowing in the wind
 | position      = Supreme flower
 | age           = 2 months
 | status        = Active
 | height        = 5 inches
 | weight        = 20 grams
}}</pre>

The Template called (in this case [[Template:Infobox character]]) may be using the Portable Infobox syntax, which looks something like this:
<source lang="xml">
<infobox>
    <title source="title" />
    <image source="image">
        <caption source="imagecaption" />
    </image>
    <data source="position" />
    <data source="age" />
    <data source="status" />
    <data source="height" />
    <data source="weight" />
</infobox>
</source>

The example above does produce a viable Infobox, and indeed may be the basic result produced by the Migration Tool. There are some features missing that can be used to make that Draft better. Here, we'll introduce "default" (which can be used as a child of any element that calls for "source"), "labels" and "format". The latter is employed so that we can start using pure data instead of mixed data and units, but the same function can do many important things, which we will explain in more detail later in this document.
<source lang="xml">
<infobox>
    <title source="title">
        <default>{{PAGENAME}}</default>
    </title>
    <image source="image">
        <caption source="imagecaption" />
    </image>
    <data source="position">
        <label>Position</label>
    </data>
    <data source="age">
        <label>Age</label>
    </data>
    <data source="status">
        <label>Status</label>
    </data>
    <data source="height">
        <label>Height</label>
        <format>{{{height}}} inches</format>
    </data>
    <data source="weight">
        <label>Weight</label>
        <format>{{{weight}}} grams</format>
    </data>
</infobox>
</source>

== Drafts with the Migration Tool ==
{{Main|Help:InfoboxMigration}}The InfoboxMigration tool is used to convert other types of infoboxes to PortableInfoboxes with mixed results. With more complex templates, manual editing is needed.

== Insertion of Infoboxes using the VisualEditor ==
[[File:Infobox_on_VE_dropdown.png|thumb|Inserting an Infobox with VisualEditor]]
Using VisualEditor — the most common tool for new wiki contributors — the process of adding an Infobox itself is easy. There is a dropdown in the editing toolbar that provides a list of Portable Infoboxes. Modifying that same Infobox and some operations with it are not as simple. At this time, the parameters for an Infobox are exposed without explanation, and images and videos are not easily inserted.

[[File:Source_Editor_in_VE_dropdown.png|thumb|Source Editor in VE]]
Inserting an image (or video) into the Infobox requires the VisualEditor insert tool in the main body of the article, and copying the pointer to that image into the Infobox using the Source Editor. It is important to remember what parameter the image should be placed into. It is not important to mark sizing, caption, thumbnail, or other modifiers to the image, as these are ignored. The width of the image is determined by CSS, and a caption should be handled by a separate parameter using the caption tag.

In the current implementation, this copy/paste process is also necessary in the Classic (RTE) Editor.

[[File:SE_Before.png|thumb|Image outside the Infobox, using SE]]
[[File:SE_After.png|thumb|Image inside the Infobox, using SE]]

== Tags ==
{{Main|Help:PortableInfoboxes/Tags}}
If you are accustomed to traditional Templates, a word enclosed in three brackets (eg "'''<code>{{{word}}}</code>'''") is called a [[Help:Template parameters|parameter]]. They represent input to a Template, where the value of "word" is whatever is set in an article. The same input is recognized in Portable Infobox using '''<code>source="word"</code>'''. Such parameters are used to store data in the article, but they don't have to display in the same way they are input. They can be output differently using the '''<code>&lt;format&gt;</code>''' tag.

The nesting of tags is very important to keep track of as some tags can only be nested in other types of tags. In XML, it is also important that tags be closed; if they do not require a closing tag, they should end with '''<code>/&gt;</code>'''

To group together data elements into a section (either horizontally or vertically), a <code>&lt;group&gt;</code> tag is helpful.

<code>&lt;navigation&gt;</code> tags represent a generic way to render any type of [[Help:Wikitext|wikitext]] inside a Portable Infobox where it might otherwise be ignored or restricted. These tags typically occupy a whole section (much like the <nowiki><data></nowiki> tag) and can be used to show links or any other information. Typically, a navigation tag is used as a footer.

=== Images ===
Partial [[Help:Tabber|tabber-like]] functionality is supported if you pass a set of images to the template enclosed in <code>&lt;gallery&gt;</code> or <code>&lt;tabber&gt;</code> tags. See the [[Help:Infoboxes#Using_multiple_images_or_videos|Using multiple images or videos]] section of help.

;Example portable infobox
<pre>
<!-- Infobox character -->
<infobox layout="stacked">
  <title source="name"><default>{{PAGENAME}}</default></title>
  <image source="image" />
  <data source="season"><label>Season(s)</label></data>
  <data source="first"><label>First seen</label></data>
</infobox>
</pre>

;Example gallery usage
<pre>
{{Infobox character
 |name   = Mary Crawley
 |image  = <gallery>
    Mary riding.jpg|Mary on a horse
    Mary wedding.jpg|Mary in wedding dress
    Mary dancing.jpg|Mary dancing
  </gallery>
 |season = [[Series 1|1]], [[Series 2|2]], [[Series 3|3]], 
           [[Series 4|4]], [[Series 5|5]], [[Series 6|6]]
 |first = [[Episode 1.01]]
}}
</pre>

;Example tabber usage
<pre>
{{Infobox character
 |name   = Mary Crawley
 |image  = <tabber>
    Riding   = [[File:Mary riding.jpg]]  |-|
    Wedding  = [[File:Mary wedding.jpg]] |-|
    Dancing  = [[File:Mary dancing.jpg]]
  </tabber>
 |season = [[Series 1|1]], [[Series 2|2]], [[Series 3|3]], 
           [[Series 4|4]], [[Series 5|5]], [[Series 6|6]]
 |first = [[Episode 1.01]]
}}
</pre>

== Styling with CSS ==
{{Main|Help:PortableInfoboxes/CSS}}
Infoboxes using this kind of code are automatically styled, taking cues from your [[Help:Theme designer|community's custom theme]]. If any of the variables are empty, the relevant row of the template will not be displayed (unless the 'default' tag has been used).

Inline CSS is not supported. It also appears that custom classes are not supported, but a limited set of pre-defined classes can be used to style elements via <code>theme</code> and <code>theme-source</code> attributes.

=== Layout ===
For the overall or table info boxes, layouts are pretty basic right now and appear to only apply to data and their labels.

<infobox><data><label>label</label><default>Data</default></data></infobox>
The default is a "table"-like layout with labels in data laid out like the box on the right.

<infobox layout="stacked"><data><label>label</label><default>Data</default></data></infobox>
The other layout is <code>&lt;infobox layout="stacked"&gt;</code> which puts labels above data and data indented box on the right.

Layouts also apply to groups (see below) and give more options which will be described with the help for Groups.

=== Groups ===
You can think of groups like sub-infoboxes where you can control the layout and some functions independently of the overall infobox.

Groups are especially good for portions of an infobox you want to be [[Help:Infoboxes#Collapsible_groups|collapsible]]. You can add one of the following attributes:
* <code>collapse="closed"</code> - collapsed by default
* <code>collapse="open"</code> - uncollapsed by default

=== Themes ===
{{Main|Themes}}
Themes are sets of CSS styles that apply to a particular portable infobox (via the <code>theme="''themename''"</code> attribute of <code>&lt;infobox&gt;</code>). Once you specify a theme, you can apply styles for the class <code>.portable-infobox.pi-theme-''themename''</code> in your <tt>MediaWiki:Wikia.css</tt>. They will be different from the default styling, but will inherit defaults for anything not specified in the theme.

;Examples

* See [[Portable Infobox/Themes]]

== Advanced output ==
The most straightforward use of data types are to output values just as they were input. However, a secondary goal of Portable Infoboxes is a move towards structured data. In the height and weight examples above, it is assumed that all values are in inches and grams, and the '''<code>format</code>''' tag adds those labels to the output with the expectation that the input will be a number only. In future designs of Visual Editor, it is likely that entering a value that is not a simple number will be disallowed.

=== Format tags ===
Format tags (<code>&lt;format&gt;</code>) allow more control of how parameter data is displayed for <code>&lt;data&gt;</code>, <code>&lt;title&gt;</code>, and <code>&lt;caption&gt;</code> tags.

=== ParserFunctions ===
Calling ParserFunctions is currently done inside the <code>&lt;default&gt;</code>, <code>&lt;format&gt;</code> or <code>&lt;navigation&gt;</code> tag, using a '''<code>&#123;{#switch:</code>''' (or similar) statement. When used in format or navigation tags, this will not be called or displayed unless there is a value in the parent's data source parameter. For use in default, avoid the pitfall of referring to the same element it is a default for. Use of parser functions in default, borrows information entered elsewhere to construct the output for the missing information. There is no need to use an '''<code>&#123;{#if:</code>''' statement if it is testing for the parent's source parameter, as these will not render in an infobox if they are absent or blank, unless the <code>&lt;default&gt;</code> tag is present.

=== Using Lua functions ===
Lua functions (in particular those with multiple inputs) can be called wherever Wikitext is allowed, although it is generally used within the <code>&lt;format&gt;</code> or <default> tag, using an '''<code><nowiki>{{#invoke:}}</nowiki></code>''' statement. This will not be called or displayed unless there is a value in the parent's data source parameter.

=== DPL ===
"DPL" stands for [[Help:DynamicPageList|Dynamic Page List]] and is complex, powerful, but limited extension for wikis that can generate lists (primarily for tables) based on categories and other metadata (like time stamps and last editor). It is not enabled by default on FANDOM wikis, so you will need to request it be enabled to use it.

== Future directions ==
Details regarding functional replacements for Semantic MediaWiki (SMW) and possibly DynamicPageList inside infoboxes, as well as integrated HTML5 microdata, were discussed during [[w:c:connect|Community Connect 2015]], but nothing in detail.

== Examples ==
See [[Example_communities#Portable_Infoboxes|portable infobox examples]].

== See also ==
* [[Portable Infoboxes/Tips and tricks]]
* [[Portable Infoboxes/Faq]]
* [[Portable Infoboxes/Benefits]]
* [[Portable Infoboxes/Best practices]]
* [[Help:Infoboxes/Tags|Portable Infoboxes/Tags list]]

== Discussions ==
* [[Thread:2179|Making a simplified documentation (e.g. basics page)]]
* [[Thread:2196|A pros (and cons) page for portable infoboxes]]
* [[Thread:2211|Non-standard (or exotic) portable infobox uses]]


[[de:Portable Infoboxen]]
[[fr:Infoboxes portables]]
[[es:Infoboxes portátiles]]
[[pt-br:Infoboxes Portáteis]]
[[ru:Модульные инфобоксы]]
[[zh:訊息框]]
[[ja:ポータブルインフォボックス]]
[[Category:Documentation]]
[[Category:Overviews]]
[[Category:Portable Infobox]]
[[Category:Portability Hub core articles]]