Extension:GuidedTour/Refactoring notes 2014-02-11

Based on a meeting with Matthew Flaschen and Sam Smith

Prior discussion edit

General edit

Use cases edit

These are just for discussion and consideration. We may not want to add code support for all of this.

Cards for next steps edit

  • 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 edit

mediawiki.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