Specs/HTML/2.5.0/Extensions/Gallery

< Specs‎ | HTML‎ | 2.5.0‎ | Extensions
  • T292657: mw-file-description added to media links to the file description page, which is the default
  • T108380: Set title for tooltips on media if caption isn't visible
  • T273505: Merge mw:Image|mw:Audio|mw:Video into a single mw:File
  • T297443: Use caption as alt on imgs when not present and caption isn't visible


Note: Gallery syntax is part of MediaWiki core, but is implemented as an extension tag in Parsoid.

The basic structure is as follows.

This gallery:

<gallery caption="caption1">
File:Image.jpg|caption2
</gallery>

Renders as:

<ul class="gallery mw-gallery-traditional" typeof="mw:Extension/gallery" data-mw='{"name":"gallery","attrs":{},"body":{}}'>
<li class="gallerycaption">... caption1 HTML ... </li>
<li class="gallerybox">
  <div class="thumb">... inline image HTML for Image.jpg ...</div>
  <div class="gallerytext">... caption2 HTML ... </div>
</li>
</ul>

packed-overlay and packed-hover modes add some additional structure around gallerytext

<div class="gallerytextwrapper"><div class="gallerytext">... caption2 HTML ...</div></div>

Attributes to support (on the extension tag):

  • showfilename
  • caption
  • mode
  • widths
  • heights
  • perrow
<gallery caption="caption1" showfilename="" mode="packed" perrow="4">...</gallery>

Renders as:

<ul ... data-mw='{"name":"gallery","attrs":{"showfilename":"","mode":"packed","perrow":"4"},"body":{}}'>... </ul>

A more involved example:

<gallery caption="Foo [[Main Page]]">
[[x|xx]]]]
File:Nonexistent.jpg|caption
Image:foobar.jpg|some '''caption''' [[Main Page]]
foobar.jpg
Image:foobar.jpg|Blabla|alt=This is a foo-bar.|blabla.
Image:foobar.jpg|link=Main_Page
</gallery>

Renders as:

<ul class="gallery mw-gallery-traditional" typeof="mw:Extension/gallery" about="#mwt3" data-mw='{"name":"gallery","attrs":{},"body":{}}'>
<li class="gallerycaption">Foo <a rel="mw:WikiLink" href="./Main_Page" title="Main Page">Main Page</a></li>
<li class="gallerybox" style="width: 155px;"><div class="thumb" style="width: 150px; height: 150px;"><span typeof="mw:Error mw:File" data-mw='{"errors":[{"key":"apierror-filedoesnotexist","message":"This image does not exist."}]}'><a href="./Special:FilePath/Nonexistent.jpg"><span resource="./File:Nonexistent.jpg" data-width="120" data-height="120">File:Nonexistent.jpg</span></a></span></div><div class="gallerytext">caption</div></li>
<li class="gallerybox" style="width: 155px;"><div class="thumb" style="width: 150px; height: 150px;"><span typeof="mw:File"><a href="./File:Foobar.jpg" class="mw-file-description" title="some caption Main Page"><img alt="some caption Main Page" resource="./File:Foobar.jpg" src="//upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Foobar.jpg/120px-Foobar.jpg" data-file-width="240" data-file-height="28" data-file-type="bitmap" height="14" width="120"/></a></span></div><div class="gallerytext">some <b>caption</b> <a rel="mw:WikiLink" href="./Main_Page" title="Main Page">Main Page</a></div></li>
<li class="gallerybox" style="width: 155px;"><div class="thumb" style="width: 150px; height: 150px;"><span typeof="mw:File"><a href="./File:Foobar.jpg" class="mw-file-description"><img resource="./File:Foobar.jpg" src="//upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Foobar.jpg/120px-Foobar.jpg" data-file-width="240" data-file-height="28" data-file-type="bitmap" height="14" width="120"/></a></span></div><div class="gallerytext"></div></li>
<li class="gallerybox" style="width: 155px;"><div class="thumb" style="width: 150px; height: 150px;"><span typeof="mw:File"><a href="./File:Foobar.jpg" class="mw-file-description" title="blabla."><img alt="This is a foo-bar." resource="./File:Foobar.jpg" src="//upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Foobar.jpg/120px-Foobar.jpg" data-file-width="240" data-file-height="28" data-file-type="bitmap" height="14" width="120"/></a></span></div><div class="gallerytext">blabla.</div></li>
<li class="gallerybox" style="width: 155px;"><div class="thumb" style="width: 150px; height: 150px;"><span typeof="mw:File"><a href="./Main_Page" title="Main Page"><img resource="./File:Foobar.jpg" src="//upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Foobar.jpg/120px-Foobar.jpg" data-file-width="240" data-file-height="28" data-file-type="bitmap" height="14" width="120"/></a></span></div><div class="gallerytext"></div></li>
</ul>

A showfilename example:

<gallery showfilename="">
File:Foobar.jpg
Image:Foobar.jpg|some '''caption''' [[Main Page]]
</gallery>

Renders as:

<ul class="gallery mw-gallery-traditional" typeof="mw:Extension/gallery" about="#mwt3" data-mw='{"name":"gallery","attrs":{"showfilename":""},"body":{}}'>
<li class="gallerybox" style="width: 155px;"><div class="thumb" style="width: 150px; height: 150px;"><span typeof="mw:File"><a href="./File:Foobar.jpg" class="mw-file-description"><img resource="./File:Foobar.jpg" src="//upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Foobar.jpg/120px-Foobar.jpg" data-file-width="240" data-file-height="28" data-file-type="bitmap" height="14" width="120"/></a></span></div><div class="gallerytext"><a href="./File:Foobar.jpg" class="galleryfilename galleryfilename-truncate" title="File:Foobar.jpg">File:Foobar.jpg</a></div></li>
<li class="gallerybox" style="width: 155px;"><div class="thumb" style="width: 150px; height: 150px;"><span typeof="mw:File"><a href="./File:Foobar.jpg" class="mw-file-description" title="some caption Main Page"><img alt="some caption Main Page" resource="./File:Foobar.jpg" src="//upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Foobar.jpg/120px-Foobar.jpg" data-file-width="240" data-file-height="28" data-file-type="bitmap" height="14" width="120"/></a></span></div><div class="gallerytext"><a href="./File:Foobar.jpg" class="galleryfilename galleryfilename-truncate" title="File:Foobar.jpg">File:Foobar.jpg</a>some <b>caption</b> <a rel="mw:WikiLink" href="./Main_Page" title="Main Page">Main Page</a></div></li>
</ul>

Editing support edit

All the extension attributes, except caption, need to be edited via data-mw.

Parsoid provides the raw extension body text in body.extsrc and raw gallerycaption in data-mw='{"attrs":{"caption":""}}' for clients to edit in a raw-text editor. If these data-mw properties are provided in the edited HTML, Parsoid uses that to generate serialized output for the extension. These properties should be removed from data-mw to enable serializing the HTML content instead.

As of December 2016, this HTML editing support should be considered experimental while we work with existing clients like VisualEditor to test the accuracy of this feature.