Skip to content

[6.2] New backend Joomla! Help page - #46355

Merged
MacJoom merged 38 commits into
joomla:6.2-devfrom
ceford:helptoc
May 25, 2026
Merged

MacJoom merged 38 commits into
joomla:6.2-devfrom
ceford:helptoc

Conversation

@ceford

@ceford ceford commented Oct 23, 2025 •

Copy link
Copy Markdown
Contributor

Pull Request for Issue # .

No issue in the tracker but the problematic list of Help pages has been mentioned in discussions.

Summary of Changes

This PR is for a replacement of the backend list of Help files accessed via Help → Start Here. The current page presents a list of 198 items sorted into alphabet order of the language selected at login. It is very difficult to use! Each time the page is reloaded the displayed item is Start Here. Also, it is generated by a script that fetches all the pages from docs.joomla.org that are categorised as Help5 or Help6 or ... but only in selected languages.

The proposed replacement gives the list of Help pages a similar structure to the Atum side menu. The changes in brief:

  1. The Help page menu source is a handcrafted php array (toc-src.php) in the tmpl folder.
  2. The menu build code has been moved from the Model to the tmpl folder (toc-build.php).
  3. Unused code has been removed from the Model.
  4. Unused code has been removed from the HtmlView.
  5. The unused administrator/help/en-GB/toc.json tree has been deleted.
  6. The now unused build/helpTOC.php has been deleted.
  7. There are additional strings in com_admin.ini
  8. Changes to admin-help.es6.js are significant.
  9. There is styling added in default.php with addInlineStyle() to distinguish the Help menu from the Atum menu.
  10. The last page displayed is recorded in local storage and displayed when the page is reloaded.

There is a potential problem: initialisation of the Help menu requires a delay or it is left inoperative. That needs testing on different platforms.

Testing Instructions

Testing needs a development installation.

  • Apply the patch and use npm run build:js and npm run build:css
  • In the backend visit Help → Start Here / Joomla! Help

Edit: removed instruction to edit configuration.php - the Help proxy has been fixed.

Actual result BEFORE applying this Pull Request

The current long alphabetic list of Help pages is difficult to use.

Expected result AFTER applying this Pull Request

The list of help pages is structured with a Metismenu. Screenshot to follow.

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

@joomla-cms-bot joomla-cms-bot added Language Change This is for Translators NPM Resource Changed This Pull Request can't be tested by Patchtester PR-6.1-dev labels Oct 23, 2025
@brianteeman

Copy link
Copy Markdown
Contributor

Looks good

@brianteeman

Copy link
Copy Markdown
Contributor

When the menu item wraps to two lines I find the center alignment visually awkward but that might just be me

image

@richard67 richard67 changed the title New backend Joomla! Help page [6.1] New backend Joomla! Help page Oct 23, 2025
@ceford

ceford commented Oct 23, 2025

Copy link
Copy Markdown
Contributor Author

It works but I am having second thoughts about how I have coded this feature. Perhaps it should be considered a draft for now. I will get on to the points raised by @brianteeman - thank you. Meanwhile, here is a screenshot:

image

@ceford

ceford commented Oct 23, 2025

Copy link
Copy Markdown
Contributor Author

@brianteeman Should I make the copyright 2026 on the assumption it will be next year before it appears?

@brianteeman

Copy link
Copy Markdown
Contributor

@brianteeman Should I make the copyright 2026 on the assumption it will be next year before it appears?

no - you wrote it in 2025 and it will hopefully be merged on github in 2025

@C-Lodder

C-Lodder commented Oct 24, 2025 •

Copy link
Copy Markdown
Member

You could remove the need for the wait() delays if you wanted to.
Will leave this code here incase you want to use it.

document.addEventListener("DOMContentLoaded", function (event) {
  new MetisMenu('#helpmenu', {
    toggle: true
  });

  const helpIndex = document.getElementById('helpmenu');
  if (helpIndex) {
    helpIndex.querySelectorAll('a:not(.has-arrow)').forEach(element => element.addEventListener('click', () => {
      window.scroll(0, 0);
      // Save clicked link data-id
      const id = element.dataset.id;
      if (id) {
        localStorage.setItem('helpIndex.lastClick', id);
      }
    }));
  }

  // Async restore function
  function restoreMenu() {
    let lastClick = localStorage.getItem('helpIndex.lastClick');
    if (!lastClick) {
      lastClick = 'start-here';
    }

    const selectedLink = helpIndex.querySelector(`a[data-id="${lastClick}"]`);
    if (!selectedLink) return;

    // Collect parent list items top-down
    const lists = [];
    let parentLi = selectedLink.closest('li');
    while (parentLi && parentLi !== helpIndex) {
      const parentUl = parentLi.parentElement;
      const parentLiOfUl = parentUl.closest('li');
      if (parentLiOfUl) {
        const li = parentLiOfUl
        if (li) lists.unshift(li);
      }
      parentLi = parentLiOfUl;
    }

    // Trigger clicks in sequence with a delay
    for (const li of lists) {
      li.classList.add('mm-active');
      li.querySelector('ul').classList.add('mm-show');
      li.querySelector('a').setAttribute('aria-expanded', true);
    }

    // Optional: highlight selected link
    selectedLink.classList.add('active');

    // Ensure it's visible and then "click" it
    //selectedLink.scrollIntoView({ behavior: 'smooth', block: 'start' });

    // Give the submenu a moment to fully render before clicking
    selectedLink.click();
  }

  // Run restore after MetisMenu setup delay
  restoreMenu()
});

@ceford

ceford commented Oct 24, 2025

Copy link
Copy Markdown
Contributor Author

@C-Lodder only just seen your suggestion - I will give it a try.

@ceford

ceford commented Oct 24, 2025

Copy link
Copy Markdown
Contributor Author

@C-Lodder I implemented you suggestion. Next problem: In narrow screens the Help menu starts open and it takes two clicks to close it. I want it to start with the Help menu closed. Also, in narrow screen mode I want the Help menu to close after selecting an item. I am looking in to how to do this - do you have any suggestions?

@ceford

ceford commented Oct 24, 2025

Copy link
Copy Markdown
Contributor Author

I am happy! This PR is ready for testing.

@richard67

Copy link
Copy Markdown
Member

@ceford What about these 2 unresolved review comments by @brianteeman ?

If they are resolved, please use the button below the comment on GitHub to mark it as resolved.

With the other 2 about the copyright year I've just done that.

Thanks in advance.

@ceford

ceford commented Oct 24, 2025

Copy link
Copy Markdown
Contributor Author

@ceford What about these 2 unresolved review comments by @brianteeman ?

* [[6.1] New backend Joomla! Help page #46355 (comment)](https://github.com/joomla/joomla-cms/pull/46355#discussion_r2454333605)

* [[6.1] New backend Joomla! Help page #46355 (comment)](https://github.com/joomla/joomla-cms/pull/46355#discussion_r2454339366)

If they are resolved, please use the button below the comment on GitHub to mark it as resolved.

With the other 2 about the copyright year I've just done that.

Thanks in advance.

Done that! As I am a rare contributor I did not realised that I needed to resolve comments. I also addressed the alignment problem mentioned by Brian

@richard67

Copy link
Copy Markdown
Member

@ceford Thanks. It is not necessarily the author of a PR who has to resolve review comments, it can also be done by the initial reviewer or by a maintainer. But at the end it is good to have them resolved, otherwise GitHub shows a message about unresolved comments which might discourage testers because they might think there will be more changes coming.

@ceford

ceford commented Oct 24, 2025

Copy link
Copy Markdown
Contributor Author

There is a snag! The rebase to 6.1 has led to the proxy returning 404 not found pages. For test purposes you can edit configuration.php and set the minor version to 0

public $helpurl = 'https://help.joomla.org/proxy?keyref=Help{major}0:{keyref}&lang={langcode}';

@brianteeman

Copy link
Copy Markdown
Contributor

@richard67 as this pr removes the only file in the folder help/en-gb it will result in the packages being created without that folder at all. If the folder is needed for b/c etc then an index.html should be placed in the folder to ensure it is included in packages

@richard67

Copy link
Copy Markdown
Member

@richard67 as this pr removes the only file in the folder help/en-gb it will result in the packages being created without that folder at all. If the folder is needed for b/c etc then an index.html should be placed in the folder to ensure it is included in packages

@brianteeman I have no idea if that folder is needed for b/c and if so, if it is needed in a new install of the core, too, or only should be kept on updates.

@ceford Do you have an idea if that cold be needed e.g. for 3rd party extensions?

@brianteeman

Copy link
Copy Markdown
Contributor

if it is not needed then entire folder tree can be removed

@ceford

ceford commented Oct 25, 2025

Copy link
Copy Markdown
Contributor Author

if it is not needed then entire folder tree can be removed

Looks like it is used in libraries/Src/Help/Help.php (line 71 ff) so I will create administrator/help/en-GB/index.html

@HLeithner
HLeithner changed the base branch from 6.1-dev to 6.2-dev March 17, 2026 09:13
@HLeithner

Copy link
Copy Markdown
Member

This pull request has been automatically rebased to 6.2-dev.

@github-actions

Copy link
Copy Markdown
Contributor

This pull request has conflicts, please resolve those before we can evaluate the pull request.

@ceford

ceford commented Apr 13, 2026

Copy link
Copy Markdown
Contributor Author

@HLeithner I don't know what this conflicts message means or how to fix it. Can you help?

@richard67

richard67 commented May 25, 2026 •

Copy link
Copy Markdown
Member

@HLeithner I don't know what this conflicts message means or how to fix it. Can you help?

@ceford I'm not Harald, but I can answer your question.

The conflicts happen because after your PR has been successfully rebased to 6.2-dev, another PR #46879 has been merged into 6.2-dev which moves the build/media_source/ folder to media_source/. This includes the modified file build/media_source/com_admin/joomla.asset.json and the added file build/media_source/com_admin/js/admin-help.es6.js from your PR.

Unfortunately this kind of conflict cannot be resolved on GitHub with a button in your PR. It needs to solve it in a development environment.

I will try to do that here and solve it for you.

Update: Just done. It was just a clean merge of the 6.2-dev branch into the branch of this PR, which did not have any conflicts. Just the GitHub UI here cannot do that due to the moved files, but a Git client can.

So I don't think it will need new test. But that's on release managers to decide.

@charvimehradu @MacJoom Do we need new tests here? The rebase to 6.2-dev was clean after the tests, and also my conflict resolution (see above).

@MacJoom MacJoom added this to the Joomla! 6.2.0 milestone May 25, 2026
@MacJoom
MacJoom merged commit 5bc6f2b into joomla:6.2-dev May 25, 2026
128 of 150 checks passed
@joomla-cms-bot joomla-cms-bot removed the RTC This Pull Request is Ready To Commit label May 25, 2026
@MacJoom

MacJoom commented May 25, 2026

Copy link
Copy Markdown
Member

Thank you very much for the hard work!

@QuyTon

QuyTon commented May 30, 2026

Copy link
Copy Markdown
Contributor

@ceford UI issue when collapsing menu.

46355-help-menu

@ceford

ceford commented May 30, 2026

Copy link
Copy Markdown
Contributor Author

This is what the mobile view looked like when submitted:

help-index

How did you take your screenshot?

@QuyTon

QuyTon commented May 30, 2026

Copy link
Copy Markdown
Contributor

On the desktop...click Toggle Menu icon.

@ceford

ceford commented May 30, 2026 •

Copy link
Copy Markdown
Contributor Author

@QuyTon In the PR there is a file named build/media_source/com_admin/css/admin-help.css that has not made it into merge. It adjusts the styles for the Help menu. I don't know what to do about this. Maybe @MacJoom can help?

@richard67

Copy link
Copy Markdown
Member

@QuyTon In the PR there is a file named build/media_source/com_admin/css/admin-help.css that has not made it into merge. It adjusts the styles for the Help menu. I don't know what to do about this. Maybe @MacJoom can help?

build/media_source has been moved to media_source in 6.2-dev.

The subfolders below that are unchanged.

@ceford

ceford commented May 31, 2026

Copy link
Copy Markdown
Contributor Author

Please see PR #47864 for the fix to the missing css file problem.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Feature Language Change This is for Translators NPM Resource Changed This Pull Request can't be tested by Patchtester PR-6.2-dev

Projects

None yet

Development

Successfully merging this pull request may close these issues.