[#40645] - [5.0] Guided tours import export functionality
- Closed
- 22 Nov 2023
- Medium
- Build: 5.0-dev
- Draft PR
- # 40645
- Diff
- obuisard:guided-tours-import-export
User tests: Successful: Unsuccessful:
Summary of Changes
This PR introduces missing functionality to the guided tours.
Export/import of tours will be useful for:
- creators of tours who would like to export their work and import it into client's websites,
- third party extension developers who would like to create tours and make them available to their users.
Tours are exported as json files.
Testing Instructions
Apply the patch.
Go to System -> Manage -> Guided Tours.
Actual result BEFORE applying this Pull Request
There is no import/export functionality.
Expected result AFTER applying this Pull Request
You should see import/export buttons IF you have the rights to create tours.
Select a tour to access 'Export'.
The selected tour will be downloaded to the browser's default download folder.
Select 'Import'.
A modal window opens, allowing you to select a file of application/json type.
Select 'Process' to import the file.
Upon success, you should be greeted with a success message.
In case of an error, a proper error message will show.
SAMPLE FILE
{ "tours": [ { "title": "COM_GUIDEDTOURS_TOUR_NEWSFEEDS_TITLE", "description": "COM_GUIDEDTOURS_TOUR_NEWSFEEDS_DESCRIPTION", "extensions": "[\"*\"]", "url": "administrator/index.php?option=com_newsfeeds&view=newsfeeds", "published": 1, "language": "*", "note": "", "access": 1, "steps": [ { "title": "COM_GUIDEDTOURS_TOUR_NEWSFEEDS_STEP_NEW_TITLE", "description": "COM_GUIDEDTOURS_TOUR_NEWSFEEDS_STEP_NEW_DESCRIPTION", "position": "bottom", "target": ".button-new", "type": 2, "interactive_type": 1, "url": "administrator/index.php?option=com_newsfeeds&view=newsfeeds", "published": 1, "language": "*", "note": "" }, { "title": "COM_GUIDEDTOURS_TOUR_CONTACTS_STEP_CONGRATULATIONS_TITLE", "description": "COM_GUIDEDTOURS_TOUR_CONTACTS_STEP_CONGRATULATIONS_DESCRIPTION", "position": "bottom", "target": "", "type": 0, "interactive_type": 1, "url": "administrator/index.php?option=com_contact&view=contact&layout=edit", "published": 1, "language": "*", "note": "" } ] } ] }
DEVELOPERS
A specific function importFromFilePath is present in the Tours controller.
To import a json file, it is as simple as calling, as an example:
$app = Factory::getApplication();
$controller = $app->bootComponent('com_guidedtours')->getMVCFactory()->createController('Tours', 'Administrator', [], $app, $app->getInput());
$result = $controller->importFromFilePath(JPATH_ROOT . '/tmp/tours.json');
if ($result) {
$app->enqueueMessage('Imported tours.json successfully');
}
NOTES
Right now, importing a tour does not 'replace' an existing tour, which can be a problem if a developer packages tours within an extension's installer. It is suggested that tours could be made available as separate downloads and let users decide if/when a tour could be added to their system.
If images are included in tours, the images must be retrieved and packaged separately.
Suggestions are welcome.
Link to documentations
Please select:
-
Documentation link for docs.joomla.org: TBD
-
No documentation changes for docs.joomla.org needed
-
Pull Request link for manual.joomla.org: TBD
-
No documentation changes for manual.joomla.org needed
joomla-cms-bot
- | Category | ⇒ | Administration Language & Strings |
| Status | New | ⇒ | Pending |
| Labels |
Added:
Language Change
PR-5.0-dev
|
||
Thanks Brian @brianteeman for all your suggestions.
Tested the import and while it does import multiple tours it only ever says "Tour imported" and not "x tours imported"
There is no data validation on import :(
Example 1
If you are importing a tour that has a start url for a component that is not present on the site it is imported successfully without error and is published and active - yet it obviously will not work when you try to start it
Example 2
If you are importing a tour that is set to be restricted to a component that is not present on the site it is imported successfully without error and is published and active - yet it obviously will not work when you try to start it. at a minimum if the value in the required extensions field is invalid then there should be some indication
Example 3
If you are importing a tour with an access set to 2 there is no check that the site it is bening imported on has an access level with an id of 2. Results in no access level being shown in the list view and a public access level in the item view
There is no consideration of images in the export/import
Tested the import and while it does import multiple tours it only ever says "Tour imported" and not "x tours imported"
My bad, I have made changes and forgot to update the count. Fixed now.
There is no data validation on import :(
Example 1
If you are importing a tour that has a start url for a component that is not present on the site it is imported successfully without error and is published and active - yet it obviously will not work when you try to start it
Example 2
If you are importing a tour that is set to be restricted to a component that is not present on the site it is imported successfully without error and is published and active - yet it obviously will not work when you try to start it. at a minimum if the value in the required extensions field is invalid then there should be some indication
Example 3
If you are importing a tour with an access set to 2 there is no check that the site it is bening imported on has an access level with an id of 2. Results in no access level being shown in the list view and a public access level in the item view
Great point, I will work on that.
Take a word doc and change its extension to json
Import that file
expected to get some sort of error about the file not being json etc
actually got neutral message "no tour imported"
I think this is the wrong approach. I had assumed that the intention was for this functionality to be used by people to build guides that they can share. The reality is that its not really a practical method for that as imported guides will only work if eother the language strings are available or the guides have been created in the users language,.
I think this is the wrong approach. I had assumed that the intention was for this functionality to be used by people to build guides that they can share.
That is exactly that!
And for developers to provide tours for their extensions.
And for web agencies to create guides for their clients (usually in their client's language).
The reality is that its not really a practical method for that as imported guides will only work if eother the language strings are available or the guides have been created in the users language,.
The developers would need to provide language key translations for the tours like they do for their extensions.
They could also provide a tour per language.
I could see myself providing tours in English and French on my site, for instance, for people to download freely and install the tours corresponding to the languages they need (and add more languages as they become available). It could be packaged (json file + images) and installed like a regular extension.
I created this PR as draft so that we can start talking about it, improve and find the best solution. Because the NEED is there from all the feedback I have gotten since the Guided Tours have been included in Joomla 4.3
Because the NEED is there from all the feedback
3rd PD could flourish in such cases. That was the reason I never implemented the export of Child Templates. Joomla should NOT kill the ecosystem by offering everything in the core.
My 2c
Because the NEED is there from all the feedback
3rd PD could flourish in such cases. That was the reason I never implemented the export of Child Templates. Joomla should NOT kill the ecosystem by offering everything in the core.
My 2c
Funny that you mentioned it. I actually thought about that. Because what is needed (packaging of images...) is really what a 3rd party could provide. However, this feature was discussed for the release of guided tours but could not be part of the initial release, that is why I proposed a solution.
The developers would need to provide language key translations for the tours like they do for their extensions. They could also provide a tour per language.
@obuisard I'm trying to do exactly that however the Guided Tours plugin is not loading the component's .sys language file. I've created PR #40606 to fix that issue.
@obuisard I'm trying to do exactly that however the Guided Tours plugin is not loading the component's .sys language file. I've created PR #40606 to fix that issue.
Thank you Douglas @machadoug!
| Labels |
Added:
Feature
|
||
I have tested this item ✅ successfully on ced05e0
The feature you didn't know you wanted. Really useful.
This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/40645.
This pull request has been automatically rebased to 5.1-dev.
There is no data validation on import :(
Example 1
If you are importing a tour that has a start url for a component that is not present on the site it is imported successfully without error and is published and active - yet it obviously will not work when you try to start it
Example 2
If you are importing a tour that is set to be restricted to a component that is not present on the site it is imported successfully without error and is published and active - yet it obviously will not work when you try to start it. at a minimum if the value in the required extensions field is invalid then there should be some indication
Example 3
If you are importing a tour with an access set to 2 there is no check that the site it is bening imported on has an access level with an id of 2. Results in no access level being shown in the list view and a public access level in the item view
Good point @brianteeman
This pull request has been automatically rebased to 5.1-dev.
Yeah, as I understood it from the last time I did a pull request for a new feature on 5.0-dev, The maintainers explained me quite well the process, and new features for 5.0-dev should be a pull request for the 5.1-dev branch, only bug fixes on 5.0-dev should target 5.0-dev. Thanks @HLeithner and @richard67 to make me aware of the right way to contribute in joomla following correctly the process and the procedure.
Thank you everyone for the feedback.
I am closing this PR now BUT keeping all remarks and improvements in mind.
This functionality will not be offered in the core, but an optional extension will be downloadable from the JED to package tours.
Soon you will be able to check the progress and participate in https://github.com/joomla-extensions/tours-packager.
Thank you all!
| Status | Pending | ⇒ | Closed |
| Closed_Date | 0000-00-00 00:00:00 | ⇒ | 2023-11-22 16:12:34 |
| Closed_By | ⇒ | obuisard |
Personally I think this is a bad idea. I don't see why guided tours being synced across sites are any more/less important than any other services (articles or whatever when you're dev'ing locally and pushing to a public site).
Why are the existing tools we have (i.e. the UI or webservices not good enough for this?)