Extension:GuidedTour/Refactoring notes 2014-03-07

Cards to create

• Deprecate all of the advance (e.g. advance_if_test) methods and maybe some others (e.g showIfHashed)
• Merge guiders into GuidedTour more thoroughly
• Stepping from one tour into another
• Optional: Publish the documentation early and see if a few tour writers understand it (checklist item at Implement non-linear transitions in GuidedTour)
• Back button support

API

next

• step.next( 'stepName' ) - When they click next, just go to that step
• step.next( someStep ) - Same, except with a Step object. Name can be statically checked (it's a valid variable name).

step.next( function () {

        ...

    return step string or step;

} );

• Assumes we'll keep using action: 'next', which I think makes sense since we allow control over button placement, which we couldn't do if we only had the method.

back

• Could work similarly: action: 'back', with .back(). Let's leave out since the change will be big enough and there has never been back support. Can easily add later.

skip

• non-linear version of "shouldSkip"

// type - jQuery or mw.hook for now, maybe document.ready if we don't use the 'content' hook for that.
// detail - hook name or selector
step.skip( function ( type, detail) {
    return step string or step;
    // returning nothing, or no registered skip function, means it does not skip
  } );

• Called for global events, like page load/document.ready, post-edit, and anything you specifically listen for at the tour or step level.
  • Same API to listen at tour or step level.
  • The reason to listen at the tour level, is:
    • Transition to another tour (e.g. VE tour transitions to wikitext)
    • Or you click reference button anywhere, goes into that step.
• Alternative: Separate by jQuery vs. hook (skipByEvent/skipByHook)? Think we're going .step
• Trying to think how to send people from a step to another tour. Maybe some sort of StepReference wrapping tour IDs?
• Keep using tour IDs? But they're kind of a little ugly

Builder

Should be able to build tour with core objects (Tour/Step), but builder syntax is shorthand on top of that.

( new TourBuilder() ).tour( ) 
  .step()
  .title()
  .description()
  .skip( function ( type, detail ) {
  } );

– Maybe?