Help:Infoboxes/Migration walkthrough

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 0: 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   or  .

But sometimes infoboxes won't be filed away neatly. That's when you have to look for templates by  classification . When in doubt, examine what the template's intended role is. The best place to start is to look at  . You may sometimes see Vanguard members shorthand "unclassified templates" as "UTs".


 * Look at each template entry in Templates Without Type that seems like it may be an infobox. If it is a complete and self-contained infobox, classify it as  Infobox . If it is a component to build part of an infobox, that is usually  Data  (if it's changing the actual text) or  Design  (if it's changing how the content or element looks).
 * Change the classifications of those templates by selecting (clicking or tapping) the classification (which appears as a link near the Template page's title) or using the "k" key shortcut. A partial window panel (called a "modal") will appear to select the new classification.
 * If you have several templates put into a category, you can use the " Bulk template classification " tool to massively classify them. The tool can be only used by local admins or some volunteer groups, such as VSTF and Vanguard.

"NOTE: Changes in classification will not usually appear in Insights until the next day, as they are cached once daily. Non-Insights Special pages, like, are updated more frequently (but not in real-time)."

Step 1: Insights
  is the spine of infobox porting work for a community. It also will sometimes show false positives (or templates that are not really infoboxes, or appear in no articles).

Scroll down to the bottom of the   list and classify templates that appear on 0 articles as  Non-Article , or other appropriate classification. As Template Documentation pages may appear in this list — but by definition are not intended for article pages —  Non-Article  is the proper classification. See Step 0 for more detailed instructions.

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   (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=" " or style="width:  ; background-color:  ". In that last example, bgcolor is likely to be used as a theme-source parameter.

Step 2: The "Convert!" button, and what it does and doesn't do
When a template is classified as Infobox but does not use the Portable Infobox syntax, a "Convert!" button will appear in the Insight page next to the template (and in the Template page's rail). This button triggers a migration tool that partially converts the non-portable infobox into a Portable Infobox  draft . The tool will usually detect all variables used by a classic infobox and convert them into appropriate Portable Infobox syntax. It is familiar with the most commonly used code patterns for labels, default values, and attempts to recognize and convert them for Portable Infobox roles.

Though this tool is useful and can do a major part of the migration itself, there will usually be some work which has to be done manually. Most of variables will be converted into 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: 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 general shape and structure of these infoboxes is not detected with the migration tool. 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 has a 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.
 * 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 . To maintain the cleanest possible code, this should be altered to   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  group property.

Data Labels
Data labels can contain most wikitext. They should also respect  (to clarify a label in a way that is not displayed, for editing purposes) and   (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  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  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.

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 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 tag to show the visible value as "10 gold" (or use an in-game infoicon for gold, etc.). The tag can be used in the

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   added to the end of the template name. This is similar to using  . It works on all templates, not only infoboxes.

Placing  .portable-infobox  and other PI-specific CSS in a separate stylesheet ( ) imported to   can also be helpful. The import line in the main skin stylesheet  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.