Page MenuHomePhabricator

Make documentation on toolbars, tool groups, and tools
Closed, ResolvedPublic

Description

Currently documentation is scarce on the topic of toolbars and tools. They aren't mentioned on the living style guide and code level documentation is all that there is (and even that isn't very detailed). I would be great if an article was created on the living style guide and a bit more documentation was added for doxygen.

Event Timeline

Negative24 raised the priority of this task from to Lowest.
Negative24 updated the task description. (Show Details)
Negative24 added a project: OOUI.
Negative24 added a subscriber: Negative24.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMar 1 2015, 3:04 PM

Note that there are some vague plans for a pretty major reworking of how toolbars work: T74159: OOUI: Toolbar groups should support sub-groups as items (hierarchical, nested menus). Right now you can't have nested menus at all (there's only a rigid structure: toolbar has tool groups, tool groups have tools), which turned out to be too limiting in practice.

I'll be taking apart the demo and making a bit of documentation from that. It seems to be the simplest working copy of toolbars at the moment (even though it still is complicated for new users, such as I).

Spage raised the priority of this task from Lowest to Normal.Apr 23 2015, 8:42 PM
Spage added a project: Documentation.
Spage set Security to None.
Spage added a subscriber: bmansurov.
Spage assigned this task to KMenger.Apr 23 2015, 8:55 PM
Spage added a subscriber: Spage.

@bmansurov also had difficulty figuring out OOjs UI toolbars.

So it sounds like overview or tutorial is needed as well. Kirsten are you going to (eventually) document toolbars, tool groups, and tools in https://www.mediawiki.org/wiki/OOjs_UI ? If so I suggest add a placeholder page with the links above and a hatnote Subject to change per T74159.

I added the big example recently after being prodded by @Negative24 :) demos/pages/toolbars.js is pretty awful and you probably don't want to look there if you value your sanity.

(I also wouldn't count on the promised rewrite happening soon, sadly, now that I'm doing primarily Multimedia rather than VisualEditor and Trevor is doing management. :( )

Negative24 added a comment.EditedApr 24 2015, 1:03 PM

...demos/pages/toolbars.js is pretty awful and you probably don't want to look there if you value your sanity.

I agree. That's how I got as far as knowing toolbars and toolgroups. It doesn't explain tools which is why I needed your example. I believe I have a full rewrite of the demo without the loop initialization and object definitions somewhere. I don't know if that would be useful for someone.

Yes, I will be documenting toolbars. I will create a placeholder page as you recommend, S.

Jdforrester-WMF moved this task from Backlog to Reviewing on the OOUI board.Aug 26 2015, 1:38 AM