Extension:GuidedTour/Refactoring notes 2014-02-11

Based on a meeting with Matthew Flaschen and Sam Smith

Prior discussion

General

• Extension:GuidedTour/Refactoring brainstorming
• Extension:GuidedTour/API brainstorming

Use cases

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

• Extension:GuidedTour/Refactoring brainstorming/Use case: Article Creation Help
• Extension:GuidedTour/Microsurveys

Cards for next steps

• 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

• 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

mediawiki.libs.guiders

• 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

• 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

• Auto-launcher.
• Tours depend on that module, so if the tour is added to the page, it launches itself.

ext.guidedTour.lib.internal

• Internal library that can be unit tested but is not public
• Loads tour(s) from on-wiki or extension module
• Parses user state