User:MSchottlender-WMF/ooui-doc-draft

From MediaWiki.org
Jump to: navigation, search

This is a concept write-up for starting OOjs UI documentation.

The rationale behind this is to organize the documentation in a conceptually logical way, so we can make sure developers know where to start, and we can collaboratively write and maintain the documentation.

The idea is that once a developer understands the rationale of why things are built a certain way, it is much easier to get into multiple widgets and implementation details. On top of that, we build separate documentation for quick-info if a developer 'just' wants to create a one-off widget without getting all in to the logic and operation of OOjs UI. In between the documentation we should include hands-on tutorials and walk-throughs.

Please feel free to add, adjust, or link to a page if you've written it.

Section Concept/Description Existing pages for reference / replacement
Introduction
  • What is OOjs-UI
    • Rationale
    • Why you should use it in your extension
  • OOjs and OOjs-UI
  • How to work with OOUI / Good practices
    • View models, widgets and events
    • Creating a UI from multiple widgets
    • Using existing OOjs-UI icons
About the library

OOjs UI/OOjs primer

Getting started
  • Dependencies
    • Javascript modules
    • PHP composer dependencies
  • Using OOjs-UI in MediaWiki
  • Choosing from existing widgets
  • Tutorial: Building a basic UI from existing ooui widgets
Creating interfaces programmatically

OOjs UI/PHP examples

OOjs UI/Using OOjs UI in MediaWiki

Working with widgets
  • Labels
  • Buttons
  • Inputs
  • Checkboxes
  • Select inputs
  • Layouts
  • Dialogs
  • Icons
OOjs UI/Elements

OOjs UI/Elements/Flagged

OOjs UI/Elements/Groups

OOjs UI/Elements/Lookup

OOjs UI/Index and Cards

OOjs UI/Layouts

OOjs UI/Layouts/Booklets and Pages

OOjs UI/Layouts/Fields and Fieldsets

OOjs UI/Layouts/Forms

OOjs UI/Layouts/Grids (deprecated)

OOjs UI/Layouts/Menu Layout

OOjs UI/Layouts/Stacks and Panels

OOjs UI/Widgets

OOjs UI/Widgets/Buttons and Switches

OOjs UI/Widgets/Icons, Indicators, and Labels

OOjs UI/Widgets/Inputs

OOjs UI/Widgets/Popups

OOjs UI/Widgets/Progress bars

OOjs UI/Widgets/Selects and Options

OOjs UI/Windows

OOjs UI/Windows/Dialogs

OOjs UI/Windows/Message Dialogs

OOjs UI/Windows/Process Dialogs

OOjs UI/Windows/Simple messages

OOjs UI/Windows/Window managers

OOjs UI/Toolbars

Extending widgets
  • General method / rationale / best practices
  • The difference between a mixin and a widget (PopupElement vs PopupWidget, etc, and when to use each)
  • Tutorial: Creating a basic TODO app interface with extended input widgets (inspired from part 2 of the tutorial here)
  • Advanced Tutorial: Creating a TODO app interface with a view model, event listener, and extended ooui widgets.
Advanced concepts Generalizing a widget for upstream into ooui