Wikidata:Comment créer des visites guidées Wikidata/Javascript
Créer une page Javascript
Toutes les visites guidées nécessitent un fichier JavaScript qui contient un ensemble d'options pour configurer la visite. Les droits Administrateurs d'interface sont nécessaires pour déployer un fichier JavaScript à des fins de test, vous devrez donc utiliser cette Liste des utilisateurs pour trouver quelqu'un pour vous aider lorsque vous atteindrez cette étape. Le reste des instructions sur cette page sont destinées à l'administrateur d'interface qui est rédigée pour aider.
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.
Nom et emplacement du fichier
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.
Pour résumer, le fichier doit se trouver aux endroits suivants au fur et à mesure que vous progressez dans les étapes de la visite guidée:
Espace de nom d'utilisateur
(Current step) 
MediaWiki namespace test.wikidata.org
(Etape de test)
MediaWiki namespace www.wikidata.org
(Etape de publication)
Structure
En supposant que vous créez une visite guidée appelée "Ma visite guidée cool", vous auriez besoin des éléments suivants :
- 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
Le fichier JavaScript pour "Ma visite guidée cool" serait complété avec les détails indiqués dans l'exemple de modèle ci-dessous. Comme il ne s'agit que d'une visite fictive, la page Wiki et le fichier JavaScript n'existent pas, mais vous pouvez consulter les fichiers de la visite Références pour un exemple réel :
- 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
Développez l'exemple ci-dessous pour le modèle que vous pouvez copier et coller comme point de départ.
/*
* @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
C'est le nom utilisé pour identifier la visite, il est utilisé dans l'URL lors du lancement de la visite. Le nom doit :
- 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 est un objet JavaScript contenant toutes les données que vous souhaitez ajouter à l'élément de visite guidée lors de l'initialisation, telles que les étiquettes, les descriptions et les instructions.
Comme l'élément de visite guidée est effacé chaque fois qu'un utilisateur démarre la visite, laisser les données de démarrage sous la forme d'un objet vide { } signifie que la visite commence toujours comme un élément complètement vide.
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:
| Propriété | Valeurs autorisées | Description |
|---|---|---|
| position |
|
Détermine la position de la fenêtre contextuelle par rapport à l'élément auquel vous vous attachez.
Si aucun attachTo n'a été défini, ce paramètre sera ignoré.
|
| attachTo |
|
Sélecteur de l'élément auquel la fenêtre contextuelle doit s'attacher.
Si vous laissez ce champ vide, la fenêtre contextuelle flottera au milieu de la page. |
| actionBtn2 |
|
Sélecteur d'une action de clic qui doit être effectuée pour que l'étape avance. La saisie d'une valeur pour cela a deux fonctions importantes:
Quelques points importants sur cette propriété :
|