AndyRussG has uploaded a new change for review. https://gerrit.wikimedia.org/r/82208
Change subject: TourController w/ modifyStep( step, properties ) ...................................................................... TourController w/ modifyStep( step, properties ) Another implementation of a possible solution for modifying tours dynamically, as per Option 1a described here: https://www.mediawiki.org/wiki/Extension:GuidedTour/ Refactoring_brainstorming/Use_case:_Article_Creation_Help For modifying steps, provides a modifyStep( step, properties ) method where properties is an object with the properties to modify. Change-Id: I00ec47c5e758eeb7dbcffc7fd0a25a0d90a85e33 --- M modules/ext.guidedTour.lib.js M modules/mediawiki.libs.guiders/mediawiki.libs.guiders.js 2 files changed, 155 insertions(+), 1 deletion(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/GuidedTour refs/changes/08/82208/2 diff --git a/modules/ext.guidedTour.lib.js b/modules/ext.guidedTour.lib.js index 9d8e142..b4ac1ba 100644 --- a/modules/ext.guidedTour.lib.js +++ b/modules/ext.guidedTour.lib.js @@ -36,7 +36,8 @@ userId = mw.config.get( 'wgUserId' ), // Key is tour name, value is tour spec (specification). A tour spec is // exactly what is passed in to defineTour. - definedTours = {}; + definedTours = {}, + originalModifiableValues = {}; /** * Setup default values for logging, unless they're logged out. This doesn't mean @@ -793,6 +794,28 @@ } } + function saveModifiableValues( tourSpec ) { + var steps, i; + steps = []; + + for ( i = 0; i < tourSpec.steps.length; i++ ) { + steps[ i ] = { + description: tourSpec.steps[ i ].description + }; + } + + originalModifiableValues[ tourSpec.name ] = { steps: steps }; + } + + function restoreModifiableValues( tourSpec ) { + var i; + + for ( i = 0; i < tourSpec.steps.length; i++ ) { + tourSpec.steps[i].description = + originalModifiableValues[ tourSpec.name ].steps[ i ].description; + } + } + /** * Internal initialization of guiders and guidedtour, called once after singleton * is built. @@ -1463,6 +1486,8 @@ throw new gt.TourDefinitionError( '\'tourSpec.steps\' must be an array, the list of steps.' ); } + saveModifiableValues( tourSpec ); + stepCount = steps.length; for ( stepInd = 1; stepInd <= stepCount; stepInd++ ) { steps[stepInd - 1] = augmentGuider( defaults, steps[stepInd - 1] ); @@ -1484,6 +1509,84 @@ return true; }, + + /** + * Get a controller for programmatic launch and manipulation of a tour. + * + * Returns null if there isn't a tour called tourName. + * + * @param {String} tourName + * @returns {gt.TourController|null} + */ + getTourController: function( tourName ) { + return definedTours[ tourName ] ? new gt.TourController ( tourName ) : null; + }, + + /** + * An object for launching and manipulating a tour. + * + * @param {String} tourName the name of the tour to be launched/manipulated + */ + TourController: function ( tourName ) { + this.tourName = tourName; + + // Defining methods here to keep stuff together. + + if ( typeof gt.TourController.prototype.reset === 'undefined' ) { + + /** + * Returns the tour to original, unmodified state + */ + gt.TourController.prototype.reset = function () { + var tourSpec, i, tourId; + tourSpec = definedTours[ this.tourName ]; + + // tell guiders to reset/remove everything for this tour's steps, + // and reset descriptions on spec + for ( i = 0; i < tourSpec.steps.length; i++ ) { + tourId = gt.makeTourId( { name: this.tourName, step: i + 1 } ); + guiders.removeGuider( tourId ); + } + + restoreModifiableValues( tourSpec ); + }; + } + + if ( typeof gt.TourController.prototype.modifyStep === 'undefined' ) { + + /** + * Modify the properties of a given step. + * + * Currently supports modifying only the description. + * + * @param {Number} step the index of the step (starts at 0) + * @param {Object} properties the properties to modify + * + */ + gt.TourController.prototype.modifyStep = function ( step, properties ) { + var tourId; + + // modify the guider and cache in mediawiki.libs.guiders + tourId = gt.makeTourId( { name: this.tourName, step: step + 1 } ); + guiders.modifyGuider( tourId, properties ); + + // change spec + definedTours[ this.tourName ].steps[ step ].description = + properties.description; + }; + } + + if ( typeof gt.TourController.prototype.launch === 'undefined' ) { + + /** + * Launches the tour; same as mw.guidedTour.launch( tourName ). + */ + gt.TourController.prototype.launch = function () { + gt.launchTour( this.tourName ); + }; + } + }, + // Below are exposed for unit testing only, and should be considered // private /** diff --git a/modules/mediawiki.libs.guiders/mediawiki.libs.guiders.js b/modules/mediawiki.libs.guiders/mediawiki.libs.guiders.js index 369f1b2..574a401 100644 --- a/modules/mediawiki.libs.guiders/mediawiki.libs.guiders.js +++ b/modules/mediawiki.libs.guiders/mediawiki.libs.guiders.js @@ -846,6 +846,57 @@ }; /** + * Removes a guider, its cached settings and its DOM element + * + * @param guiderId {string} + */ + guiders.removeGuider = function ( guiderId ) { + // TODO for now, we're not worrying about whether a guider is visible, etc. + var guider = guiders._guiders[ guiderId ]; + + if (guider) { + guider.elem.remove(); + delete guiders._guiders[ guiderId ]; + } + + delete guiders._guiderInits[ guiderId ]; + }; + + /** + * Modifies a guider in the DOM, if it's there, as well as + * its cached settings, if they're there. + * + * Currently supports modifying only the description. + * + * @param guiderId {string} + * @param options {object} the properties to modify + * + */ + guiders.modifyGuider = function ( guiderId, options ) { + var guiderInit, guider; + + // modify cached info about guider + guiderInit = guiders._guiderInits[ guiderId ]; + if ( guiderInit ) { + guiderInit.description = options.description; + } + + // modify the guider itself + guider = guiders._guiders[ guiderId ]; + if ( guider ) { + + guider.description = options.description; + + if ( guider.elem ) { + guider.elem.find( '.guider_description' ) + .html( options.description ); + + guiders._attach( guider ); + } + } + }; + + /** * Hides all guiders * * @param {boolean|undefined} omitHidingOverlay falsy to hide overlay, -- To view, visit https://gerrit.wikimedia.org/r/82208 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I00ec47c5e758eeb7dbcffc7fd0a25a0d90a85e33 Gerrit-PatchSet: 2 Gerrit-Project: mediawiki/extensions/GuidedTour Gerrit-Branch: master Gerrit-Owner: AndyRussG <[email protected]> Gerrit-Reviewer: jenkins-bot _______________________________________________ MediaWiki-commits mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
