Page MenuHomePhabricator

OOUI tutorial migration
Closed, ResolvedPublic

Description

Synopsis

A standalone tutorial page that links back to the Docs and Demos with styling that uses OOUI css (MVP).
If time permits: (1) Additional tutorial page(s); (2) Installation instructions.

Document with some initial thoughts and ideas.

Timeline

PeriodTask
July 9 - July 13Create initial Tutorial: 1 page with top bar linking to Docs and Demos, working lives demos of the ToDo app and code snippets.
July 16 - July 20Use PrismJS for syntax highlighting. Update ToDo app code to comply with current state of OOUI core stylesheet. Add header links. Update installation instructions. Design demo app boxes. Ensure coherence and cohesion of the entire text.
July 23 - July 27Review. Modify folder structure. Revamp Basics2 tutorial. Make a page footer with links and a back to top button. Create an index page with links both tutorials. Fix some problems in Basics2 tutorial, such as date/time display.
July 30 - August 3Following the review/feedback, make corrections and modifications, and design/Implement additional UX/UI features for this and future tutorial pages as needed. Extract relative page URLs. Add dropdown menu with links to all tutorials, as part of top toolbar. Check license of fonts if we end up using them.
August 6 - August 10Code cleanup for submission, HTML and CSS in particular. Make page footer responsive. Test final tutorial apps for appearance and functionality. Test links.

Deliverables

Design and implement an up-to-date version of the OOUI tutorial as part of the OOUI demos repo, as an additional page. The new tutorial will be based on Moriel's OOUI tutorial.

Details

Related Gerrit Patches:

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJul 5 2018, 11:06 AM
Hagarshilo updated the task description. (Show Details)Jul 5 2018, 1:59 PM
Hagarshilo updated the task description. (Show Details)Jul 5 2018, 4:46 PM

Change 444389 had a related patch set uploaded (by Hagar Shilo; owner: Hagar Shilo):
[oojs/ui@master] Create initial tutorial page

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

Volker_E moved this task from Backlog to Doing on the OOUI board.Jul 9 2018, 10:22 PM
Hagarshilo updated the task description. (Show Details)Jul 12 2018, 3:51 PM
Hagarshilo updated the task description. (Show Details)Jul 15 2018, 9:20 PM
Hagarshilo updated the task description. (Show Details)Jul 16 2018, 9:32 AM
Hagarshilo added a comment.EditedJul 16 2018, 10:08 AM

OOUI theme issue

The original tutorial app uses light blue highlights that seem to no longer be a part of oojs-ui-core-wikimediaui.css, the theme that the users are instructed to use in the tutorial.

However, these style rules do exist in the Core Apex theme (oojs-ui-core-apex.css). I found and copied them into tutorial.css for now. The problem is, users will be using oojs-ui-core-wikimediaui.css, not the tutorial theme and not the Apex theme.

Is there any way to style the SelectWidgets and OptionWidgets with such highlights when selected and hovered, using only oojs-ui-core-wikimediaui.css?

This is what the live demo apps in the new tutorial look like with the blue highlights (Demo #3):

@Hagarshilo There's this related task T166560: Consider changing :hover tools and menu background to use Accent90 – we could pick it up again and implement it in course of the tutorial. In any case we should stay with the library's default styles as much as possible in order to lower implementation and maintenance cost of the tutorial and also make it reflect the library defaults as good as we can.

Hagarshilo updated the task description. (Show Details)Jul 22 2018, 11:14 AM
Hagarshilo updated the task description. (Show Details)Jul 25 2018, 8:22 AM
Hagarshilo updated the task description. (Show Details)Jul 25 2018, 12:02 PM
Hagarshilo updated the task description. (Show Details)Jul 30 2018, 1:39 PM
Hagarshilo updated the task description. (Show Details)

I do understand the gain through the creative approach of current tutorial styling and think that it's done well if seen only on its own.
Nevertheless we should make a few necessary changes in order to embed this more into a framing of OOUI branding (let's not doubt its existence for a moment) and best UX practices.
It's also clear that when you currently approach OOUI demos and compare to the docs, it's hard to think of a clear design framing. But we're currently working on T185396 which brings a change in looks of JS docs.

To the main points for now (trying to keep it low-volume as the work accomplished by @Hagarshilo so far is already very good IMHO):

    1. I'd pledge against using custom web font, it's a performance issue, we're loading from Google servers for little reason. Better use device-independent font-stack like on Design Style Guide T188799
  1. We're sometimes, but not consistently using colors from our Style Guide palette
  2. I'd orientate myself on the inline code styles on mediawiki.org code styling, not using blue as foreground color
  3. We should limit block level elements to a more user-friendly line-length with 45-75 chars per line

I really like the font-size in current patch set.

Mooeypoo added a subscriber: matmarex.EditedAug 1 2018, 3:48 PM

There's an issue with the indicator in the dropdown widget that I want to get some insight on, I'm either missing something, or we might have an OOUI issue (?)

OO.ui.DropdownWidget already has indicator: 'down' by default:

OO.ui.DropdownWidget = function OoUiDropdownWidget( config ) {
	// Configuration initialization
	config = $.extend( { indicator: 'down' }, config );
...

But the indicator isn't showing in the tutorials. I thought it might be that the icon isn't loaded, so I searched for any mention of indicator or 'down' in the less and css files, and all I found was src/themes/apex/widgets.less that redefines 'visibility:visible' and a margin.

I was searching for some css to add to the index.html page in Tutorials but I can only find icon-xxx stuff and the svg/png files in the dist/themes/wikimediaui/images/indicators

Is there a CSS file to add to the tutorials that we're missing that loads the indicators? It seems like that's what we are missing, and I can't find which css file to attach. @Volker_E @matmarex any ideas?

Just submitted a new patch with some design changes. Tried to follow the style guide better. Let me know your thoughts.
Dropdown indicator still missing, as Moriel just said.
I don't get 404 when selecting the index page. I will need more details about this bug, if it still occurs.

Hagarshilo updated the task description. (Show Details)Aug 8 2018, 12:45 PM
Volker_E moved this task from Doing to Reviewing on the OOUI board.Aug 11 2018, 7:00 PM
Hagarshilo updated the task description. (Show Details)Aug 13 2018, 12:28 PM

Change 444389 merged by jenkins-bot:
[oojs/ui@master] Create 2 OOUI tutorials and an index page

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

Volker_E moved this task from Reviewing to OOUI-0.28.0 on the OOUI board.Aug 13 2018, 9:17 PM
Volker_E edited projects, added OOUI (OOUI-0.28.0); removed OOUI.

There's an issue with the indicator in the dropdown widget that I want to get some insight on, I'm either missing something, or we might have an OOUI issue (?)
(…)
But the indicator isn't showing in the tutorials. I thought it might be that the icon isn't loaded, so I searched for any mention of indicator or 'down' in the less and css files, and all I found was src/themes/apex/widgets.less that redefines 'visibility:visible' and a margin.

(…)
Dropdown indicator still missing, as Moriel just said.
I don't get 404 when selecting the index page. I will need more details about this bug, if it still occurs.

I'm sorry about missing these comment, I get a lot of bugmail and sometimes something slips through the cracks :( Feel free to ping me again or email directly if I'm not responding.

In this case, you were not loading the file oojs-ui-images-wikimediaui.css. Looks like you solved this problem in PS50 by loading oojs-ui-core-wikimediaui.css (which contains -core, -widgets, -toolbars, -windows, -images merged together): https://gerrit.wikimedia.org/r/c/oojs/ui/+/444389/49..50/demos/tutorials/index.html. Note that you can now stop loading oojs-ui-core-wikimediaui.css from the tutorial pages (these styles are already included in the other file).

Change 452701 had a related patch set uploaded (by Mooeypoo; owner: Mooeypoo):
[oojs/ui@master] Tutorials: Fix CSS links

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

Change 452701 merged by jenkins-bot:
[oojs/ui@master] Tutorials: Fix CSS links

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

Change 452872 had a related patch set uploaded (by VolkerE; owner: VolkerE):
[mediawiki/core@master] Update OOUI to v0.28.0

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

Volker_E triaged this task as High priority.Aug 15 2018, 12:32 AM
Volker_E removed a project: Patch-For-Review.
Volker_E awarded a token.
Volker_E removed a subscriber: gerritbot.

Change 452872 merged by jenkins-bot:
[mediawiki/core@master] Update OOUI to v0.28.0

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

Jdforrester-WMF added a subscriber: Jdforrester-WMF.

The OOUI release landed in MediaWiki 1.32.0-wmf.18.

Brilliant!

@Hagarshilo wonderful work.

We all hope you stick around after the Google Summer of Code internship, as a valued member of the development community. Well done, and thank you for a super valuable contribution to the OOUI library.

Thank you! Almost there...

I spotted a couple of problems with the tutorials toolbar (and I've explored them a bit with Moriel and Roan).

  1. The Docs link is broken. It comes from
demos/tutorials/widgets/toolbar.js

I think it can be fixed by replacing "oojs-ui/master/js" with "js/" on line 29.

  1. Toolbar menu icons load locally, but not on doc.wikimedia.org. The submenu links are loaded from
dist/oojs-ui-wikimediaui-icons-content.css

and can be seen both locally and in production. We think the missing links come from

dist/oojs-ui-wikimediaui-icons-editing-citation.css

so a link to this file should be added to all 3 HTML files:

tutorials/index.html
tutorials/collection/basics1/contents.html
tutorials/collection/basics2/contents.html

However, we're not sure why the missing links do load locally, while a link to this CSS file is missing.

@Hagarshilo I'd recommend opening one or several follow-up tasks for above to keep task scope smaller. You've done a sufficiently good job for this task to be set to “resolved”! As with most software projects it's a journey of continuous improvements.

Volker_E closed this task as Resolved.Aug 16 2018, 9:34 PM

💯