[#45423] - Code to make Help page source user configurable
- Closed
- 2 May 2025
- Medium
- Build: 6.0-dev
- # 45423
- Diff
- ceford:new-toc
User tests: Successful: Unsuccessful:
Pull Request for Issue #45411.
Summary of Changes
The changes here introduce a new method of creating the index of Help pages from the en-GB/com_admin.ini strings. It allows us to use the Joomla 5 Help pages in Joomla 6 and change to a different Help server when a replacement for help.joomla.org emerges.
- Changed the code of the getToc function in HelpModel.php to create toc.json if it does not exist.
- Added field to com_config/forms/application.xml on line 781 to allow user configuration of the help server.
- Replaced help/en-GB/toc.json with a new version.
- Corrected a string in com_admin.ini
- Added strings to com_config.ini
- Deleted file build/helpTOC.php - no longer used.
- Changed the default $helpurl setting in configuration.php-inst
Testing Instructions
Test 1: In an existing J6 Installation:
- Select the Help button in any admin Toolbar - the result is a 404 Not found response from the proxy
- Apply the patch, delete the file help/en-GB/toc.json, in Global Configuration change the helpurl to the new default
- Select the Help button in any admin Toolbar - there is a Hep page
- Go to System -> Help -> Start Here - all the Help pages should work
Test 2: A new installation
This is tricky and advice is welcome! Perhaps get a patch, clone the joomla-cms (not this fork), apply the patch and then follow the instructions for building a working Joomla 6 installation in the README.
Then compare a normal Joomla 6 Installation with the one to which the patch was applied.
- Select any Toolbar Help button.
- In the Admin menu select Help -> Joomla! Help
Actual result BEFORE applying this Pull Request
There are no Help pages in a standard J6 installation because there are no J6 specific web pages.
Expected result AFTER applying this Pull Request
Help pages are available, albeit J5 Help pages. But we are not expecting significant user functionality changes.
Link to documentations
Please select:
Documentation link for docs.joomla.org:
[ x ] No documentation changes for docs.joomla.org needed
Pull Request link for manual.joomla.org:
[ x ] No documentation changes for manual.joomla.org needed
| Status | New | ⇒ | Pending |
joomla-cms-bot
- | Category | ⇒ | Administration com_admin com_config Language & Strings Repository Installation |
| Labels |
Added:
Language Change
PR-6.0-dev
|
||
What is the reason for making the url to the help server user configurable?
Dont you need to change this so that new installs will get the correct url
joomla-cms/installation/src/Application/InstallationApplication.php
Lines 445 to 447 in ab8edd1
how do you plan for new versions of the json to be generated?
Good question, to which I don't have a good answer. toc.json is only used to display the list of Help pages, 200 of them - so who will notice if one is missing? If toc.json is missing it will be rebuilt - so users could delete it to get it rebuilt.
A more significant problem is what happens for users who update from J5 to J6. Their $helpurl in configuration.php will still contain {major}{minor} so there will be no Help pages. Do we tell them to go to Global Configuration and change it to the new default or do we change it in the upgrade script? I don't know!
how do you plan for new versions of the json to be generated?
Good question, to which I don't have a good answer. toc.json is only used to display the list of Help pages, 200 of them - so who will notice if one is missing? If toc.json is missing it will be rebuilt - so users could delete it to get it rebuilt.
A more significant problem is what happens for users who update from J5 to J6. Their $helpurl in configuration.php will still contain {major}{minor} so there will be no Help pages. Do we tell them to go to Global Configuration and change it to the new default or do we change it in the upgrade script? I don't know!
this is why this entire approach is wrong.
from my understanding what you are looking to achieve is to use the 5.0 help pages for 6.0 without updating them.
this should be done on the help server by aliasing the 5.0 pages to 6.0
this would require absolutely zero changes in the cms - your approach is creating a lot of work to produce an unmanageable process which is simply not needed
Actually, the main purpose of the change is to make provision for migrating away from the Wiki completely. Users can easily enough change the $helpurl in configuration.php but the index of Help files is still generated from a Wiki query.
You have drawn my attention to something I had overlooked: there are 86 instances of helpurl in 45 files and 31 of them are hard coded to docs.joomla.org. So perhaps more work than I had bargained for!
Actually, the main purpose of the change is to make provision for migrating away from the Wiki completely. Users can easily enough change the $helpurl in configuration.php but the index of Help files is still generated from a Wiki query.
then you are definitely doing this wrong.
for now all you have to do is to address where the EXISTING help urls resolve to. And that is not something to do in the CMS
when you have an alternative to the wiki then you can look at the best way to build the helptoc
what this PR does will not help anyone at all.
user will not change the $helpurl no matter how easy you think it is.
asking/expecting developers to manually edit the helptoc.json is not a practical solution either
i would probably look at using joomla for the help server and the existing joomla api to build the helptoc and serve the pages but you are not at that stage yet and none of the changes here will help you to achieve that in any way.
this is simply wrong
| Status | Pending | ⇒ | Closed |
| Closed_Date | 0000-00-00 00:00:00 | ⇒ | 2025-05-02 09:49:42 |
| Closed_By | ⇒ | ceford |
Actually, the main purpose of the change is to make provision for migrating away from the Wiki completely. Users can easily enough change the $helpurl in configuration.php but the index of Help files is still generated from a Wiki query.
then you are definitely doing this wrong.
when you have an alternative to the wiki then you can look at the best way to build the helptoc
Thanks for the feedback. You have given me a lot to think about and led me to discover nooks of the CMS I have never visited. All very useful.
how do you plan for new versions of the json to be generated?