Wikidata:How to create Wikidata Tours/Javascript/zh
Create JavaScript page
All tours require a JavaScript file which contains a set of options for configuring the tour. Interface Admin rights are needed to deploy a JavaScript file for testing, so you will need to use this list of Interface Admins to find someone to help when you reach this step. The rest of the instructions on this page are intended for the Interface Admin who is drafted to help.
Note: If you have basic knowledge of JavaScript and CSS, you can create the JavaScript file yourself by following the steps on this page. You will still need help from an Interface Admin to actually deploy the file for testing in the next step, but this will save them some time as they can start from your proposed JavaScript file.
文件名和位置
At this stage in the process, the JavaScript file should be created in your own user space, e.g. User:YOUR_USERNAME/tours/wbmycooltour.js. However, to actually run the tour (either on test.wikidata.org or main wikidata.org) you will need to place the JavaScript file in the MediaWiki namespace using the following name convention: MediaWiki:Guidedtour-tour-tour name.js.
The [tour name] is also specified as one of the configuration options within the JavaScript file. This must match the filename for the tour to load. For example, use the filename MediaWiki:Guidedtour-tour-wbcoordinates.js for a tour with the name "wbcoordinates". You should only deploy the JavaScript file to this location on main wikidata.org once the tour has been fully tested and refined on test.wikidata.org, as explained in the rest of this guide.
To summarise, the file should be located in the following places as you work through the steps of the tour:
User namespace
(Current step) 
MediaWiki namespace test.wikidata.org
(Test step)
MediaWiki namespace www.wikidata.org
(Publish step)
Structure
Assuming you were creating a tour called "My Cool Tour", you would need the following:
- A wiki page to link to for the tour text, such as Wikidata:Tours/My_Cool_Tour
- A JavaScript file, which must be placed at MediaWiki:Guided-tour-wbMyCoolTour
- A new Wikidata item, only used by this tour
The JavaScript file for "My Cool Tour" would be completed with the details shown in the example template below. As this is just a fictional tour, the Wiki page and JavaScript file do not exist, but you can look at the References tour files for a real example:
- Name: wbreferences
- Wiki page: Wikidata:Tours/References
- JavaScript file: MediaWiki:Guidedtour-tour-wbreferences.js
- Wikidata item: Earth (Q85408509)
- Live tour URL: https://www.wikidata.org/w/index.php?title=Q85408509&tour=wbreferences
Expand the example below for template you can copy and paste as a starting point.
/*
* @see [[Wikidata:Tours/My_cool_tour]]
*
* @author Your_Username_Goes_Here
*/
( function( $, mw, gt, wb ) {
$.ajax( {
async: false,
url: mw.util.wikiScript() + '?title=MediaWiki:Guidedtour-lib.js&action=raw&ctype=text/javascript',
dataType: 'script'
} );
/**
* Name of your tour, always starts with 'wb' by convention
*/
var tourName = 'wbmycooltour',
/**
* Wikidata item that will be loaded for the tour
*/
tourEntityId = 'Q123...',
/**
* Initial data to add to the tour item, such as labels, descriptions and statements in standard wikibase syntax
*/
newData = { };
gt.init( tourName, tourEntityId, newData, {
/**
* The Wiki page from where the tour texts should be loaded.
*/
pageName: 'Wikidata:Tours/My_cool_tour',
/**
* The steps of the tour.
*/
steps: [ {
// 1. Welcome to My Cool Tour
}, {
// 2. Some background info
}, {
// 3. Add a statement
attachTo: '.wikibase-statementgrouplistview > .wikibase-addtoolbar-container .wikibase-toolbar-button-add',
actionBtn2: '.wikibase-statementgrouplistview > .wikibase-addtoolbar-container .wikibase-toolbar-button-add a',
}, {
// 4. Select a property
position: 'top',
attachTo: '.wb-edit',
}, {
// 5. Input a value
position: 'top',
attachTo: '.wb-new .valueview-value'
}, {
// 6. Add a reference
position: 'top',
attachTo: '.wb-new .wikibase-statementview-references .wikibase-toolbar-button-add',
actionBtn2: '.wb-new .wikibase-statementview-references .wikibase-toolbar-button-add a'
}, {
// 7. Select reference property
position: 'top',
attachTo: '.wb-reference-new .ui-suggester-input'
}, {
// 8. Input reference value
position: 'top',
attachTo: '.wb-reference-new .valueview-value',
}, {
// 9. Publish
position: 'top',
attachTo: '.wb-new .wikibase-toolbar-button-save',
actionBtn2: '.wb-new .wikibase-toolbar-button-save a',
}, {
// 10. Congratulations!
// The function below should be included on the last slide
// It makes the final "OK" click redirect back to the tours home page
// Note: This is a temporary hack, it will not be needed in the near future
onShow: function() {
// Todo: should be the default action for clicking the "end tour" button on any Wikidata
$('.guidedtour-end-button').off('click').on('click', function() {
window.location = window.location.origin + '/wiki/Wikidata:tours';
})
}
} ]
} );
} )( jQuery, mediaWiki, mediaWiki.guidedTour, wikibase );
tourName
This is the name used to identify the tour, it is used in the URL when launching the tour. The name must:
- Be unique, so no two tours can have the same name.
- Only use lowercase normal text, with no spaces, hyphens or other special characters.
- Match the name at the end of the JavaScript filename (e.g. set to "wbmycooltour" in the file MediaWiki:Guidedtour-tour-wbmycooltour.js).
- Start with "wb" in keeping with convention for other tours (e.g. "wbqualifiers" or "wbuniqueidentifiers").
- Be kept as brief as possible (e.g. "wbstatements" or "wbofficialwebsite").
tourEntityId
Enter the Q number of the Tour item created in the previous step. This is the dedicated Wikidata item that will be loaded when the tour runs. The item you enter here will not not be used until you run the final tour during the Publish step, but it's good to have it recorded at this stage.
Important: The tour item will be cleared of data completely every time a user takes the tour, so you should never use a 'normal' Wikidata item for your tour!
newData
newData is a JavaScript object containing all of the data that you want to add to the tour item on initialisation, such as labels, descriptions and statements.
As the tour item is cleared whenever a user starts the tour, leaving the startup data as an empty object { } will mean the tour always starts as a completely blank item.
Using existing item data
The format for providing startup data matches the standard Wikibase syntax for describing items, so you can easily export from any existing item. The two main approaches are:
- Using the Linked Data interface: For example, you could copy the entire contents of http://www.wikidata.org/entity/Q42.json and paste it into your JavaScript file if you wanted a complete copy of Douglas Adams (Q42). This is generally useful when copying from an item with not too much data
- Using the Wikidata API wbgetentities action: This allows you to control which types of data you want to get back, including filtering by language. For example, this API call returns statements, along with labels and descriptions in English and French - https://www.wikidata.org/w/api.php?action=wbgetentities&ids=Q42&languages=en%7Cfr&props=claims%7Clabels%7Cdescriptions
The normal approach is to filter down to just the starting data that is required to carry out the tour, as well as generally set the scene and make it feel like editing a real item. However, it is strongly advised to keep the label in all available languages to aid translation of the tour (more info below).
Labels and descriptions in your startup data
- Always add a label to your item's startup data (unless the tour is actually about adding the label). The label provides important context for new users.
- You should include the label in all available languages. As explained above, the startup data is usually copied from an existing popular item, so the label will be available in a large number of different languages. Adding this data now means that labels will likely already be available as the tour is translated into different languages. See the Translate page for further info.
- You should always add a description of the form "Test item for TOUR NAME tour only" (replace TOUR NAME with the name of the tour). As tour items are just normal Wikidata items, they can show up in the search box. Adding this description makes sure everyone is aware that the item is not the real item for that topic - e.g. the tour item Earth (Test item for References tours only) vs the 'real' item Earth (third planet from the Sun in the Solar System).
- If you add both labels and descriptions in the newData object, you must make sure that the combination of label + description is unique on Wikidata. If it's not, the tour will not load! This is because the initial edit to add startup data will be rejected. This can be achieved by following the previous point on adding a description.
Step configuration
Each step in the tour has a JavaScript object to describe it's functionality. These are added to the steps array in the initialisation options, with one object for each step in the tour. For any step that that should just float in the middle of the page, and has no special action to complete, you can just use an empty object.
You should start by adding an empty object for every step, with a comment above each one to indicate the title of the step and any special instructions (copy this from corresponding Tour Wiki page). This will help you keep track of what needs doing as you work through the settings for each step.
The options available for each step are:
| Property | Allowed values | Description |
|---|---|---|
| position |
|
Determines the position of the popup relative to the element you are attaching to. If no attachTo has been set, then this setting will be ignored.
|
| attachTo |
*Any valid JQuery selector |
Selector for the element the pop up should attach to. If you leave this blank, then the popup will float in the middle of the page. |
| actionBtn2 |
*Any valid Query selector |
Selector for a click action that needs to be completed for the step to advance. Entering a value for this has two important functions:
Some important points about this property:
|