Extension:GuidedTour/API brainstorming

Feel free to brainstorm ideas for improving the API. See bugzilla:43530.

Current

edit
( function ( window, document, $, mw, guiders ) {

gt.defineTour( {
	name: 'test',
        steps: [ {
		titlemsg: 'guidedtour-tour-test-testing',
		descriptionmsg: 'guidedtour-tour-test-test-description',
		overlay: true,
		buttons: [ {
			action: 'next'
		} ]

	}, {
		titlemsg: 'guidedtour-tour-test-callouts',
		descriptionmsg: 'guidedtour-tour-test-portal-description',
		attachTo: '#n-portal a',
		position: '3',
		buttons: [ {
			action: 'next'
		} ]
	}, {
		titlemsg: 'guidedtour-tour-test-mediawiki-parse',
		// XXX (mattflaschen, 2012-01-02): See GuidedTourHooks.php
		description: mw.config.get('wgGuidedTourTestWikitextDescription'),

		// attachment
		attachTo: '#searchInput',
		position: 'bottomRight', //try descriptive position (5'oclock)

		buttons: [ {
			action: 'next'
		} ],
	}, {
	/*
	 * Test out mediawiki description pages
	 */
		titlemsg: 'guidedtour-tour-test-description-page',
		description: pageName,
		overlay: true,
		onShow: gt.getPageAsDescription,
		buttons: [ {
			namemsg: 'guidedtour-tour-test-go-description-page',
			onclick: function() {
				window.location = mw.util.wikiGetlink(pageName);
				return false;
			}
		}, {
			action: 'end'
		} ]
	},
	// ...
	]
} );

The supported actions (basically a higher-level way of specifying the behavior of the Okay button) are:

  • next - Go to next step
  • end - End tour

Other properties, such as isTooltipOnly, could be added to the main object passed in in the future.

Yes, JSON object

edit

The code in the above design is just a JSON structure, which is good as it eliminates the risk of executing arbitrary script

It can't be shoe-horned into the Schema namespace on meta-wiki, but a general JSON namespace is possible.

It's not currently JSON. Besides the wrapper call and no double-quoted keys, it is intended to keep allowing inline functions. This doesn't open any new vectors, since anyone who can currently create a tour can inject arbitrary code through Common.js or an extension. I'm not ruling out a JSON version in the future, though. Superm401 - Talk 04:01, 5 February 2013 (UTC)

Previous

edit

The current version looks like:

( function ( window, document, $, mw, guiders ) {

var gt = mw.guidedTour = mw.guidedTour || {};
gt.currentTour = 'test';

// For each step, the ones ending with msg are message keys
gt.initGuider({
	id: "gt-test-1",
	titlemsg: 'guidedtour-tour-test-testing',
	descriptionmsg: 'guidedtour-tour-test-test-description',

	// attachment
	overlay: true,

	next: "gt-test-2",
	buttons: [ {
		action: 'next'
	} ]
});

// ...
} (window, document, jQuery, mediaWiki, mediaWiki.libs.guiders) );