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

The experimental ArticleCreationHelp extension shows guiders over red links. The guiders' descriptions contain the title of the article pointed to by the red link, so they change for each red link they appear over. Also, they sometimes contain a link to a page for creating that article.

Some conisderations:

Not all properties available on tourSpecs should be modifiable.

GuidedTour should hear back about any changes made to a tour, and should take care of things like caching.

While dynamic modification of tours seems to go against the grain of the declarative approach taken here, it would allow reuse of code and styles for cases where some tour elements are best set dynamically.

Option 1: TourController

// An object for dynamically controlling a tour
var myTourController = mw.guidedTour.getTourController('mytour');

// Resets tour to pristine state, removing any DOM elements created on
// previous launches.
myTourController.reset();

// Sets the HTML for a guider's description.
// Setters could be provided for other elements that may be changed dynamically.
myTourController.description(0, descriptionHtml);

// Same as mw.guidedTour.launchTour(tourName)
myTourController.launch();

// We might also allow changing the contents of a guider while it's showing,
// perhaps with an animation.
// (See the fifth comment here: https://gerrit.wikimedia.org/r/#/c/79555/)
// For example, the following could be the click-handler for a button on a guider:
var clickHandler = function (event) {

    // The last argument could be an optional "animate", for requesting
    // an animated transition if the guider is showing.  
    myTourController.description(0, newDescriptionHtml, true);
}

Here's a draft implementation.

Some issues:

• Maybe instead of myTourController.description(int, string, boolean) it should be myTourController.modifyStep(int, object, boolean), with object holding the properties to change.
• With regard to changing a guider while it's displayed: it's nice to be able to animate, but the new version of the guider should probably be a distinct step, rather than a new version of an existing step.

Option 1a: TourController with properties, and animateFromPrev in step definition

Here's a variation on the previous option:

// An object for dynamically controlling a tour
var myTourController = mw.guidedTour.getTourController('mytour');

// Resets tour to pristine state, removing any DOM elements created on
// previous launches.
myTourController.reset();

// You can now modify some guider properties.
var properties = {
    description: 'new guider description'
};
myTourController.modifyStep(0, properties);

// Same as mw.guidedTour.launchTour(tourName)
myTourController.launch();

// End a tour programmatically
myTourController.cancel();

It seems there may be times when you'll want to change a guider while it's displayed. ("To click the save button, scroll down," "Keep scrolling," "Now click here."gerrit:79555) That is the possible use case for modifying steps while they're displayed.

Another case is: when you have consecutive guiders/steps that point to the same thing, and you want to animate the transition from one guider to the next. For that situation, steps could have an animateFromPrev property.

Here are draft implementations for this TourController API and the animateFromPrev property.

Option 2: Tour start-up callbacks

Suggested here: "Allow tours to run setup code every time the tour is re-started (passing some setup callback to defineTour)?"

Option 3: Methods directly on GT

Similar to Option 1. Something like this (?):

mw.guidedTour.reset('mytour');
mw.guidedTour.description('mytour', 0, htmlDescription);
mw.guidedTour.launchTour('mytour');

Option 4: Allow functions instead of strings

Suggested here. For example, the library could call a function for creating description html each time a tour is launched, and replace DOM elements if the value returned has changed since the previous launch.

See also

Discussions on uncacheable and getTourSpec.