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.
Description
Status | Subtype | Assigned | Task | ||
---|---|---|---|---|---|
Duplicate | None | T97264 Make it lovely to develop with OOjs UI | |||
Open | None | T101995 Improvements to the toolbar system | |||
Resolved | • KMenger | T91195 Make documentation on toolbars, tool groups, and tools |
Event Timeline
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).
@bmansurov also had difficulty figuring out OOjs UI toolbars.
- The generated doc https://doc.wikimedia.org/oojs-ui/master/#!/api/OO.ui.Toolbar has a big example that you can edit and preview.
- The toolbar demo source code is https://tools.wmflabs.org/oojs-ui/oojs-ui/demos/pages/toolbars.js , but uncommented.
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. :( )
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.