امتداد:جولة تعريفية

الدليل المرجعي لامتدادات ميدياويكي

GuidedTour حالة الإصدار مستقر
تنفيذ	صفحة خاصة , تصرف خاصة بالصفحة
بيان	يقدّم جولة تعريفية منبثقة على صفحات الويكي أو استبيانات قصيرة أو كليهما.
المؤلف/المؤلفون	Munaf Assaf, Terry Chay, Matt Flaschen, Pau Giner, Ori Livneh, Rob Moen, S Page, Sam Smith, Moiz Syed, Luke Welling
آخر إصدار	Continuous updates
MediaWiki	1.32+
PHP	5.4+
ترخيص	رخصة أباتشي 2.0
التنزيل	تنزيل الامتداد غت [?]: تنزيل ملف غت الرئيسي تصفح المستودع (Phabricator · GitHub) تاريخ الالتزام مساهمو المستودع (غت هب) مراجعة الكود البرمجي
الروابط المستخدمة BeforePageDisplay MakeGlobalVariablesScript RedirectSpecialArticleRedirectParams ResourceLoaderRegisterModules
Internet Explorer compatibility: none for 6, partial for 7.
تنزيلات ربع سنوية	5 (Ranked 135th)
استخدام مواقع الويكي العمومية	893 (Ranked 266th)
ترجم الامتداد GuidedTour لو كان متوفرا على translatewiki.net
المسائل	المهام المفتوحة · الإبلاغ عن عطل تقني

The GuidedTour extension provides a framework for creating "guided tours," or interactive tutorials for MediaWiki features. Tours typically walk a user through some standard workflow (like editing an article or uploading an image) and are implemented as a series of dialog boxes that tell the user where to click and what to do next.

Tours are backed by JavaScript and PHP code that can monitor the user's progress, check their understanding, and offer advice and encouragement. Guided tours are an effective means for breaking down complex tasks into a series of simple, discrete sub-tasks, and for giving the user the experience and confidence needed to repeat the workflow for similar tasks in the future. Tours may also be used to implement interactive surveys.

GuidedTour was developed by the (former) Growth team. It is partly based on Optimize.ly's Guiders library. GuidedTour originally started at WMF Tech Days 2012.

Note that there are some performance concerns with using this extension.

تثبيت امتداد جولة تعريفية على موقعك الويكي واستخدامه

• Test that it worked by calling a page with tour=test appended to the URL. For example: http://localhost/w/index.php?tour=test
• نزّل الملف/الملفات وضعها في دليل يحمل اسم ‎GuidedTour داخل مجلد ‎extensions/‎ لديك.
  يجب على مطوري البرمجيات والمساهمين بالكود البرمجي تثبيت الامتداد من غت بدلا من ذلك، مستخدمين:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/GuidedTour
• أضف الكود التالي في الجزء الأسفل من ملف LocalSettings.php :

  wfLoadExtension( 'GuidedTour' );
  

•  تم التنفيذ – اذهب إلى Special:Version على موقع الويكي لديك كي تتحقق من أن الامتداد قد ثبت بنجاح.

إن أردت استخدام امتداد الجولات التعريفية، عليك أن...

1. Write a real tour on a page in the MediaWiki namespace. It must be named MediaWiki:Guidedtour-tour-tour name.js, for example MediaWiki:Guidedtour-tour-mytour.js
2. تستدعي الصفحة المطلوبة مستخدمًا ‎tour=mytour التي تضاف إلى معرف الموارد الموحد. مثال على ذلك:

   http://localhost/w/index.php?tour=mytour , or ?tour=test for the example above.

3. To style the output, either edit the css file in the modules directory or add overrides to MediaWiki:Common.css

Note: for security reasons, tours cannot run on some pages, including login, account creation, user preferences, and password reset.

معلومات أساسية

Our communities were once limited to using static wiki pages, templates, and other functions to build tutorials and tours of any kind. As rich as tools like Wikipedia:Tutorial might be, they interrupt the user and force them to go to a separate Web page. They are also quite long; most documentation about Wikipedia would take quite some time to read in full.

تجربة المستخدم

Interactive guided tours provide a simple, step-by-step guide through a feature set without interrupting the user. Guided tours don't dominate the screen, are dismissable, and walk the user through a task directly. Guided tours are also ideally something that one can return to at any time when you need it.

Each step in a guided tour is called a "guider."

وصف عناصر الدليل التعريفي

Title

Names the current step. If the title is the beginning of the tour, you may need to use it to describe the tour as a whole. If your tour title is more than one line, it's too long.

Body text

Describes the current step. If you make additional points unnecessary for the user to understand how to move to the next step, you're saying too much. Guided tours are effective not just because tooltips point at things, but because they limit instructional text to what is immediately necessary, rather than trying to dump paragraphs of documentation on a user all at once.

Buttons

tour buttons are for actions, typically progressing the user to the next step. By default, guided tour buttons use the "progressive" class from the mediawiki.ui library. It is a poor practice to provide multiple action buttons, e.g. "Start tour" plus "Next." Choose one action you want the user to take in response to a tour step, focus on completion of that action. Never use the action button for ending the tour (unless the user is actually at the end), since this muddles whether the primary action buttons is for continuing the tour or ending it (positive vs. negative action). If your guider step points to an additional action you want the user to take (e.g. "Edit" or "View history), it is a bad idea to have the tour button perform this action for them. Instead, point to the element you wish a user to use, and encourage them to give it a try, so they learn how to use a function as they normally would.

Close button (X)

provides an obvious element for dismissing a tour, as opposed to simply closing a single guider, which can be done by an outside click or hitting ESC. If the user clicks this close button, it should end the tour across pages, and will clear the associated tour from the user's cookies.

Location

Guiders can be positioned as either a "central overlay" or an "attachment". "Attachments" are positioned next to specific page elements (for example, a link or tab) using CSS selectors. The position of the guider relevant to the page element is specified with orientations such as topLeft, top, topRight, rightTop, right, etc. (See details)

وصف سلوك الدليل التعريفي

A short video of the 'firstedit' tour, which shows basic behavior like callouts, animations, and more

Keep in mind the following default behaviors for guided tours:

• If a guider is not visible (i.e. above or below the fold) for a user, the browser will scroll the user to the location of the guider. You can choose to disable this for individual steps.
• Guiders animate in to view by default, unless it requires scrolling to see. Animations can be disabled if you are writing a tour.
• If a user has launched multiple tours, the most recent tour started will always be displayed, if there is a conflict.
• You can force a tour to "stick" to a particular page. If you have not defined this behavior in your tour, a tour in progress might keep showing across pages. For instance, if you have a tour that points to the "Save" button, a tour that is in progress might point at this element every time until the user moves to the next step or dismisses the tour.
• A guider will flip horizontally to the left or right, if it would otherwise be cut off by the width of the user's browser. You can also disable this for each step.

تصميم جولة تعريفية

إن أردت تصميم جولة تعريفية خاصة بك، إليك بعض الأمور التي يمكنك النظر فيها جديًا:

1. Choose a primary goal for the tour. What do you want users to learn by the end?
2. Know who your audience is before you start, and what their goals and experiences are. What knowledge about a process do they have before starting your tour?
3. Plot the necessary steps, focusing on the one action or key takeaway for each step. Less is more. The more steps in your tour, the more likely a user is to abandon your tour in the middle.
4. Tours can be started via a link or button within a page, or automatically via a cookie. How you start a tour has a big impact on the potential for delivering tours that interrupt or annoy users, so choose carefully.
5. Let the steps and their associated actions guide the design of the tour. For example, if you want users to edit as one step, pointing directly to the edit button is the obvious and efficient thing to do. A poor alternative would be to have a center-aligned window with an image and description of the edit tab. The strength of tooltip-based tours is that you can show users what to do, instead of simply describing it.
6. Choose titles, body text, and images only after you have plotted all steps in your tour.

قائمة الجولات التعريفية

GuidedTour

الجولات التعريفية التالية محزومة في الوقت الحالي مع الامتداد، وهي بالتالي متاحة على أي موقع ويكي ثبّت فيه امتداد GuidedTour.

• Test - Simple tour to show what tours can do (Code, demonstration).
• First edit - A tour showing you how to make your first edit using the wikitext (Code, demonstration) editor or VisualEditor (Code, demonstration).

على موقع الويكي

• The Wikipedia Adventure - this project is a pilot of a game-like experience for learning the ropes, hosted at The Wikipedia Adventure on English Wikipedia (Level 1 Code).
• WikiMOOC #2, french MOOC about Wikipedia using 17 tours (marked as interactive tutorial on the table of content).
  • List of all the starting pages: fr:Category:Tutoriel WikiMOOC 2017
  • List of all the corresponding JS scripts: fr:Category:Guided tour
• Aide:Wikipédia Pas à Pas, a re-use of these tutorials in a standalone version.

Feel free to add your own tours to the appropriate list above.

Find more examples by searching for "prefix:MediaWiki:Guidedtour-tour", e.g. at Enwiki.

أفكار لتصميم جولات تعريفية

Potential tours include nearly all tasks currently covered by help documentation in Wikimedia projects. We're starting with Wikipedia, and with tasks that are most common or attractive to new registered editors, since they are a group most likely to need a guided tour of an interface or activity.

• Page creation
• 'Your user page' - what it's for, etc.
• How to add/edit a reference
• How to add an image
• Watchlist - what are the important elements of it, how to add stuff to it, etc.
• Process helpers: how to request a move, how to file a deletion request, etc.

Please add to the list!

توثيق فني

Building and launching tours

You launch a guided tour on a page by adding tour=tourname to the query string of a URL linking to it, or by calling mw.guidedTour.setTourCookie( tourName ) to set a cookie for the next page load. You can also launch it immediately with mw.guidedTour.launcher.launchTour (requires only the ext.guidedTour.launcher module). You can set the cookie from the server if appropriate too. This will cause the GuidedTour extension to load both the code to display the tour and the tour itself.

You define your tour in a JavaScript file in your extension, or in the MediaWiki namespace (MediaWiki:Guidedtour-tour-tourname.js). Much of this file simply names the elements of each step of the tour — a titlemsg, descriptionmsg, a 'next' button, etc. Individual wikis can override the CSS at MediaWiki:Guidedtour-custom.css.

• To add a tour by editing your wiki, see Write an on-wiki tour. Any local wiki administrator can do this.
• To bundle a tour with your extension, see Write an extension tour. This requires access to the code repository for your wiki and the right to install extensions.
• For API documentation, see https://doc.wikimedia.org/GuidedTour/master/#!/api/mw.guidedTour