Extension:GuidedTour/Refactoring notes 2014-03-07

From mediawiki.org

GuidedTour/guiders[edit]

Cards to create[edit]

API[edit]

next[edit]

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

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

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

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?