Page MenuHomePhabricator

[M] Gadgets should have a reliable way to add content to the subtitle
Closed, ResolvedPublic1 Estimated Story Points

Assigned To
Authored By
Jdlrobson
Aug 31 2022, 9:50 PM
Referenced Files
F36022242: Screen Recording 2023-01-06 at 4.51.54 PM.mov.gif
Jan 7 2023, 12:53 AM
F36022237: Screen Recording 2023-01-06 at 4.49.25 PM.mov.gif
Jan 7 2023, 12:53 AM
F36022229: Screen Recording 2023-01-06 at 4.46.58 PM.mov.gif
Jan 7 2023, 12:53 AM
F36022240: Screenshot 2023-01-06 at 4.49.17 PM.png
Jan 7 2023, 12:53 AM
F36022235: Screenshot 2023-01-06 at 4.49.17 PM.png
Jan 7 2023, 12:53 AM
F36022232: Screenshot 2023-01-06 at 4.44.49 PM.png
Jan 7 2023, 12:53 AM
F36022224: Screenshot 2023-01-06 at 4.41.45 PM.png
Jan 7 2023, 12:53 AM
F36022222: Screenshot 2023-01-06 at 4.39.34 PM.png
Jan 7 2023, 12:53 AM

Description

Vector is currently in the process of revising the content under the title. This caused breakage in certain gadgets (T315639) and highlighted a need for a more reliable stable API

Currently gadgets add content under the title by targetting the #contentSub element. The #contentSub element however is not always present - it just so happens various skins decided to mark up elements this way.

Going forward similar to mw.util.$content we should have an element that always represents the subtitle no matter what ID it has or it's position in the DOM.

Use cases

QA steps

Perform the following on the Timeless (useskin=timeless), Minerva (useskin=minerva) and Vector 2022 skins

  1. Run the following code:
var node = document.createElement('div');
    node.textContent = 'hello world!';
    mw.util.addSubtitle(node)

it should add hello world to the subtitle area (under the title).

  1. Run the following code:
mw.util.addSubtitle('<div>test</div>')

it should add test to the subtitle area (under the title).

  1. Clear subtitle
mw.util.clearSubtitle();

subtitle should disappear.

Sign off steps

  • Create a user notice

QA Results - Prod

ACStatusDetails
1T316830#8506084
2T316830#8506084
3T316830#8506084

Event Timeline

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

Change 828646 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/core@master] Skin: Gadgets should have a reliable way to add content to the subtitle

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

Seeking some thoughts on how this should work from skin developers. Please let us know!

Change 828650 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/skins/Vector@master] Subtitle: Prepare for standardized subtitle markup

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

I'm not familiar enough with Gadgets to judge that part, but having a more standardized way for them to interact with MediaWiki that skins can implement with little to no fuss is good in my book. I should note the comment on 828646 about skins being unable to hide it isn't exactly true, they can still hide it through CSS. This is actually a good thing, this allows users to opt-in through user CSS and gadgets to keep work in skins that just hide the element.

Change 828646 abandoned by Jdlrobson:

[mediawiki/core@master] Skin: Gadgets should have a reliable way to add content to the subtitle

Reason:

Not working on this right now.

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

Change 828650 abandoned by Jdlrobson:

[mediawiki/skins/Vector@master] Subtitle: Prepare for standardized subtitle markup

Reason:

Not working on this right now.

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

Jdlrobson renamed this task from Gadgets should have a reliable way to add content to the subtitle to (Medium) Gadgets should have a reliable way to add content to the subtitle.Sep 30 2022, 7:54 PM
Jdlrobson renamed this task from (Medium) Gadgets should have a reliable way to add content to the subtitle to [M] Gadgets should have a reliable way to add content to the subtitle.
Jdlrobson changed the point value for this task from 3 to 1.

Change 828650 restored by Jdlrobson:

[mediawiki/skins/Vector@master] Subtitle: Prepare for standardized subtitle markup

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

Change 828646 restored by Jdlrobson:

[mediawiki/core@master] Skin: Gadgets should have a reliable way to add content to the subtitle

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

Change 828650 abandoned by Jdlrobson:

[mediawiki/skins/Vector@master] Subtitle: Prepare for standardized subtitle markup

Reason:

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

ovasileva lowered the priority of this task from Medium to Low.Nov 21 2022, 6:39 PM

Moving to blocked on others to wait for feedback from other team's and community members. Any input much appreciated!

Change 828646 merged by jenkins-bot:

[mediawiki/core@master] Skin: Gadgets should have a reliable way to add content to the subtitle

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

Jdlrobson moved this task from Code Review to QA on the Web-Team-Backlog (Kanbanana-2022-23-Q2) board.

User notice: A new function has been used for gadget developers to add content underneath the title on article pages. This is considered a stable API that should work across all skins. You can try the API out on https://en.wikipedia.beta.wmflabs.org/wiki/Dog using code:mw.util.addSubtitle('Hello world');
I suggest putting this in the tech news after 15th, since there will be some caching implications with the new function for a few days (TTL for Varnish) meaning on cached pages the API might not work.

@Jdlrobson Thanks for the Tech News draft wording/timing, 'tis appreciated!

Re: example - Is there a translatable documentation page on mediawiki-wiki that we could link to instead of including it directly?

I tried searching, and found these (related? outdated?) pages which might either be the correct location for this documentation, or might be related-but-not-precisely-correct (but should perhaps link to wherever the correct location is?).
https://www.mediawiki.org/wiki/ResourceLoader/Core_modules#mediawiki.util
https://www.mediawiki.org/wiki/Manual:Skinning/Subtitle
https://www.mediawiki.org/wiki/Manual:Tagline_(Site_Subtitle)

Also, do any existing gadgets either need to or significantly benefit from migrating to this new method? I.e. Should we include a sentence urging gadget-authors to migrate? And if so, can we link to an example of a gadget that has been migrated? (e.g. I'd guess that XTools#ArticleInfo gadget might be related to this?)

FYI @ovasileva This has caused T324876 - I don't think this is a major problem but let me know if you think differently.

FYI @ovasileva This has caused T324876 - I don't think this is a major problem but let me know if you think differently.

No concerns from my side, prioritized T324876 separately

Change 867301 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/core@master] Parse API should not include #mw-content-subtitle element

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

Feedback from editing that T316830 is not working quite as we need it to, for the refresh use case so moving back to code review with the new patch.

Change 867301 merged by jenkins-bot:

[mediawiki/core@master] Parse API should not include #mw-content-subtitle element

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

Now added to https://meta.wikimedia.org/wiki/Tech/News/2022/51 - in the Recent changes section, with a link to the docs. Please amend if needed, within the next ~20 hours. Thank you!

Also, do any existing gadgets either need to or significantly benefit from migrating to this new method? I.e. Should we include a sentence urging gadget-authors to migrate? And if so, can we link to an example of a gadget that has been migrated? (e.g. I'd guess that XTools#ArticleInfo gadget might be related to this?)

I tried to migrate the XTools gadget and it works great, except on pages where there's no .mw-content-subtitle, such as the Main Page. I would have expected mw.util.addSubtitle() to create the element if it didn't already exist. Could that functionality be added? I tested in legacy Vector and Vector-2022.

It's #mw-content-subtitle and it will always be present in the page. It looks like meta wikipedia has some common CSS hiding the subtitle

With https://meta.wikimedia.org/wiki/Main_Page?safemode=1 and running mw.util.addSubtitle('hello world') it seems to work for me.

Perhaps your gadget could force the display or the site styles could be relaxed to not hide #contentSub ?

Edtadros subscribed.

Test Result - Prod

Status: ✅ PASS
Environment: enwiki
OS: macOS Ventura
Browser: Chrome
Device: MBP
Emulated Device:NA

Test Artifact(s):

QA Steps

Perform the following on the Timeless (useskin=timeless), Minerva (useskin=minerva) and Vector 2022 skins

✅ AC1: Run the following code:

var node = document.createElement('div');
    node.textContent = 'hello world!';
    mw.util.addSubtitle(node)

it should add hello world to the subtitle area (under the title).

TimelessMinervaVector 2022
Screenshot 2023-01-06 at 4.37.54 PM.png (864×1 px, 288 KB)
Screenshot 2023-01-06 at 4.39.34 PM.png (869×1 px, 229 KB)
Screenshot 2023-01-06 at 4.41.45 PM.png (873×1 px, 314 KB)

✅ AC2: Run the following code:

mw.util.addSubtitle('<div>test</div>')

it should add test to the subtitle area (under the title).

TimelessMinervaVector 2022
Screenshot 2023-01-06 at 4.44.49 PM.png (837×1 px, 420 KB)
Screenshot 2023-01-06 at 4.49.17 PM.png (864×1 px, 323 KB)
Screenshot 2023-01-06 at 4.49.17 PM.png (864×1 px, 323 KB)

✅ AC3: Clear subtitle

mw.util.clearSubtitle();

subtitle should disappear.

TimelessMinervaVector 2022
Screen Recording 2023-01-06 at 4.46.58 PM.mov.gif (916×870 px, 384 KB)
Screen Recording 2023-01-06 at 4.49.25 PM.mov.gif (916×870 px, 218 KB)
Screen Recording 2023-01-06 at 4.51.54 PM.mov.gif (916×870 px, 260 KB)

It's #mw-content-subtitle and it will always be present in the page. It looks like meta wikipedia has some common CSS hiding the subtitle

With https://meta.wikimedia.org/wiki/Main_Page?safemode=1 and running mw.util.addSubtitle('hello world') it seems to work for me.

Perhaps your gadget could force the display or the site styles could be relaxed to not hide #contentSub ?

Bah, thanks for pointing that out! I'm not going to bother trying to fix Meta's Common.css (though it seems fairly safe to just remove the problematic rule). If wikis or individual users want hide the elements used by the gadget, the gadget shall respect that.

Change 919241 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/core@master] Remove and correct selector for cached HTML

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

Change 919241 merged by jenkins-bot:

[mediawiki/core@master] Remove and correct selector for cached HTML

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