Page MenuHomePhabricator

Render references list in multiple columns based on the number of items
Closed, ResolvedPublic40 Estimated Story Points

Description

Author: a.d.bergi

Deployment:
This ticket has been implemented, please read about this new feature and its deployment plan at https://www.mediawiki.org/wiki/Editing/Projects/Columns_for_references . This is an *opt-in feature* everywhere.
This means that, when editing a group of references, it is possible to choose that the columns are responsive. Only some wikis have that flag enabled by default instead. See the MediaWiki page linked above to request that it becomes a default option at your wiki.

Original description:
The German Wikipedians would like to format the references list in multiple columns (http://de.wikipedia.org/wiki/Wikipedia:Umfragen/Multicol). This CSS3 technique is already used on en:wp, but there it is tied to a template.
We do not want to make the same mistake: templates are evil, mostly because another new syntax would be confusing, they cost (little) parser resources, and they would have to be spread over all articles. A native implementation would be much cleaner, and hereby I'd like to request one.

Of course it would be quite simple for us to just add some lines of code to MediaWiki:common.js, but that doesn't fulfil our requirements.
The points mostly named are:

  • It should be simple: a plain <references /> should do everything automatically.
  • Very few lines of references don't look good as columns. An automatic solution can't be done with templates; I'd propose counting the ref-tags to display and when the count is higher than an integer variable (configurable as a system message) a "column"-class should be added to the list tag.
  • There will always be cases where the automation doesn't work or the article author wants something special. So he must be able to set the layout manually (on/off). This /could/ be done by solving T8019; which should be not that difficult, see r81865 for example), but I think a simple on/off switch per parameter would be enough.
  • Different colum widths should be settable, fitting to the content (size of the ref-tags). I don't think this is automatable, it's just that there should be an option to change it.

Implementing the ref-count and fixing T8019 would be enough, but I think we should implement a more specific solution that also prohibits uncontrolled usage.

I would propose the following algorithm (for each <references />-tag):

  1. Fetch "cite colums autonumber", "cite columns autoclass" and all "cite colums width-*" system messages. The first should contain an integer, the latter ones DOMStrings.
  2. Look if the references-tag has a "columns"-attribute
    1. If so, look up whether its value fetches the name of one of those "cite_columns_width-..." messages
      1. If so, use the message content as the class name
      2. Else set the class empty. E.g. values like columns="none" could be used the prevent multicoumn layout.
    2. When there is no attribute, count the <ref>-tags which should get displayed in the current list. If that number is higher than (or equal to) the "cite columns autonumber"-message,
      1. then use the content of the "cite columns autoclass"-message as the class name
      2. else set the class empty
  3. Add the class name to the "class" attribute of the ol-element (behind the "references ").

This should allow the wiki admins a very precise, local configuration (with Mediawiki-messages and the local CSS files), and make the usage of this feature as simple as possible.

Related Objects

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
Jdforrester-WMF subscribed.

Did someone work on this project during#Wikimedia-Hackathon-2015? Otherwise please remove the label.

Yes, @Krinkle did at Wikimedia-Hackathon-2015.

Change 229852 had a related patch set uploaded (by Krinkle):
Implement mw-references list with responsive columns

https://gerrit.wikimedia.org/r/229852

See also https://phabricator.wikimedia.org/T53260#550341.

I'd like to see this implemented. But I'd like to question some of the requested configuration options.

[snip]

I would guess that there might be different requirements for the various non-Latin script languages (e.g. Farsi, Russian, and Japanese). Most citations in European languages I would guess extend to a full 1000-1200 px on a single line (e.g. from a web citation), but those languages might be able to fit a citation in a smaller amount of space, meaning their need for columns would come only with a larger number of citations.

Krinkle lowered the priority of this task from High to Medium.Jan 5 2017, 3:36 AM
Jdforrester-WMF set the point value for this task to 40.Feb 3 2017, 9:32 PM

Points applied mostly due to extremely delicate roll-out need to avoid disrupting community processes and content.

Change 341708 had a related patch set uploaded (by Krinkle):
[operations/mediawiki-config] Disable wgCiteResponsiveReferences by default for back-compat

https://gerrit.wikimedia.org/r/341708

Change 341708 merged by jenkins-bot:
[operations/mediawiki-config] Disable wgCiteResponsiveReferences by default for back-compat

https://gerrit.wikimedia.org/r/341708

Mentioned in SAL (#wikimedia-operations) [2017-03-08T00:08:37Z] <catrope@tin> Synchronized wmf-config/InitialiseSettings.php: Disable wgCiteResponsiveReferences by default for back-compat (T33597) (duration: 00m 41s)

Change 229852 merged by jenkins-bot:
[mediawiki/extensions/Cite] Implement responsive columns for reference lists

https://gerrit.wikimedia.org/r/229852

OK, this is now live in master, and will be rolling out next week in wmf.16.

The code is disabled on pages by default on all wikis except test wikis and MW.org.

On the default-on wikis, reference lists will have multiple columns, and to disable this, uses of <references /> can be edited to opt out by changing them to <references responsive="0" />.

On the default-off wikis, nothing will change. Uses of <references /> have to be edited to opt in by changing them to <references responsive />.

The next task is to help each wiki's communities convert their templates over to use <references responsive /> explicitly, or opt out if they can't be fixed. Once they are fixed, we can then enable it for the entire wiki.

OK, this is now live in master, and will be rolling out next week in wmf.16.

The code is disabled on pages by default on all wikis except test wikis and MW.org.

On the default-on wikis, reference lists will have multiple columns, and to disable this, uses of <references /> can be edited to opt out by changing them to <references responsive="0" />.

On the default-off wikis, nothing will change. Uses of <references /> have to be edited to opt in by changing them to <references responsive />.

The next task is to help each wiki's communities convert their templates over to use <references responsive /> explicitly, or opt out if they can't be fixed. Once they are fixed, we can then enable it for the entire wiki.

Migration details for template authors

<references responsive /> will automatically wrap the list in <div class="mw-references-wrap">. Any list with more than 10 references will also get the class mw-references-columns. In this mode, the references list is automatically split over multiple columns based on the available space on the screen. E.g. on narrow screens 1 or 2 columns, on wider screens 2 or 3. Given that this happens automatically, it is no longer necessary for editors to manually enable/disable the columns mode of a template.

Remember also that other customisations for the references list are best applied directly to the ol.references CSS selector in your wikis' MediaWiki:Common.css. Many wikis customise the font-size this way, for example. (No need to manually code it through a template). In case a DIV wrapper is needed for certain styles, the .mw-references-wrap CSS selector will apply to all references lists produced by <references responsive /> regardless of whether the columns were dynamically activated.

@Jdforrester-WMF how does one know whether a wiki is default ON or OFF?

Wikisources which typically convert page footnotes to compiled endnotes, and we have typically not utilised columns (imagine a footnote table squashed into a column). I would suggest that they will prefer to be in OFF. Can that be taken as the default position and give those communities the ability to opt-in?

@Billinghurst it would seem to me that https://www.mediawiki.org/wiki/Editing/Projects/Columns_for_references has the answers to your questions does it not ?

Do you have example links of your 'typical' usage btw, that can always be handy.

@Billinghurst it would seem to me that https://www.mediawiki.org/wiki/Editing/Projects/Columns_for_references has the answers to your questions does it not ?

Do you have example links of your 'typical' usage btw, that can always be handy.

Okay, so the overt statement is ... default for all wikis is OFF, and wikis need to OPT-IN.

@Billinghurst it would seem to me that https://www.mediawiki.org/wiki/Editing/Projects/Columns_for_references has the answers to your questions does it not ?

Do you have example links of your 'typical' usage btw, that can always be handy.

You were after some examples from a Wikisource

  • simple list of by page footnotes that become endnotes when transcluded

https://en.wikisource.org/wiki/A_colonial_autocracy,_New_South_Wales_under_Governor_Macquarie,_1810-1821/Chapter_3

  • quoted/excerpts of correspondence, poetry, other works

https://en.wikisource.org/wiki/My_Life_in_Two_Hemispheres/Chapter_15

  • example of a small table that is joined from two separate references (use of <ref name=> and <ref follow=>)

https://en.wikisource.org/wiki/Considerations_on_the_state_of_Ireland

  • longer list with a table

https://en.wikisource.org/wiki/A_colonial_autocracy,_New_South_Wales_under_Governor_Macquarie,_1810-1821/Chapter_6

I cannot readily find a work with references with complex tables, so that will have to a be a raincheck.

It's probably relevant to point out that the feature is opt-in and opt-out per page as well. They can set a default per wiki (if not specified on the page, then do X), but any editor can override that default on any page.

The ideal arrangement for each wiki is to choose a reasonable default (based on a typical/most common type of page) and then override that default whenever the other behavior is wanted on any individual page. So, for example, the Wikipedias should probably choose to have responsive columns by default, but can and should make individual pages be non-responsive (e.g., an explanatory footnote that contains a table or gallery). The Wikisources might decide to have a single column by default, but can and should make individual pages be responsive (e.g., a project page or a page that has lots of columns of plain text in the original).

Hi, on zhwp there seems to be still some good amount of confusion among almost-techy (bot-capable) users (including sysops, sadly), so I added a paragraph in the document to clarify the process up. Please find some time to review these changes, possibly perform some copyedit, and ideally mark these text for translation. Pretty sad to see people opposing stuff with questions in mind.

I want ask that Could it the tag add two parameters ('class' and 'style') to set custom div's class and style when it have the 'responsive' parameter?

Old tag is a clean output which is only a ol.references. Some designs of consumers, like some wmf's wiki, will add a custom div which sets a custom div's class and style to include the ol.

If the auto columns is on acquiescently, the custom div will make the structure become complex beacause of the two div's nest. There are two ways, One is keep the old tag's style to keep the custom div's class and style, The other is only use new tag's style ,give the custom div up which it will lose the custom div's class and style because the new tag is no the enter to set it more.

If I need the class and style of custom div for ol.references, the auto columns, and NO div's nest, I suggest that parameters 'class' and 'style' should be added when the 'responsive' parameter is on.

Here it comes.

Old tag is a clean output which is only a ol.references. Some designs of consumers, like some wmf's wiki, will add a custom div which sets a custom div's class and style to include the ol.

Why fear adding another div? Nobody, not even normal CSS/JQuery selectors found in zhwp's MediaWiki:Common.css (all without a strict >), will consider that a problem.

If the auto columns is on acquiescently, the custom div will make the structure become complex beacause of the two div's nest. There are two ways, One is keep the old tag's style to keep the custom div's class and style, The other is only use new tag's style ,give the custom div up which it will lose the custom div's class and style because the new tag is no the enter to set it more.

Again, nesting is not a problem. Nobody will see.

If I need the class and style of custom div for ol.references, the auto columns, and NO div's nest, I suggest that parameters 'class' and 'style' should be added when the 'responsive' parameter is on.

Forwarding the class and style can be a lovely feature to have, but are you sure it belongs to this task?


Figured out this thing would have been easier to explain if I just called it {{reflist|35em}} by default.

Logged https://phabricator.wikimedia.org/T166293 - AutoWikiBrowser does not recognise <references responsive/> and assumes the article needs a {{Reflist}}