Extension:GuidedTour/Refactoring notes 2014-02-11
This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on the information here being up-to-date. |
Based on a meeting with Matthew Flaschen and Sam Smith
Prior discussion
editGeneral
editUse cases
editThese are just for discussion and consideration. We may not want to add code support for all of this.
Cards for next steps
edit- Refactoring (tracking) (includes below)
- Domain-specific language
- Review existing tours
- What requires complicated workarounds (make sure it's required, not just that they're doing it that way)
- What works well?
- Refactor user state
- User state is split across modules
- ext.guidedTour.lib.internal and ext.guidedTour.lib both deal with user state in some way. If the user state is going to become more complicated then it should be moved into its own module (or two -- one for parsing/encoding, one for storing/retreiving).
Future
edit- Integrate more closely with mediawiki UI library for consistency
- May clash with keeping it as a third-party library
- Define the interface for all UI interactions (showDialog etc.)
- Without the third-party library idea, we might not need these abstractions.
- Make it easy to write tours
- Back button?
- Tours for JavaScript interfaces like VisualEditor and UploadWizard
- Without having to put hook list for this into the main library
- How does a third-party library/extension signal to the tour that new content is available?
- Will probably introduce new API, eventually may deprecate and remove old one
Current modules and their responsibilities
editmediawiki.libs.guiders
edit- Originally, third party library
- Low-level guider functionality
- Rendering guiders/steps, arrows
- Auto-flipping
- Pre-load/pre-renders next guider in some cases
- Some functionality we've never used (e.g. advance_if_form_content, showIfHashed)
ext.guidedTour.lib
edit- Our main public API.
- User state persistence
- Logging
- Calls MW API for rendering wikitext or using the content of a page as a description
- Converts high-level actions (like 'next' or 'wikilink' to buttons understood by mediawiki.libs.guiders)
- Determines whether to flip for RTL support
- i18n
- Listens to MW-specific hooks
- Auto-loads tour based on initial state (query string and cookie).
- shouldSkip helpers for moving from step to step
- Calls internal library
ext.guidedTour
edit- Auto-launcher.
- Tours depend on that module, so if the tour is added to the page, it launches itself.
ext.guidedTour.lib.internal
edit- Internal library that can be unit tested but is not public
- Loads tour(s) from on-wiki or extension module
- Parses user state