Extension:GuidedTour/API brainstorming

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

Current

( 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

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

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) );