Rework Help module + begin tests for Setup module
While working on #1353 (closed), I came to the conclusion that it would be easier, and better to just rewrite the Help module entirely. So that's mostly what I've done. All the while keeping an eye at the existing code to get a feel for what functionality was needed.
I've done some changes, though:
- I've moved the English (default language) docs into it's own
en/
subdirectory. This is the same as for the other languages, and makes things easier and more tidy. We no longer need to treat English as a special case. - Support for overriding the location of the document tree root has been dropped. I suspect nobody is using this, but if it's important for someone, please let me know!
- Support for overriding the table of contents (toc) file with a
sitetoc
in the root of the doc directory has been dropped. Again, if this is needed by somebody, please let me know! - Support for the toc file in other formats than html has been dropped. Should be easy to add if somebody needs it, but as the toc files currently in use is in html format, I don't see much value in adding features that will not be used.
- The toc file will have to reside in the language dir it belongs, if it's not found, we will no longer default to the english toc.
-
#include
directives in the help files will now need to be exact. We will no longer try to look in the relevant language dir if it's not found. - We will no longer try to look for the english help topic if it was not found within the currently selected language. If the file does not exist within the language requested, you will get a 404. (I have some plans for a compromise here, but the MR is large enough as it is, so checking if it's acceptable as this for now.)
- When no topic is specified, we now redirect to the
help/about/about
page, instead of just modifying the latest browser history entry. Way cleaner, and does not mess with how the browser is supposed to work.
On the plus side, the functionality that is implemented is covered fairly well with tests. Writing the tests before implementing a specific feature has been a great help in getting things covered without breaking existing functionality.
Also, reloading the page will no longer redirect to help/about/about
, but will stay on where you were.
The original issue
The original issue with #1353 (closed) is the above mentioned rewriting of browser history in the javascript that follows the module. This caused the rewritten URL to be fetched when reloading the page (or linking to it), but as that did not correspond with the underlying file system structure, and the attempt at special handling of English help files didn't really work, the code ended up with a redirect to help/about/about
since the file you were looking at was not found.
This was in part solved by making English another among equal languages, but not quite.
The new code is (I hope) way cleaner, and should be easier to maintain. I've tried to add some comments documenting things as I found them.
What I've done
I've rewritten the major part of the Help module (Zotlabs\Module\Help
). Hopefully making it a bit easier to reason about. The functionality was split into several helper methods instead of trying to keep everything in one method. (I've not touched the search and serving of static files that's in there, I'll deal with that later.)
I've also rewritten the Helpindex widget (Zotlabs\Widget\Helpindex
), reusing some of the work done for the Help module itself. Removed the commented out "hierachical toc" code, as it's been commented out since Aug 2017... probably time to consider it stale.
I've added a trait (Zotlabs\Lib\Traits\HelpHelper
) that is used by both the Help module and the Helpindex widget, and contains the common code that they both need.
The previously overly complex code in include/help.php
that are no longer in use has been removed.
Remaining work
I have not yet started working on the javascript part. From what I can see, it handles language selection, the modification of the browser history, and syncing the highlights in the table of contents with the currently visible part of the help page in view. Not sure how much value any of that has, tbh.
While I think returning a 404 when a page is not found, is the proper way of doing it, it could be useful to provide a message along the lines of "This page as not been translated to yet. You can have a look at the <original page (in English)>." with a link to the English page in the 404 message. We could also link to instructions for help with translations, if we wanted to.
What's broken?
I have no idea, apart from the features not ported over, as listed at the top. I'm sure there's plenty though! Please test, and please let me know if any feature you're relying on is no longer working!