I've written some help documentation for a plugin I've developed. I noticed that MyBB has a builtin-in system for help documentation, accessible via misc.php?action=help. I'd like to leverage that system if possible, because it seems most user-friendly.
It looks as though translatable help sections/pages can be enabled by setting to one the usetranslation column of either mybb_helpsections or mybb_helpdocs, and then adding the translations to language files, as, for example, "d{$hid}_name" or "s{$sid}_name", where $hid is the primary key of the mybb_helpdocsdatabase table, and $sid is the primary key of the mybb_helpsections database table.
So far so good. The problem I'm having is this: the primary keys of the mybb_helpdocs and mybb_helpsections database tables, hid and sid respectively, are autoincrement fields, so if I add a row to one of those tables, there's no guarantee that its hid/sid column will be the same on one person's MyBB installation versus another's, because some other plugin could have inserted one or more rows first. This means that I can't rely on a stable {$hid} or {$sid} when adding translations to my language files.
Is this a known issue/feature, and, regardless, is there any way around it?
How do plugins usually handle help documentation?
Thanks in advance for any advice that you guys have.
Anybody?
Maybe this system of help documentation is designed for core only, and is not meant to be extensible by plugins?
You might want to take a look at MyAlerts, which IIRC is the only plugin I have seen that integrates something of this sort.
I personally would instead simple add my document to the listing by hooking at misc_help_section_end and the n at misc_start to parse my page.
I'm sure it could be better, but I think the system should be somehow improved for plugin usage.
Thanks, Omar G., I'll check out MyAlerts and the hooks you suggest.
@Omar G., I've not been able to find anything help-related in MyAlerts. Can you please give me a pointer as to where specifically to look in its code?
The hooks you suggest do seem workable, although doing it via those hooks rather than database entries means that my help pages wouldn't be searchable with the standard help search functionality. Perhaps, though, that could be remedied by additionally hooking in to misc_do_helpsearch_end. Messy, but it would probably get the job done.
Re plugin-friendly improvements, perhaps both helpdocs and helpsections could be keyed by strings, as for templates, which would make it easier for plugins to avoid duplicate entries.
Another concern I have, although I haven't tested or even looked especially carefully at the code to confirm this, is that search functionality currently doesn't work for translated helpdocs/helpsections, since (although I base this only on a cursory visual inspection) it queries the DB only, and doesn't search within those language strings which are used for the translations.
There is a helpdocs table in the database that stores the help documents. All you would need to do is add a record for a new page into this table (and subsequently remove it upon deactivation).
Not sure how MyAlerts does it, there may be other methods for it. But this might be something worth looking into.
(2020-05-02, 01:49 PM)Darth Apple Wrote: [ -> ]There is a helpdocs table in the database that stores the help documents. All you would need to do is add a record for a new page into this table (and subsequently remove it upon deactivation).
Yes, quite - and I referenced that table in my opening post. Perhaps I ought to have contextualised my problem better: I wish for my help pages to be
translatable, and my opening post explains why that does not seem to be possible
for a plugin using the core help system and the database table you mention.
Hi, maybe we could add a new column for string identifiers? If empty (for default docs) then the system should fallback to searching based on the INT identifier (current) (I'm thinking on compatibility, if major changes are done then perhaps just stick to one type of identifier).
Quote:*Recommendation #1*: Dispense with help text in language files and store help sections/documents solely in the database.
I won't be sure about this, as it would cause inconsistency with the current language system (which relies to files, never to DB).
If you wanted to offer translated posts I would agree, but help documents are as of now managed by administrators only, used in such a way that frequent edit is unlikely to be expected.
Perhaps language files should be the default fallback, editable only from the edit language module of the ACP (current), while allowing admins to attach "custom doc translations" which are saved into the DB and used only if present for the current user language. For this the
Document form field would need to be removed and expanded with a new "add custom translation" module, perhaps replaced with some information regarding the language file it is pulling data from (informative in case admins want to edit language files instead of creating custom translations).
(In this case if no custom DB doc nor language file exists, the default fatal error for missing lang files should be used.)
On thing I would agree, the
language help doc system is broken, so much IMO that a revamp is justified if necessary. My personal vision of the Help Docs module would be something in the direction (if not as complex but extendable) as my OUGC Pages plugin.
I would suggest to work on it for 1.9 instead of 1.8 too.
(2021-03-12, 11:07 PM)Omar G. Wrote: [ -> ]Hi, maybe we could add a new column for string identifiers?
I think that's a very good idea. It is essentially my recommendation #2 (in the document linked to below).
(2021-03-12, 11:07 PM)Omar G. Wrote: [ -> ]If empty (for default docs) then the system should fallback to searching based on the INT identifier (current) (I'm thinking on compatibility, if major changes are done then perhaps just stick to one type of identifier).
I think major changes are necessary, so we should stick with string codes rather than (auto-incrementing) integers.
(2021-03-12, 11:07 PM)Omar G. Wrote: [ -> ]Quote:*Recommendation #1*: Dispense with help text in language files and store help sections/documents solely in the database.
A little note for the reader: this quoted recommendation comes from a document which at the time Omar quoted it I'd only shared privately on Discord, but have now made public in the thread
Problems with the Help system and ideas on how to fix them.
(2021-03-12, 11:07 PM)Omar G. Wrote: [ -> ]I won't be sure about this, as it would cause inconsistency with the current language system (which relies to files, never to DB).
"Never to DB" is not quite accurate. Search results for the Help system are pulled from the DB, and if the
usetranslation column is set to 0 (although it never is for Help docs supplied by core), then Help docs themselves (when viewed) are pulled from the DB. It's all a bit of an inconsistent mess, hence why I think a total overhaul is justified.
(2021-03-12, 11:07 PM)Omar G. Wrote: [ -> ]If you wanted to offer translated posts I would agree, but help documents are as of now managed by administrators only, used in such a way that frequent edit is unlikely to be expected.
Perhaps language files should be the default fallback, editable only from the edit language module of the ACP (current), while allowing admins to attach "custom doc translations" which are saved into the DB and used only if present for the current user language. For this the Document form field would need to be removed and expanded with a new "add custom translation" module, perhaps replaced with some information regarding the language file it is pulling data from (informative in case admins want to edit language files instead of creating custom translations).
(In this case if no custom DB doc nor language file exists, the default fatal error for missing lang files should be used.)
Honestly, I think that trying to support and maintain two separate sources of Help data - language files and the DB - is fraught with peril and not a good idea, as the current implementation shows. I think we should pick one or the other, and my preference is for the DB.
(2021-03-12, 11:07 PM)Omar G. Wrote: [ -> ]On thing I would agree, the language system is broken, so much IMO that a revamp is justified if necessary. My personal vision of the Help Docs module would be something in the direction (if not as complex but extendable) as my OUGC Pages plugin.
I would suggest to work on it for 1.9 instead of 1.8 too.
Yes, we're in agreement on all of this.