diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md new file mode 100644 index 00000000..215ce08e --- /dev/null +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -0,0 +1,186 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Create a What's New tour + +In the following documentation, we explain how a `What's New tour` can be created to enhance the user experience when updating a Joomla! instance. + +What's New tours are available in major and minor Joomla releases, only for users who update. + +:::note [Developer Note] + Replace X and Y with the major and minor version numbers. + For instance, X_Y is 5_3 if you create a PR for the what's new tour for version 5.3. +::: + + +## Step 1: Create the What's New tour + +Enter the following parameters: + +**Title:** What’s New in Joomla X.Y! +**Identifier:** joomla-whatsnew-X-Y +**Component Selector:** Home dashboard +**Autostart:** yes +**Relative Url:** administrator/index.php +**Description:** + +```html +

Welcome to Joomla X.Y!

+``` + +It is easier to create the description from a copy of a previous tour and re-use the formated text. + +Include the sections: +- Guided tour updates +- Core updates + +If you have images, add them into the folder ``media/com_guidedtours/images/X_Y``. + +## Step 2: Create a step for the tour + +**Title:** More Information and Help +**Position:** right +**Target:** `#sidebarmenu nav > ul:first-of-type > li:last-child` +**Description:** + +```html +

Joomla X.Y Full Release Notes

+

View the full release notes on joomla.org

+
+

Help and Information

+

Many resources to help you can be found here together with additional links to more resources, documentation, support and how to become involved in Joomla.

+``` + +## Step 3: Install the Guided Tours toolkit + +The toolkit can be found at [the toolkit extension GitHub page](https://github.com/joomla-extensions/tours-toolkit). + +## Step 4: Export the tour + +Go to the newly created tour. +Select Export (in the top right end corner), and select 'SQL + INI Export'. +This generates the code necessary for importing tours through code. It actually generates the language keys even though the tour was created in plain English. +The file can be found in your browser's download folder. + +## Step 5: How to create the PR + +Open the generated text file. +Create a branch based on the Joomla/X.Y-dev from the forked Joomla repository under your account. + +### Create language files + +Go to the administrator/language/en-GB folder. + +``` +administrator/language/en-GB/guidedtours.joomla_whatsnew_X_Y.ini +administrator/language/en-GB/guidedtours.joomla_whatsnew_X_Y_steps.ini +``` + +and fill with the generated language keys. + +### Create media file(s) + +If there are images, add them to + +``` +build/media_source/com_guidedtours/images/X_Y +``` + +Keep the image file names simple (all lowercase). +In order to create a folder in GitHub and be able to upload the image(s), you may need to create a tada.txt file first (arbitrary name) in that directory (delete it when done). + +### Create SQL files + +Go to the administrator/components/com_admin/sql/updates. + +``` +administrator/components/com_admin/sql/updates/mysql/X.Y.0-YEAR-MONTH-DAY.sql +administrator/components/com_admin/sql/updates/postgresql/X.Y.0-YEAR-MONTH-DAY.sql +``` + +and fill with the generated SQL statements. + +BEFORE those statements, include: + +On a major release (for instance 5.0), add the statements to remove ALL prior what's new tours: + + + +```sql +-- uninstall previous tours +DELETE FROM `#__guidedtour_steps` + WHERE `tour_id` IN (SELECT `id` FROM `#__guidedtours` WHERE `uid` LIKE 'joomla-whatsnew-%'); + +DELETE FROM `#__guidedtours` + WHERE `uid` LIKE 'joomla-whatsnew-%'; +``` + + +```sql +-- uninstall previous tours +DELETE FROM "#__guidedtour_steps" + WHERE "tour_id" IN (SELECT "id" FROM "#__guidedtours" WHERE "uid" LIKE 'joomla-whatsnew-%'); + +DELETE FROM "#__guidedtours" + WHERE "uid" LIKE 'joomla-whatsnew-%'; +``` + + + +On a minor release (for instance 5.3), set the previous What's New tour to NOT autostart: + + + +```sql +-- disable autostart for the previous tour +UPDATE `#__guidedtours` SET `autostart` = 0 WHERE `uid` = 'joomla-whatsnew-X-YY'; +``` + + +```sql +-- disable autostart for the previous tour +UPDATE "#__guidedtours" SET "autostart" = 0 WHERE "uid" = 'joomla-whatsnew-X-YY'; +``` + + + +where YY is the previous minor release number. +For instance, if the PR is for the version 5.3, YY is 2. + +### Go to the Pull Requests tab + +Select 'Compare & pull request'. + +### Enter the title: + +[X.Y] Guided Tours: What's New + +### Enter the description: + +``` +### Summary of Changes + +This PR adds a tour that highlights new features introduced in Joomla X.Y. + +### Testing Instructions + +Download the update package, not the full install as the tour is only available on updates! + +It is possible to find the tour in the list of tours at the top of the Joomla dashboard and run it manually. +Make sure you see images when running the tour (on the first step only) and when editing the tour (System -> Manage -> Guided tours). + +### Actual result BEFORE applying this Pull Request + +No tour highlighting new features for Joomla X.Y. + +### Expected result AFTER applying this Pull Request + +The What’s New in Joomla X.Y! tour is available. +``` + +Add images of the tour so that testers can have an idea of what the tour looks like. + +## Step 6: Test the PR (turn it into a draft) + +Make sure all goes according to plan before requesting users to test. Do this by setting the PR to draft, wait until the system validates it and creates downloadable files. +Use the generated files (don't run a full install or else you won't have the tour included). diff --git a/docs/general-concepts/guided-tours.md b/docs/general-concepts/guided-tours/creating-tours.md similarity index 88% rename from docs/general-concepts/guided-tours.md rename to docs/general-concepts/guided-tours/creating-tours.md index dbcd2427..f3415a2b 100644 --- a/docs/general-concepts/guided-tours.md +++ b/docs/general-concepts/guided-tours/creating-tours.md @@ -1,13 +1,10 @@ -Guided Tours -============ - The simplest way to create tours for your organization or extensions is to create those tours with the tools provided in Joomla. Go to System (Manage section) -> Guided Tours. ## Creating a new tour -Starting with Joomla 5, an identifier is provided for each tour. This is not a required field but a value will always be present. +An identifier is provided for each tour. This is not a required field but a value will always be present. This identifier is supposed to: - allow a tour to be started from anywhere, @@ -77,7 +74,7 @@ There is no available tour when editing a specific module, plugin or template. T ### Auto start -Starting with Joomla 5.2, you can set tours to auto start. Those tours will run automatically once a user enters the context of the tour. Once a tour auto starts, the user can hide the tour forever (although the tour can still be run manually), and a cancellation will delay the tour for a later run. Once a specific time has passed (the delay setting can be found in the Global Configuration of the Guided Tours - it defaults to 1 hour), the tour will run again automatically, once in context. +You can set tours to auto start. Those tours will run automatically once a user enters the context of the tour. Once a tour auto starts, the user can hide the tour forever (although the tour can still be run manually), and a cancellation will delay the tour for a later run. Once a specific time has passed (the delay setting can be found in the Global Configuration of the Guided Tours - it defaults to 1 hour), the tour will run again automatically, once in context. ### Event dispatchers diff --git a/docs/general-concepts/guided-tours/index.md b/docs/general-concepts/guided-tours/index.md new file mode 100644 index 00000000..6f13631a --- /dev/null +++ b/docs/general-concepts/guided-tours/index.md @@ -0,0 +1,4 @@ +--- +title: Guided Tours +--- +This section describes the concept of Tours.