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

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


 * : 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.


 * : 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, is preferred for code clarity and simple understanding.


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

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