Reading/Multimedia/Media Viewer/Template compatibility

MediaViewer relies on special markup in templates to figure out how images should be handled and what information to show on them. The template detection code was based on Commons templates, since that is where most of the images reside, but it should work for images hosted on other wikis as well, as long as you have a reasonably similar template system (e.g. separate license and information templates) and add the required special markup to the templates. This page is supposed to help with that.

Updating templates in your wiki to work with MediaViewer

If you want to ensure the some type of metadata that is already handled by MediaViewer (license, description, author name etc.) will be read correctly for files which have been uploaded to your wiki, you need to present it in the same way it is presented on Commons. See the first two sections of COM:MRD (infobox templates, license templates) on how to do that. (Also, COM:GEO although currently it is not very helpful for figuring out how to make location templates in other wikis compatible.)

tl;dr: you need to add a certain HTML id or class to some container element in the template, and another one to the specific text that you want to be machine-readable (such as the license name) - this usually means wrapping the text in a ‎<span> which does not change anything visually (or maybe hides the text completely) but has a certain class or id.

So in practice it will look something like this:

<div class="licensetpl">
(lots of fancy HTML)
Licensed under the <span class="licensetpl_long">Do What the Fuck You Want
to Public License</span> (<span class="licensetpl_short">WTFPL</span>).
<span class="licensetpl_attr_req" style="display: none">false</span>
(more fancy HTML)
</div>

Alternatively, if you don't want to mess with existing template code, you can just add all the information in hidden fields, the way the PD templates do it on Commons. If you have lots of templates for the same license, and they do not share a common layout template, this way it can be done by a bot.

You may also want to use the exported test environment to get a kick-start on setting up templates.

Marking up article templates as ignored

By default MediaViewer processes most images on the page - this can be annoying with icons in article maintenance templates which pop up when the user tries to page through the images in the article with prev/next buttons in MediaViewer. To fix this, you can mark up a template as ignored by adding the metadata class to it; MediaViewer ignores all images in such classes.

Adding support for new metadata types

If you want to add some new kind of information to MediaViewer, you need to make sure there is a template which will provide it in the way described above (have a class that wraps the whole template plus a class for each specific piece of information you want to read from it).

Just marking up the template as a whole will probably not be enough. That way MediaViewer gets a big HTML blob instead of proper metadata. We would really like to avoid displaying big blobs of HTML which will clash with the design of the viewer in uncontrollable ways. We made an exception with permission templates, because they are important (also there is lots of them, and marking all up properly would be herculean work), we would prefer if we didn't need to make more. So please try to figure out what is the specific text (or link, logo image, whatever) that needs to be shown, and add specific markup for that.

(Also, before putting a lot of work into making some templates provide metadata, make sure somebody is willing to implement it on the MediaViewer side!)

Q&A

Q: I changed the template but don't see any effect!

A: Data parsed from files is cached for a month, or until the file description page changes. Doing a purge or a null edit on the file page will update the information.

Q: I want to mark up templates on my local wiki to be compatible with Commons templates. Are all the fields described on COM:MRD used by MediaViewer?

A: No, most aren't. You can check the source code if you need an exact list. (It is not as hard as it sounds!)

Q: Is the class wrapping the whole template ("licensetpl" in the above example) important?

A: Yes! We use it to know which fields belong together when multiple templates of the same type are used on the page.

Q: Does all information come from the templates described on COM:MRD?

A: No, some comes from categories (specifically assessment data such as featured image status - although we do not display it yet). That will not work for non-Commons-hosted images :( If you want to help with fixing that, see the previous section.

Q: What about internationalization on Commons and other multi-language wikis?

A: If the template uses MediaWiki messages for localization, that will work. Other methods probably won't. (Language templates like {{En }} work in {{Information }} and similar templates, but that's probably not a method that can be used for other types of metadata.)

Q: I am adapting templates for a new type of metadata. Should I use ids or classes?

A: Classes. Please. Using ids is almost always a bad idea. Using the same id twice on a page is invalid HTML and can cause unexpected behavior (XML parsers choking on the page, CSS selectors not returning all matching elements etc). You might think that the template will never need to be used twice on a page, but you will probably be proven wrong eventually.

(Also, ids are more trouble when adding CSS styles. Although using the same id/class for marking up metadata and for styling the content is probably a bad idea in itself.)