From cf50cbd0b913ebdcd215711cf986068a5ad81c69 Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Sun, 26 Jan 2025 11:36:47 -0500 Subject: [PATCH 01/16] Create index.md --- docs/general-concepts/guided-tours/index.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 docs/general-concepts/guided-tours/index.md diff --git a/docs/general-concepts/guided-tours/index.md b/docs/general-concepts/guided-tours/index.md new file mode 100644 index 00000000..4f7c53a2 --- /dev/null +++ b/docs/general-concepts/guided-tours/index.md @@ -0,0 +1,4 @@ +--- +title: Guided Tours +--- +This section describes the concept of Tours, which were introduced in Joomla! 4.3. From c0fe84e0e5ac20922f4dbcdb7b6eb5de3cc31e34 Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Sun, 26 Jan 2025 11:41:07 -0500 Subject: [PATCH 02/16] Create creating-tours --- .../guided-tours/creating-tours | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 docs/general-concepts/guided-tours/creating-tours diff --git a/docs/general-concepts/guided-tours/creating-tours b/docs/general-concepts/guided-tours/creating-tours new file mode 100644 index 00000000..41b6c61e --- /dev/null +++ b/docs/general-concepts/guided-tours/creating-tours @@ -0,0 +1,106 @@ +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. +This identifier is supposed to: + +- allow a tour to be started from anywhere, +- differentiate tours, and gives a hint on their origin, +- give the file name structure for the language files, if any is required for the tour, +- allow possible updates on an existing tour, easily traceable in the database. + +New in Joomla 5 as well is the creation of 2 separate language files. One for the tour and one for the steps of the tour. + + +### The identifier + +This is a unique string, very much like an alias for an article. +The string should be formatted as: + +``` +authorname-tourname +companyname-tourname +domain-tourname +``` + +For instance, a welcome tour created by Joomla would have an identifier name `joomla-welcome`. +authorname, companyname, domain name should be one single word, tourname can contain dashes. + +As long as the tour you create includes your 'signature' and is unique in your pool of tours, there will be no duplication issue for users. + +The identifier corresponds to the `uid` column of the `#__guidedtour` table. +On save or duplicate, a suggested identifier string is created. + + +### The language files + +Not all tours need language files, especially if you are only targetting a one-language audience. +But if you do need them, the files need to follow the new convention didacted by the identifier. + +For instance, for the tour with identifier `joomla-welcome`, the language files will be: + +``` +guidedtours.joomla_welcome.ini +guidedtours.joomla_welcome_steps.ini +``` + +where the first file only contains 2 keys, one for the tour name and one for its description and the second file contains all step keys. + +All language files need to start with 'extensionname', 'com_extensionname', 'mod_modulename', 'plg_[group]_pluginname' or 'tpl_templatename', end with `.ini` or `_steps.ini`. + +Reminder: the language keys can be anything BUT need to contain GUIDEDTOUR in the key. This is to allow the tour and step views to properly distinguish what is a language key and what is just regular content. + +Language files do not need to be placed into administrator/language/[language]/. You can leave the files inside the extension's file structure. + + +### The tour context + +A `Component selector` parameter has been available ever since tours have been introduced in Joomla. +The definition of 'component selector' slightly differs in Joomla 5. +Now, on any given page where the module 'Take a tour' is showing, the tours being in the context of the page are the ones showing in priority. + +Selecting a component will ensure the tour will be tagged as 'favorite' when in the component's views. 'All' will show the tour in priority in all pages. Leaving the selection to 'All' is not recommended. As a third party developer, you would select the extension(s) the tour is tied to. + +For instance, the 'How to create articles' tour will be visible in priority when in an 'Articles', 'Featured articles' or 'Categories' views. +To allow that, the tour's component selector is set to 'Articles' and 'Categories'. + +Note that the Guided Tour component knows how to differentiate category tours for specific components. For instance, if you create a categories tour for com_contact, the category tour for articles won't show as a favorite tour when in 'Contact' context. + +There is no available tour when editing a specific module, plugin or template. That is where launching a tour from anywhere can become handy. + + +### 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. + + +### Event dispatchers + +Once a user cancels, opts-out or completes a tour, events are triggered, allowing developers to act according to user actions. One may want to send a message to a user after completion of a tour in order to propose another one, for instance. +Those events are triggered at different stages: +- onBeforeTourSaveUserState: before saving the auto-start tour user state (used to record states in the User Action Logs), +- onAfterTourSaveUserState: after saving the auto-start tour user state. + +You can find those events in the AjaxController class. + + +### Adding images to the content + +Use the editor to include images inside the content descriptions. Images are located in the media folder, ```/images``` by default. +However, expecially when creating a tour for a third party extension, you may want to include images located in the media folder of the extension. +In this case, the image path must start with ```media/...```. + + +## Launching a tour from any location + +Launching a tour from a different location than the Guided Tours module is as easy as adding the attribute `data-gt-uid` with the identifier of the tour. + +As an example, create a custom module in the cpanel dashboard and add this HTML to it: + +``` + + +``` From c1a6ce8f52e1839981601454c70a7697d704856a Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Sun, 26 Jan 2025 11:43:45 -0500 Subject: [PATCH 03/16] Rename creating-tours to creating-tours.md --- .../guided-tours/{creating-tours => creating-tours.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/general-concepts/guided-tours/{creating-tours => creating-tours.md} (100%) diff --git a/docs/general-concepts/guided-tours/creating-tours b/docs/general-concepts/guided-tours/creating-tours.md similarity index 100% rename from docs/general-concepts/guided-tours/creating-tours rename to docs/general-concepts/guided-tours/creating-tours.md From 60c1e0d9c292500f72917d267749879647dc2a21 Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Sun, 26 Jan 2025 12:20:23 -0500 Subject: [PATCH 04/16] Created create-whatsnewtour.md --- .../guided-tours/create-whatsnewtour.md | 167 ++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 docs/general-concepts/guided-tours/create-whatsnewtour.md 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..a2f55165 --- /dev/null +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -0,0 +1,167 @@ +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: +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` +``` +

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` +``` +

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 ``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. +The file can be found in your browser's download folder. + +## Step 5: Create the PR + +Open the generated file. +Create a PR in a branch you have created from the forked Joomla repository. + +### 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. + +### Create files + +``` +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 files + +If there are images, add them to + +``` +build/media_source/com_guidedtours/images/X_Y +``` + +### Create files + +``` +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: + +MySQL: +``` +-- 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-%'; +``` + +PostgreSQL: +``` +-- 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: + +MySQL: +``` +-- disable autostart for the previous tour +UPDATE `#__guidedtours` SET `autostart` = 0 WHERE `uid` = 'joomla-whatsnew-X-YY'; +``` + +PostgreSQL: +``` +-- 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. From 942351c38e3209c934c32625337a5282e642d68a Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Sun, 26 Jan 2025 12:20:51 -0500 Subject: [PATCH 05/16] Delete docs/general-concepts/guided-tours.md --- docs/general-concepts/guided-tours.md | 109 -------------------------- 1 file changed, 109 deletions(-) delete mode 100644 docs/general-concepts/guided-tours.md diff --git a/docs/general-concepts/guided-tours.md b/docs/general-concepts/guided-tours.md deleted file mode 100644 index dbcd2427..00000000 --- a/docs/general-concepts/guided-tours.md +++ /dev/null @@ -1,109 +0,0 @@ -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. -This identifier is supposed to: - -- allow a tour to be started from anywhere, -- differentiate tours, and gives a hint on their origin, -- give the file name structure for the language files, if any is required for the tour, -- allow possible updates on an existing tour, easily traceable in the database. - -New in Joomla 5 as well is the creation of 2 separate language files. One for the tour and one for the steps of the tour. - - -### The identifier - -This is a unique string, very much like an alias for an article. -The string should be formatted as: - -``` -authorname-tourname -companyname-tourname -domain-tourname -``` - -For instance, a welcome tour created by Joomla would have an identifier name `joomla-welcome`. -authorname, companyname, domain name should be one single word, tourname can contain dashes. - -As long as the tour you create includes your 'signature' and is unique in your pool of tours, there will be no duplication issue for users. - -The identifier corresponds to the `uid` column of the `#__guidedtour` table. -On save or duplicate, a suggested identifier string is created. - - -### The language files - -Not all tours need language files, especially if you are only targetting a one-language audience. -But if you do need them, the files need to follow the new convention didacted by the identifier. - -For instance, for the tour with identifier `joomla-welcome`, the language files will be: - -``` -guidedtours.joomla_welcome.ini -guidedtours.joomla_welcome_steps.ini -``` - -where the first file only contains 2 keys, one for the tour name and one for its description and the second file contains all step keys. - -All language files need to start with 'extensionname', 'com_extensionname', 'mod_modulename', 'plg_[group]_pluginname' or 'tpl_templatename', end with `.ini` or `_steps.ini`. - -Reminder: the language keys can be anything BUT need to contain GUIDEDTOUR in the key. This is to allow the tour and step views to properly distinguish what is a language key and what is just regular content. - -Language files do not need to be placed into administrator/language/[language]/. You can leave the files inside the extension's file structure. - - -### The tour context - -A `Component selector` parameter has been available ever since tours have been introduced in Joomla. -The definition of 'component selector' slightly differs in Joomla 5. -Now, on any given page where the module 'Take a tour' is showing, the tours being in the context of the page are the ones showing in priority. - -Selecting a component will ensure the tour will be tagged as 'favorite' when in the component's views. 'All' will show the tour in priority in all pages. Leaving the selection to 'All' is not recommended. As a third party developer, you would select the extension(s) the tour is tied to. - -For instance, the 'How to create articles' tour will be visible in priority when in an 'Articles', 'Featured articles' or 'Categories' views. -To allow that, the tour's component selector is set to 'Articles' and 'Categories'. - -Note that the Guided Tour component knows how to differentiate category tours for specific components. For instance, if you create a categories tour for com_contact, the category tour for articles won't show as a favorite tour when in 'Contact' context. - -There is no available tour when editing a specific module, plugin or template. That is where launching a tour from anywhere can become handy. - - -### 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. - - -### Event dispatchers - -Once a user cancels, opts-out or completes a tour, events are triggered, allowing developers to act according to user actions. One may want to send a message to a user after completion of a tour in order to propose another one, for instance. -Those events are triggered at different stages: -- onBeforeTourSaveUserState: before saving the auto-start tour user state (used to record states in the User Action Logs), -- onAfterTourSaveUserState: after saving the auto-start tour user state. - -You can find those events in the AjaxController class. - - -### Adding images to the content - -Use the editor to include images inside the content descriptions. Images are located in the media folder, ```/images``` by default. -However, expecially when creating a tour for a third party extension, you may want to include images located in the media folder of the extension. -In this case, the image path must start with ```media/...```. - - -## Launching a tour from any location - -Launching a tour from a different location than the Guided Tours module is as easy as adding the attribute `data-gt-uid` with the identifier of the tour. - -As an example, create a custom module in the cpanel dashboard and add this HTML to it: - -``` - - -``` From 6a79bc6ccd6c732ff88538a1812ca2e0093623bb Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Sun, 26 Jan 2025 12:27:40 -0500 Subject: [PATCH 06/16] Linked the toolkit page --- docs/general-concepts/guided-tours/create-whatsnewtour.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index a2f55165..f227dfdb 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -60,7 +60,7 @@ right ## Step 3: Install the Guided Tours toolkit -The toolkit can be found at ``https://github.com/joomla-extensions/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 From ee0318b46e0ca95b6d8d855e05d61b942b8774a8 Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Sun, 26 Jan 2025 12:47:22 -0500 Subject: [PATCH 07/16] Update create-whatsnewtour.md --- docs/general-concepts/guided-tours/create-whatsnewtour.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index f227dfdb..bb7fa000 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -66,7 +66,7 @@ The toolkit can be found at [the toolkit extension GitHub page](https://github.c 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. +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: Create the PR @@ -165,3 +165,8 @@ 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. + +## 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). From 58370395bb2ac63e60dcdcf5184a79530e0c8189 Mon Sep 17 00:00:00 2001 From: Harald Leithner Date: Mon, 10 Feb 2025 10:27:45 +0100 Subject: [PATCH 08/16] Updated syntax --- .../guided-tours/create-whatsnewtour.md | 68 +++++++++---------- 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index bb7fa000..36e1d43d 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -1,3 +1,8 @@ +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. @@ -10,23 +15,14 @@ For instance, X_Y is 5_3 if you create a PR for the what's new tour for version Enter the following parameters: -`title` -What’s New in Joomla X.Y! - -`identifier` -joomla-whatsnew-X-Y - -`component selector` -Home dashboard +**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:** -`autostart` -yes - -`relative url` -administrator/index.php - -`description` -``` +```html

Welcome to Joomla X.Y!

``` @@ -40,17 +36,12 @@ 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 +**Title:** More Information and Help +**Position:** right +**Target:** `#sidebarmenu nav > ul:first-of-type > li:last-child` +**Description:** -`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

@@ -129,8 +120,9 @@ BEFORE those statements, include: On a major release (for instance 5.0), add the statements to remove ALL prior what's new tours: -MySQL: -``` + + +```sql -- uninstall previous tours DELETE FROM `#__guidedtour_steps` WHERE `tour_id` IN (SELECT `id` FROM `#__guidedtours` WHERE `uid` LIKE 'joomla-whatsnew-%'); @@ -138,9 +130,9 @@ DELETE FROM `#__guidedtour_steps` DELETE FROM `#__guidedtours` WHERE `uid` LIKE 'joomla-whatsnew-%'; ``` - -PostgreSQL: -``` + + +```sql -- uninstall previous tours DELETE FROM "#__guidedtour_steps" WHERE "tour_id" IN (SELECT "id" FROM "#__guidedtours" WHERE "uid" LIKE 'joomla-whatsnew-%'); @@ -148,20 +140,26 @@ DELETE FROM "#__guidedtour_steps" 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: -MySQL: -``` + + +```sql -- disable autostart for the previous tour UPDATE `#__guidedtours` SET `autostart` = 0 WHERE `uid` = 'joomla-whatsnew-X-YY'; ``` + + -PostgreSQL: -``` +```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. From bf25d9241d6878b3e24d359bcd1ba535ef0ea74d Mon Sep 17 00:00:00 2001 From: Harald Leithner Date: Mon, 10 Feb 2025 10:31:27 +0100 Subject: [PATCH 09/16] Removed version reference and update some syntax --- docs/general-concepts/guided-tours/create-whatsnewtour.md | 8 +++++--- docs/general-concepts/guided-tours/creating-tours.md | 4 ++-- docs/general-concepts/guided-tours/index.md | 2 +- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index 36e1d43d..ba159e67 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -7,9 +7,11 @@ In the following documentation, we explain how a `What's New tour` can be create What's New tours are available in major and minor Joomla releases, only for users who update. -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. +:::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 diff --git a/docs/general-concepts/guided-tours/creating-tours.md b/docs/general-concepts/guided-tours/creating-tours.md index 41b6c61e..f3415a2b 100644 --- a/docs/general-concepts/guided-tours/creating-tours.md +++ b/docs/general-concepts/guided-tours/creating-tours.md @@ -4,7 +4,7 @@ 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, @@ -74,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 index 4f7c53a2..6f13631a 100644 --- a/docs/general-concepts/guided-tours/index.md +++ b/docs/general-concepts/guided-tours/index.md @@ -1,4 +1,4 @@ --- title: Guided Tours --- -This section describes the concept of Tours, which were introduced in Joomla! 4.3. +This section describes the concept of Tours. From e8ae33a33dd7c2df2997c4f54518eb753da75b4d Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Wed, 12 Feb 2025 17:12:19 -0500 Subject: [PATCH 10/16] Improvements --- .../guided-tours/create-whatsnewtour.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index ba159e67..bf69f2f1 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -92,7 +92,9 @@ 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. -### Create files +### Create the language files + +Go to the administrator/language/en-GB folder. ``` administrator/language/en-GB/guidedtours.joomla_whatsnew_X_Y.ini @@ -101,7 +103,7 @@ administrator/language/en-GB/guidedtours.joomla_whatsnew_X_Y_steps.ini and fill with the generated language keys. -### Create media files +### Create the media files If there are images, add them to @@ -109,7 +111,9 @@ If there are images, add them to build/media_source/com_guidedtours/images/X_Y ``` -### Create files +### Create the 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 From 7327a7fb3db88af2de59fe8c288e0d23dc11d6ea Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Wed, 12 Feb 2025 17:16:44 -0500 Subject: [PATCH 11/16] Re-order the paragraphs --- .../guided-tours/create-whatsnewtour.md | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index bf69f2f1..3d855d89 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -62,37 +62,12 @@ 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: Create the PR +## Step 5: How to create the PR -Open the generated file. -Create a PR in a branch you have created from the forked Joomla repository. +Open the generated texte file. +Create a branch from the forked Joomla repository under your account. -### 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. - -### Create the language files +### Create language files Go to the administrator/language/en-GB folder. @@ -103,7 +78,7 @@ administrator/language/en-GB/guidedtours.joomla_whatsnew_X_Y_steps.ini and fill with the generated language keys. -### Create the media files +### Create media file(s) If there are images, add them to @@ -111,7 +86,7 @@ If there are images, add them to build/media_source/com_guidedtours/images/X_Y ``` -### Create the SQL files +### Create SQL files Go to the administrator/components/com_admin/sql/updates. @@ -170,6 +145,31 @@ 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. +### 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. From 9342683aeb88fd872a765db0ded6bfe69fbca4b4 Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Wed, 12 Feb 2025 17:31:50 -0500 Subject: [PATCH 12/16] Image information --- docs/general-concepts/guided-tours/create-whatsnewtour.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index 3d855d89..92431a51 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -86,6 +86,9 @@ 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. From 6ce204c89866ab7f08c3a99b3f3c4cb0b18b2218 Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Wed, 12 Feb 2025 17:38:19 -0500 Subject: [PATCH 13/16] Add steps for PR creation --- docs/general-concepts/guided-tours/create-whatsnewtour.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index 92431a51..4036dda9 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -148,6 +148,14 @@ 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: ``` From 9c4a05e9c4bda184d42c389bdff2fd48a89d4aaf Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Wed, 12 Feb 2025 17:40:13 -0500 Subject: [PATCH 14/16] Branch note --- docs/general-concepts/guided-tours/create-whatsnewtour.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index 4036dda9..3586480c 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -65,7 +65,7 @@ The file can be found in your browser's download folder. ## Step 5: How to create the PR Open the generated texte file. -Create a branch from the forked Joomla repository under your account. +Create a branch based on the Joomla/X.Y-dev from the forked Joomla repository under your account. ### Create language files From 508ad144800ccc1e5b9c06941508a5e7f19014a7 Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Wed, 12 Feb 2025 17:41:10 -0500 Subject: [PATCH 15/16] Typo --- docs/general-concepts/guided-tours/create-whatsnewtour.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index 3586480c..1b14e435 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -64,7 +64,7 @@ The file can be found in your browser's download folder. ## Step 5: How to create the PR -Open the generated texte file. +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 From 697a933eb36861f684f5a88936cfd28fb7198463 Mon Sep 17 00:00:00 2001 From: Olivier Buisard Date: Wed, 12 Feb 2025 17:44:47 -0500 Subject: [PATCH 16/16] Typos --- docs/general-concepts/guided-tours/create-whatsnewtour.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/general-concepts/guided-tours/create-whatsnewtour.md b/docs/general-concepts/guided-tours/create-whatsnewtour.md index 1b14e435..215ce08e 100644 --- a/docs/general-concepts/guided-tours/create-whatsnewtour.md +++ b/docs/general-concepts/guided-tours/create-whatsnewtour.md @@ -135,9 +135,8 @@ On a minor release (for instance 5.3), set the previous What's New tour to NOT a -- 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';