Help:Infobox migration

This is a step-by-step guide to fast, easy conversion of classic wikitext infoboxes to Portable Infoboxes. While it is impossible to cover every single type of infobox — as some infoboxes are more exotic than others — you should find that these instructions are broadly applicable to most situations.

It is written for people of all skill levels, and definitely is not intended only for use by portable template specialists. It should be a good guide to building good infoboxes from the beginning. There are "best practices" and portability principles scattered throughout for additional insight.

Fundamentals

Before you get started, you should ideally be familiar with:

• basic wikitext
• the notion of CSS selectors and properties
• the fact that the terms classic infobox, non-portable infobox, and NPI or nPI all mean the same thing

Because Portable Infobox markup is actually XML, it'll also help to know what's meant by "XML well-formedness". However, since migration with the migration naturally results in XML being well-formed, this is typically more of a diagnostic skill than one actively needed to make Portable Infoboxes.

Step 1: Finding your infoboxes

Before beginning the conversion process, you first have to figure out which templates need to be converted. This means finding all your templates. If you're lucky, most of them will be in a category, often called Category:Infoboxes or Category:Infobox templates.

Step 2: Inventory of potential themes and variations

The first part of this is fairly simple. For the infoboxes to be migrated, look at the articles where the templates are in place with Special:WhatLinksHere (found on the Insights page as "Used on X articles". Examine the general visual style of each template and note if they use a consistent style or "look", or if they look mostly the same as each other (but could be made consistent), or if they look completely different. Each major difference in style will potentially become a theme later. Be sure to note what components are consistent (such as color or rounded corners) across most themes, so that those traits can be added to the default .portable-infobox style when you create it.

The second part is potentially very technically challenging, but is necessary for a consistent replacement of a community's classic infoboxes. The easiest way to do this is to look at the source code for the classic infobox for places where the styling is changed by a parameter, such as class="{{{roundy|10px}}}" or style="width: {{{width|250px}}}; background-color: {{{bgcolor|white}}}". In that last example, bgcolor is likely to be used as a theme-source parameter.

Step 3: Copying the accessory code (noinclude and includeonly)

Templates work by transclusion - insertion of a source template into any target article. Often enough, some parts of a template aren’t useful in all cases, so we use transclusion control tags to control that:

<noinclude>

hides content within tag in target article

Often enough, a template will need certain sections hidden within articles. Documentation, infobox previews and template categories are good examples of this.

<onlyinclude>

hides content outside tag in target article

This tag is less commonly used, but quickly separates an infobox from the other template contents. In general, <includeonly> is preferred for code clarity and simple understanding.

<includeonly>

hides content within tag in source template

The infobox itself, accompanying article categories, and hatnotes are also likely to be hidden on the template page itself. This helps prevent bugs with nPI detection.

Keeping a vital part of the old infobox

The original non-portable infoboxes will likely be comprised of two parts: the infobox table itself, and documentation, categorisation, navigation and other supporting information outside the table. It will often look like this:

{|class="infobox"

. . . various lines of code

|}

<noinclude>{{documentation}}[[Category:Infoboxes]]</noinclude>

Copy everything that comes both before and after the main body of the NPI code. That is, copy everything that's above and below the {| and |}. In the new PI's code, replace the automatically-generated documentation in the PI with what you've just copied from the old NPI. In the above example:

<noinclude>{{documentation}}[[Category:Infoboxes]]</noinclude>

should be used to replace any automatically-generated documentation on the NPI.

Step 4: Translate the layout and groups of the classic infobox

Because of the way some classic templates are coded, wikitext parameters may be interpreted out of order, or were never intended to be visible at all. The best way to shape it properly is to go from top to bottom and start placing items into the proper order and groups.

Portable Infoboxes feature automatic hiding if no value is supplied, so additional code to hide these data items is not necessary. In fact, if a <group> has a <header> inside and no items of the group have values, the header will not display.

NOTE: Many communities define values as "Unknown" in their infoboxes when no value is given. While acceptable, this is not ideal (and tends to produce visual clutter) unless a strict horizontal grid layout is required, which should use the show="incomplete" function.

Data types

Is it image, title, data, navigation, header, etc? This is not always straightforward.

• <title> handles titles, and those titles do not feature visible labels. To be truly data-ready, it should also handle alternative titles, such as those in other languages, title translations, or subtitles. In CSS, it's easy to style secondary titles with something like .pi-title ~ .pi-title
  • Many infoboxes are autogenerated with <title source="name"><default>{{PAGENAME}}</default></title>. To maintain the cleanest possible code, this should be altered to <title source="name"><default><includeonly>{{PAGENAME}}</includeonly></default></title> when possible.
  • Titles by language should be consolidated into a single data item where they are equivalent, such as kanji / kana / rōmaji representations of the same title. A visual indicator of what language is being used is not typically required, though using a flag to represent a language is a bad practice; if a variety of title translations (beyond the source language and the wiki's language) are provided, these should be <data> items in a <group>.
  • Titles by region or language region should be separate, such as Spanish-language titles that are different in Spain and Latin America. This is because they are ultimately different pieces of data.
  • A logo for a subject should be secondary to a textual representation of a title, so it should be either a secondary title or a <data>.
• <image> handles feature-size images, and those images do not feature visible labels.
  • Image fields only handle image data. Mixed image and text will show only the image.
  • Image fields may contain either a <tabber> or <gallery> child to produce a tabbed gallery (or a slider gallery on mobile devices). Due to code simplicity, <gallery> is preferred. Depending on how this feature is used, it may be required to change to using a {{#tag:gallery}} parser function instead. Not all gallery properties that are available outside an infobox are available inside one, such as slideshows.
  • The <caption> child tag handles captions. If an image field has a <gallery> inside, the "caption" used for the gallery item becomes the tab label.
  • Image fields do not require full File paths nor internal File: links, though they will accept them under most circumstances. However, any size or caption information added to the File: link will have no effect.
  • Image fields will dynamically resize images (that are wider than 130px) to have the best fit on any platform, to a maximum of 270px – 300px. Smaller images, if they truly describe the subject of the infobox, will simply stay at their native size; if the smaller image is a game icon, or similar supplemental information, it should be a <data> field instead.
• <data> is your typical area for most other parameters.
• <navigation> is a label-less area for arbitrary wikitext.
  • Icons in the upper "title" area should be considered navigation, as they are neither explicitly a <title> nor an <image>.

Groups

Typical, vertical groups are easy to recognize. For horizontal groups, there are two choices: traditional "horizontal" layout, and "smart" groups. Each can be styled differently, if there is cause to do so, but there may be reasons to choose one or the other. Traditional horizontal groups are rigid, and are meant for a small and set number of items when there's little variation. For example, Previous & Next fields should use horizontal groups. They should be used on logical groups where the layout is a maximum of one layout row. Smart groups are meant for potentially larger, varied sets of items. They are responsive to the number of items, and will wrap each item to a new layout row when they reach the maximum number of items defined in the row-items group property.

Data Labels

Data labels can contain most wikitext. They should also respect <noinclude> (to clarify a label in a way that is not displayed, for editing purposes) and <includeonly> (to display parts of a label that should only appear in an article, not the editor). If they additionally contain an infoicon, they should be careful to avoid accessibility issues. Only <data> items have visible labels.

From a readability and accessibility perspective, it should be noted that vertically centered labels do not well define a taller data item, as the human eye tends to bounce around in unexpected ways. Also, short labels like "ATK" and "DEF" might make sense to an English-native reader, but should have use <abbr> to help the comprehension of others that may be unfamiliar with either the topic or language. In contrast, very long labels without line breaks may be better simplified into smaller words. An equal width of label to value (i.e. 50% label width) is similarly less readable with vertical data items as it pulls away emphasis from the actual value (and usually adds colored whitespace), and should be avoided in new templates. If a label width must be increased, the proper CSS property is flex-basis.

Step 5: Defaults and Formats

It is typically a good idea to have the simplest input data to feed the template, reduced to a simple data-type (such as a number, strings of text, links, or lists of these). To that end, the <format> tag can reshape raw input into formatted output. For example, an item with a cost of "10 gold" (assuming that "gold" is the only possible currency unit for that data value) can have the input of "10" and use the <format> tag to show the visible value as "10 gold" (or use an in-game infoicon for gold, etc.). The <format> tag can be used in the <data> or <title> tags, but not <image> or <navigation>.

Default values with <default> appear only when the article does not provide a value for the parameter named in source=. The <default> tag can be used in the <data> or <title> or <image> tags, but not <navigation>.

Default values should avoid "Unknown" or "-" type defaults unless they are required for layout. Portable Infoboxes are designed to not show values that are not used in an article's template call, so logic to hide it is not necessary; further, if no data items in a group are used, the group and its header will not appear unless the show="incomplete" attribute is added to the group.

TIP: Automation is not always a good idea. On the surface, skipping the name or title in favor of the {{PAGENAME}} magic word is efficient, but can be problematic when the page name changes or is qualified or disambiguated or the title contains characters or markup that can't be duplicated with an article name. Having other elements, like images, dependent on page name can make things much more difficult if a community's users do not understand the inner magic and logic of your template for basic data entry or maintenance. Calling helper templates, Lua functions, or complex nested ParserFunctions all can contribute to user confusion if the templates ever need to be revised or untangled.

If a data item needs no processing (i.e. only the {{{parameter}}} is used and not modified with functions or styling), the <default> and <format> tags do not need to be included at all. This function alone drastically simplifies some classic infoboxes upon migration. Otherwise, using <default> and <format> effectively is at the core of infobox migration, as many templates process

Tip: If you are adding a category that is dependent on a <data> value, declaring that Category in a switch here will save you from doing it later.

Step 6: Styling

Here is another area where classic infoboxes lose much of their bulk upon migration. Styling in PIs is accomplished using global CSS. Inline CSS (with the style and class attributes) is removed whenever possible.

If all items of the same type are styled identically, these styles should be shifted to the default .portable-infobox CSS or a theme.

If a value is styled differently from the others of its type (e.g. a Rōmaji transcription in italics next to kanji or kana), wikitext (e.g. ''') or an appropriate HTML tag (e.g. <dfn>) used to offset them inside <format>. Wikitext that does not use CSS is always considered portable.

It is strongly suggested not to alter the width of infoboxes from the default using CSS, as images inside the infobox will begin to exceed the boundaries of the infobox. Images that are narrowed using CSS inevitably become distorted.

Theming and accent color

Styling PI in CSS is a more complex topic than this guide allows for, but it is covered in some depth in Help:Infoboxes/CSS.

Bonus Step: Setting up central CSS and approving the Drafts

The Vanguard teams have their own policies and procedures for approaching communities, but communities may choose to use many of the same tools and ideas that have proven effective. Dependent on the complexity of CSS and supporting code, a separate sandbox wiki is usually not necessary. Developing the template code directly on the main community using the Draft system is straightforward and makes testing the new template against existing articles easier, as it will provide as good or better results than a standalone testing wiki.

The Draft system is very effective for being able to quickly test templates applied to a page, by previewing the page with /Draft added to the end of the template name. This is similar to using /sandbox. It works on all templates, not only infoboxes.

Placing .portable-infobox and other PI-specific CSS in a separate stylesheet (MediaWiki:Themes.css) imported to MediaWiki:Wikia.css can also be helpful. The import line in the main skin stylesheet @import url("/load.php?mode=articles&articles=MediaWiki:Themes.css&only=styles"); will load the Themes.css in an optimized manner.

Conclusion

Porting classic infoboxes to PIs can make them much simpler for future maintenance, and allow for comprehensive style changes without recoding many templates. The language is designed to be both flexible and powerful. If you run into migration issues, feel free to get help on the Portability Hub or contacting a Vanguard member.