تورهای راهنما

ساده‌ترین روش برای ایجاد تورهای راهنما برای سازمان یا افزونه‌های خود، استفاده از ابزارهای ارائه‌شده در جوملا است.

به مسیر زیر بروید: 

System (بخش مدیریت) -> Guided Tours

ایجاد یک تور جدید

از نسخه ۵ جوملا، برای هر تور یک شناسه (identifier) ارائه شده است. این فیلد ضروری نیست اما همیشه یک مقدار دارد. هدف این شناسه عبارت است از:

- امکان شروع تور از هر مکانی،

- متمایز کردن تورها و نشان دادن منبع آن‌ها،

- تعیین ساختار نام فایل‌های زبان در صورت نیاز به آن‌ها،

- امکان به‌روزرسانی آسان تورهای موجود و ردیابی آن‌ها در پایگاه داده.

در جوملا ۵ همچنین دو فایل زبان جداگانه ایجاد می‌شود؛ یکی برای خود تور و دیگری برای مراحل تور.

شناسه (Identifier)

یک رشته منحصر به فرد است، مشابه نام مستعار یک مقاله. قالب آن باید به این صورت باشد:

authorname-tourname

companyname-tourname

domain-tourname

مثلاً یک تور خوش‌آمدگویی ساخته شده توسط جوملا شناسه‌ای مطابق `joomla-welcome` دارد. بخش‌هایی مانند authorname، companyname و domainname باید یک کلمه بی‌وقفه باشند و tourname می‌تواند شامل خط تیره باشد.

تا زمانی که تور شما «امضای» خودتان را دارد و در مجموعه تورهای شما منحصر به فرد است، هیچ مشکل تکراری برای کاربران پیش نمی‌آید.

این شناسه به ستون `uid` در جدول `#__guidedtour` مربوط است. هنگام ذخیره یا کپی کردن، یک رشته شناسه پیشنهادی ساخته می‌شود.

فایل‌های زبان

تمام تورها به فایل زبان نیاز ندارند، به ویژه اگر فقط مخاطب یک زبان هدف باشد. ولی در صورت نیاز، فایل‌ها باید طبق استاندارد جدید که توسط شناسه مشخص شده است، ساخته شوند.

برای مثال، برای تور با شناسه `joomla-welcome`، فایل‌های زبان به شکل زیر خواهند بود:

guidedtours.joomla_welcome.ini

guidedtours.joomla_welcome_steps.ini

فایل اول فقط شامل دو کلید است، یکی برای نام تور و یکی برای توضیحات آن، و فایل دوم تمامی کلیدهای مربوط به مراحل تور را دارد.

تمام فایل‌های زبان باید با یکی از این پیشوندها شروع شوند: `extensionname`، `com_extensionname`، `mod_modulename`، `plg_[group]_pluginname` یا `tpl_templatename` و با `.ini` یا `_steps.ini` خاتمه یابند.

یادآوری: کلیدهای زبان می‌توانند هر چیزی باشند ولی باید شامل کلمه `GUIDEDTOUR` در کلید باشند تا تور و مراحل به درستی تشخیص داده شوند.

فایل‌های زبان لازم نیست حتما در مسیر `administrator/language/[language]/` قرار بگیرند؛ می‌توان آن‌ها را در داخل ساختار فایل‌های افزونه گذاشت.

زمینه تور (Tour Context)

از زمانی که تورها در جوملا معرفی شده، پارامتری به نام انتخابگر کامپوننت (Component selector) وجود داشته است. تعریف این پارامتر در جوملا ۵ کمی متفاوت است.

حالا در هر صفحه‌ای که ماژول «تور را آغاز کن» نمایش داده می‌شود، تورهایی که در زمینه همان صفحه هستند، اولویت نمایش دارند.

انتخاب یک کامپوننت، باعث می‌شود تور هنگام نمایش در آن کامپوننت به عنوان «تور مورد علاقه» علامت‌گذاری شود. گزینه «همه» باعث می‌شود تور در تمام صفحات اولویت داشته باشد اما انتخاب این گزینه توصیه نمی‌شود. به عنوان یک توسعه‌دهنده شخص ثالث، بهتر است افزونه‌هایی که تور مربوط به آن‌هاست را انتخاب کنید.

مثلاً تور «چگونه مقالات ایجاد کنیم» در نماهای «مقالات»، «مقالات ویژه» یا «دسته‌بندی‌ها» با اولویت نمایش داده می‌شود. برای این منظور، انتخابگر کامپوننت تور روی «مقالات» و «دسته‌بندی‌ها» تنظیم شده است.

تورهای دسته‌بندی برای هر کامپوننت به طور جداگانه شناخته می‌شوند. برای مثال، اگر تور دسته‌بندی برای `com_contact` ساخته شده باشد، این تور هنگام حضور در بخش «تماس‌ها» به عنوان تور مورد علاقه نشان داده می‌شود ولی تور دسته‌بندی مقالات اینطور نیست.

وقتی یک ماژول، پلاگین یا قالب خاص را ویرایش می‌کنید، هیچ توری قابل دسترس نیست که در این موارد، امکان شروع تور از هر جا اهمیت پیدا می‌کند.

شروع خودکار تور (Auto start)

از جوملا ۵.۲ به بعد، می‌توانید تورها را تنظیم کنید که به صورت خودکار شروع شوند. این تورها وقتی کاربر وارد زمینه مربوطه شود به صورت اتومات اجرا می‌شوند. کاربر می‌تواند نمایش تور را مخفی کند، اما هنوز می‌تواند دستی آن را اجرا کند. اگر کاربر لغو کند، تور برای اجرا بعدی به تأخیر می‌افتد.

مدت تأخیر را می‌توان در پیکربندی کلی تورهای راهنما تنظیم کرد (به طور پیش‌فرض ۱ ساعت است). پس از سپری شدن این زمان، تور دوباره خودکار اجرا می‌شود.

رویدادهای اطلاع‌رسان (Event dispatchers)

زمانی که کاربر لغو، انصراف یا پایان یک تور را اعلام می‌کند، رویدادهایی فعال می‌شوند که امکان واکنش توسعه‌دهندگان به این اقدامات را فراهم می‌کنند. مثلاً می‌توان پس از پایان تور، یک پیام به کاربر ارسال کرد تا تور دیگری پیشنهاد شود.

این رویدادها در مراحل زیر فعال می‌شوند:

- `onBeforeTourSaveUserState`: قبل از ذخیره وضعیت تور خودکار کاربر (برای ثبت در گزارش‌های فعالیت کاربران)،

- `onAfterTourSaveUserState`: بعد از ذخیره وضعیت تور.

می‌توانید این رویدادها را در کلاس AjaxController پیدا کنید.

افزودن تصاویر به محتوا

برای افزودن تصویر به توضیحات محتوا از ویرایشگر استفاده کنید. تصاویر معمولاً در پوشه `media` یا به طور پیش‌فرض در `/images` قرار دارند. مخصوصاً هنگام ایجاد تور برای افزونه‌های ثالث، شاید بخواهید تصاویر را از پوشه رسانه‌های آن افزونه استفاده کنید که مسیر تصویر باید با `media/...` شروع شود.

شروع تور از هر مکان

شروع یک تور از هر جای دیگر به غیر از ماژول تورهای راهنما، به سادگی اضافه کردن صفت `data-gt-uid` به همراه شناسه تور است.

برای مثال، یک ماژول سفارشی در داشبورد کنترل پنل ایجاد کرده و کد HTML زیر را اضافه کنید:

<button class="btn btn-primary button-start-guidedtour" type="button" data-gt-uid="joomla-articles">How to create articles?</button>
<button class="btn btn-secondary button-start-guidedtour" type="button" data-gt-uid="joomla-contacts">How to create contacts?</button>