Proposed spec for Parsoid's gallery implementation

ActivePublic

Actions

caption="Foo [[Main Page]]" doesn't seem to be accounted for in the output.

Still need to comb through the rest of the examples in https://gerrit.wikimedia.org/r/#/c/264026/5/tests/parserTests.txt

Moved comment to bug

So, basically, we expect the output to be a <div typeof="mw:Extension/gallery"> with data-mw encoding the attributes given, and then the first child should be a div.gallerycaption, then subsequent children should match the parsoid image spec exactly, with the sole exception that if the gallery showfilename option is given, then each caption will be preceded by <span class="showfilename"><a href="./File:Foobar.jpg">File:Foobar.jpg</a><br/></span> while would presumably be ignored upon serialization.

Questions:

1. is it actually possible to style this using CSS to match gallery output without further HTML element structure? It would be useful to compare this with the PHP output.
2. the caption attribute in the top-level data-mw appears to be redundant with the div.gallerycaption. If they disagree, which do you serialize? I always prefer to remove redundancy in the representation. Is there some reason why caption needs to be in data-mw? (Perhaps, as for standard captions, there's some option which hides the caption? But I think <gallery> will always be a block element, right, so we don't have the issue we do with inline images containing block elements in the caption.)
3. The <a> tag in span.showfilename doesn't match the rel and other attributes of normal wikilinks, which means that these won't be picked up by css selectors intended to identify all links.
4. Is <span> actually correct for .showfilename? I'd think you'd want the filename on a line by itself? But I'm not actually familiar with the <gallery> output, so maybe not.
5. In general it's not entirely clear to me how this is serialized; which properties are used and which are ignored.

The PHP <gallery> output seems to have a <ul class="gallery"> as the top level element, and then each image is inside its own <li>. Then the output contains three separate nested <div>s before an <a> tag and then finally <img>. That is, each image matches ul.gallery > li.gallerybox > div > div.thumb > div > a > img, with the caption for that image matching ul.gallery > li.gallerybox > div > div.gallerytextwrapper > div.gallerytext (for packed-hover or packed-overlay modes) or ul.gallery > li.gallerybox > div > div.gallerytext (for traditional, nolines, or packed modes). That is probably an excessive amount of wrapping, but we'd probably need to actually write some CSS rules for equivalent display to be sure. Even if we need all these wrapping classes, we should be able to unify the position of the caption element in the different modes. There appears to be javascript to do the actual gallery layout; if we update the structure we'd likely need to update the JavaScript as well.

Also:

The gallery tag itself takes several additional parameters, specified as attribute name-value pairs:

• caption="{caption}": (caption text between double quotes for more than a word) sets a caption centered atop the gallery.
• widths={width}px: sets the widths of the images, default 120px. Note the plural, widths.
• heights={heights}px: sets the (max) heights of the images.
• perrow={integer}: sets the number of images per row. 0 means automatically adjust based on width of screen.
• showfilename={anything}: Show the filenames of the images in the individual captions for each image (1.17+).
• mode={traditional|nolines|packed|packed-hover|packed-overlay}: See section above (1.22+).

Since "[t]he widths and heights parameters are taken more as suggestions than strict values for packed (and related) modes. Packed modes will adjust the width of images in order to make each row the same length", we probably need to put the specified widths/heights attribute into data-mw somewhere. I'm not sure the perrow attribute is actually honored anywhere.

2. the caption attribute in the top-level data-mw appears to be redundant with the div.gallerycaption. If they disagree, which do you serialize? I always prefer to remove redundancy in the representation. Is there some reason why caption needs to be in data-mw? (Perhaps, as for standard captions, there's some option which hides the caption? But I think <gallery> will always be a block element, right, so we don't have the issue we do with inline images containing block elements in the caption.)

Removed the caption from the data-mw.

3. The <a> tag in span.showfilename doesn't match the rel and other attributes of normal wikilinks, which means that these won't be picked up by css selectors intended to identify all links.

But that's true of the php implementation as well. I assume you're going to say we should fix it there as well, but I imagine if that was desirable, it would already have been done.

4. Is <span> actually correct for .showfilename? I'd think you'd want the filename on a line by itself? But I'm not actually familiar with the <gallery> output, so maybe not.

There's a linebreak after the link, same as the php side. Like,

<span class="showfilename"><a href="./File:Nonexistent.jpg">File:Nonexistent.jpg</a><br/></span>

The span is just to group them so that we can just drop that content before serializing the caption.

Hmm, seems like that changed in T139766. It's now,

<a href="/wiki/File:Foobar.jpg" class="galleryfilename galleryfilename-truncate" title="File:Foobar.jpg">Foobar.jpg</a>

1. is it actually possible to style this using CSS to match gallery output without further HTML element structure? It would be useful to compare this with the PHP output.

I added some structure.

6. In general it's not entirely clear to me how this is serialized; which properties are used and which are ignored.

At present, the gallery attributes (mode, widths, heights, perrow, showfilename) will be taken from the data-mw. The rest, including the gallery caption, will be serialized from the HTML.

Opening a discussion with @Esanders to see whether this is feasible.