Extension:GuidedTour/Write an on-wiki tour

From MediaWiki.org
Jump to: navigation, search

This page explains how to write an on-wiki tour. These types of tours are stored directly on a wiki, in the MediaWiki namespace. To edit this namespace, you generally must be an administrator. However, anyone can propose a tour be added.

A series of steps[edit | edit source]

First you have to consider when and how your tour should start

The tour itself is a sequence of dialog windows that appear on the page, called steps. (It is possible to have a single-step tour that operates as a fancy tooltip, and to jump into the tour at different points.)

Each step has an implicit next step. You define the tour in a JavaScript function, passing it the steps as a JavaScript array of objects; so at the code level the next step is explicitly the next item in the steps array.

The extension keeps track of the current step in each tour in a browser cookie, so that a tour can continue across multiple web pages.

Implementation[edit | edit source]

  1. Consult the design recommendations.
  2. Choose a tour name. This and shouldLog (if applicable) should be set on the main object of the tour (see example tours below).
    name: 'tourname',
    
  3. If you want to log certain events with Schema:GuidedTour, add:
    shouldLog: true,
    
  4. For each step in your tour:
    1. Choose title and description text.
    2. Then, choose whether the step will have an attachment or a central overlay:
      • Attachment positions a step near a page element such as the Edit tab, a link, or the save button. You identify the page element using a selector. Any jQuery selector can be used. In general, this includes all CSS selectors. This example positions near the Edit tab using an id selector:
        attachTo: '#ca-edit',
        
        For attachments, you must choose an attachment position. The choices are topLeft, top, topRight, rightTop, right, rightBottom, bottomRight, bottom, bottomLeft, leftBottom, left, leftTop. You can experiment with these values, and may want to test in a skin beside your primary one (using the useskin parameter). For on-wiki tours, you should test in the wiki's site direction (which does not vary by user or according to uselang). If you're not sure what this is, you can check in a JavaScript console with:
        $( document.body ).is( '.sitedir-ltr' ) ? 'ltr' : 'rtl'
        Extension-defined tours should always be written left-to-right. In either case (on-wiki or extension tours), if the user is using another direction (for example, they are browsing English Wikipedia but have their interface language set to Hebrew in preferences), steps will automatically flip horizontally.
      • Overlay simply shows the step in the center of the screen. It allows you to explain something without attaching to an element.
        overlay: true,
        
    3. Choose the button actions. If you want the user to click something (such as the edit tab), you can provide no explicit buttons (an Okay button that dismisses the step will still show). Otherwise, you will want to specify one or more. You can specify arbitrary button actions. However, there are helpers included for common behaviors of the Okay button:
      • next - Will go the next step, unless the user checked the "End tour" checkbox.
        { action: 'next' }
        
      • end - Will end the tour
        { action: 'end' }
        
    4. By default, the step will close when they click outside it. In some cases, such as on the edit page, you may want to disable this by including:
      closeOnClickOutside: false,
      
    5. Decide if you want automatic skip behavior. In some cases, you will want to automatically skip a step based on the current state. For example, if you have a step asking the user to click Edit, you will want to skip if they're already on the edit page:
       shouldSkip: function() { return gt.hasQuery( { action: 'edit' } ); }
      

Note that if a step doesn't have a 'next' button, you must implement a shouldSkip() function for the current step that returns true, otherwise the tour will "stall" on it — every time the user reloads the page or visits any page that loads your tour, the current step will reappear until the user exits the tour.

Tips[edit | edit source]

  • Use debug mode while developing your tours.
  • Inspect the tour cookie (named wgCookiePrefix-mw-tour) to see what step your tour is on.
  • Even when writing an on-wiki tour, use a JavaScript checker such as jshint to check for errors in your tour definition.
  • When stepping through your code in a browser debugger, the resume() function in guiders.js is one of the most useful functions in which to set a breakpoint.


Test tour code walkthrough[edit | edit source]

This is a walkthrough of the test tour built into Extension:GuidedTour, modified to be an on-wiki tour. The test tour does not use any multi-page functionality (see #Gettingstarted tour code walkthrough). It demonstrates multiple approaches to the description, either inlined completely, inlined but parsed from wikitext (gt.parseDescription), and parsed from a dedicated page (gt.getPageAsDescription). For an actual tour, you can use one option for all steps (simplest), or use different options for different steps.

/*
 * Guided Tour to test guided tour features.
 */
 
// Copy the next two lines into your tour.
( function ( window, document, $, mw, gt ) {
 
// Declare a variable for use later
var pageName = 'Help:Guided tours/guider';
 
gt.defineTour( {
	/*
	 * This is the name of the tour.  It must be lowercase, without any hyphen (-) or
	 * period (.) characters.
	 *
	 * The page where you save an on-wiki tour must be named
	 * MediaWiki:Guidedtour-tour-{name}.js , in this example MediaWiki:Guidedtour-tour-mytest.js
	 */
	name: 'mytest',
 
	/*
	 * Information defining each tour step, in order.
	 */
	steps: [ {
		/*
		 * Show overlay at start of tour
		 */
 
                // Note that for on-wiki tours, we use title and description with the actual text.
                // The title appears in the title bar of the guider.
		title: 'Testing',
 
                // The description appears in the body
		description: 'This is a test of the description. Lorem ipsum dolor sit!',
 
                // This specifies that the guider appears in the center of the screen
		overlay: true,
                // This means there is just the okay button, which will go to
                // the next step unless the user ends the tour.
		buttons: [ {
			action: 'next'
		} ]
	}, {
		/*
		 * Callout of left menu
		 */
		title: 'Test callouts',
		description: 'This is the community portal page.',
 
                // This positions the guider next to a page element, in this
                // case the portal link (which is "Community portal" on English
                // Wikipedia, but varies by site).
                // The string is a jQuery selector.  "#n-portal" means the HTML
                // element with this id attribute, and "a" means an a, or link,
                // element inside that.
		attachTo: '#n-portal a',
 
                // This means the guider shows to the right of the Community Portal link
		position: 'right',
 
		buttons: [ {
			action: 'next'
		} ]
	}, {
		/*
		 * Test out mediawiki parsing
		 */
		title: 'Test MediaWiki parse',
		description: 'A guider in your on-wiki tour can contain wikitext using onShow and parseDescription. Use it to create a wikilink to the [[{{MediaWiki:Guidedtour-help-url}}|Guided tours documentation]]. Or an external link [https://github.com/tychay/mwgadget.GuidedTour to GitHub], for instance.',
 
                // This attaches to the search box, by ID.
		attachTo: '#searchInput',
		position: 'bottomRight',
 
                // This means the description will be parsed as wikitext before being shown.
                onShow: gt.parseDescription,
		buttons: [ {
			action: 'next'
		} ]
	}, {
		/*
		 * Test out mediawiki description pages
		 */
		title: 'Test MediaWiki description pages',
 
                // In this case, we are putting a page name here, rather than text directly.
		description: pageName,
 
		overlay: true,
 
                // This means the wikitext will be loaded from the page name in the description field.
		onShow: gt.getPageAsDescription,
 
		buttons: [ {
                        // This makes a button which acts like a wikilink to 'Help:Guided tours/guider'
			name: 'Go to description page',
			onclick: function() {
				window.location = mw.util.wikiGetlink(pageName);
				return false;
			}
		}, {
                        // This makes the okay button on this step end the tour.
			action: 'end'
		} ]
	} ]
} );
 
// The following should be the last line of your tour.
} (window, document, jQuery, mediaWiki, mediaWiki.guidedTour ) );

Gettingstarted tour code walkthrough[edit | edit source]

This is a walkthrough of a simplified version of the gettingstarted tour, if it were written as an on-wiki tour. It covers more advanced features not described above:

// Guided Tour to help users start editing
 
( function ( $, mw, gt ) {
gt.defineTour( {
	name: 'gettingstarted',
	steps: [ {
		title: 'Ready to help?',
		description: 'This page needs basic copyediting – improving the grammar, style, tone, or spelling – to make it clear and easy to read. This tour will show you the steps to take.',
		overlay: true,
		buttons: [ {
			action: 'next'
		} ],
 
                // shouldSkip is a general tool to skip a step based on their progress towards some goal.  This is used to ensure this step will not be shown once they have started editing.
                // shouldSkip always returns true to skip, or false otherwise.
		shouldSkip: function() {
			return gt.hasQuery( { action: 'edit' } );
		}
	},  {
		title: 'Click \'Edit\'',
		description: 'This will let you make changes to any part of the page, when you\'re ready.',
		attachTo: '#ca-edit',
		position: 'bottom',
                // Same as above.  We plan to make this less repetitive in the future.
		shouldSkip: function() {
			return gt.hasQuery( { action: 'edit' } );
		}
	}, {
		title: 'Preview (optional)',
		description: 'Clicking \'Preview\' allows you to check what the page will look like with your changes. Just don\'t forget to save.',
		attachTo: '#wpPreview',
		position: 'top',
                // Normally, the guider will automatically close when the user clicks outside the boundaries.  This can be turned off on a case-by-case basis, as it is here.
                // In this case, it is turned off since the user is likely to click the edit box before seeing the guider at the bottom of the screen.
		closeOnClickOutside: false,
                // This is the opposite of the above.  We skip if they are *not* editing.
		shouldSkip: function() {
			return !gt.hasQuery( { action: 'edit' } );
		}
	}, {
		title: 'You\'re almost finished!',
		description: 'Click \'Save\' and your changes will be visible.',
		attachTo: '#wpSave',
		position: 'top',
 
                // Normally, guiders will close when the user clicks outside them.  But you may want to disable this in some cases.
                // For example, since people normally click on the edit box, we are disabling them on steps that are on the edit screen.
		closeOnClickOutside: false,
 
                // We skip if they are not doing a preview, show changes, etc.
		shouldSkip: function() {
			return !gt.hasQuery( { action: 'submit' } );
		}
	}, {
		title: 'Looking for more to do?',
		description: '[[Special:GettingStarted|Getting Started]] is updated every hour with new pages.',
                onShow: gt.parseDescription,
		overlay: true,
 
                // We don't want to show this step if they didn't complete an edit.
                // Note that this requires they actually change something, not just click save.
		shouldSkip: function() {
			return !gt.isPostEdit();
		},
		buttons: [ {
			action: 'end'
		} ]
	} ]
} );
 
} (jQuery, mediaWiki, mediaWiki.guidedTour ) );