Module: AdminHelp

[Macrura]

This is updated/version of the AdminDocsTab module as was posted here: https://processwire.com/talk/topic/11803-admindocstab/

(that one is now obsolete)

https://github.com/outflux3/AdminHelp

AdminHelp module for ProcessWire

Processwire helper modules for managing site documentation.

Currently alpha state - please use with caution and report all errors.

Instructions

There are 3 modules included with this: the master module holds the settings for the other 2.

This is a helper module which expects you to have already setup a hidden part of your page tree* to establish your help documentation, using any template (e.g. 'help-doc') and a body field (ckeditor) (*or you can run the setup and it will create these items).

The help-doc template does not need to have an output template, as the module will only echo the body field inside the admin.

In addition this 'help-doc' template requires "template select" field (separate module) which should be named template_select. (if you run setup it will create this).

To have a global help page, which renders all of the help docs in an accordion view, you can install the ProcessAdminHelp module, which will setup a page to view the help docs, under setup.

Help Setup Module (AdminHelp)

This is how the setup module looks before setup is completed:

If you use the automated setup, it will create the field, templates and pages, and will auto-set the module configuration:

Example Help Tab (when using AdminHelpTab)

Admin Help page (ProcessAdminHelp)

This shows all help docs in accordion.

(it is capable of displaying child pages also but this is not currently implemented in the module due to the family settings of the default templates).

Accordion opened:

Features Summary:

1. Manages settings for the help templates (help-index, and help-doc), which enabled users to add new help docs where applicable; these can already exist and be named whatever, you just specify them in the setting.
2. Getting the help/docs tab to show up in the right place (based on user preference template selected on the help doc).
3. Has it's own scoped CSS styling that makes the documentation readable and engaging;
   has some @import fonts, and also rules to make text layout look correct in PW admin (paragraphs, lists, headings, blockquotes etc.)
4. Makes it easy for site editors to add their notes, mods/edits/enhancements to the docs (edit button - currently only enabled for Superadmin - this can be made a setting based on user feedback).
5. Using the secondary process module will create a 'Help Docs' page under Setup where you can view all of the docs in 1 place as an accordion. (could be moved somewhere else)
6. There is also an automated setup that can run, where it will create the field, templates, and pages for you to get started.
7. This module is probably optimized to handle no more than 10-15 or so help pages; if you needed more than that, the Process module may need to be changed to work differently. Most sites I do need around 4-5 help pages.

*If you don't want to load those extra google fonts in your admin you can modify the CSS to your needs, e.g. remove the @import and then change the few lines of css that reference those;

Once there have been a few testers, I can see about adding this to the modules directory in a week or so.

[SteveB]

What am I missing? I'm unable to change the formatting. Thought that was handled by module's ___execute function but I keep getting the same layout.

[Macrura]

do you mean the help tab, or the process page, that shows all of the help docs?

[SteveB]

I meant the render from the help tab. Hmmm.

[Macrura]

could you post a screenshot ? does the lightbox option work? i can test again, maybe i broke something on the last update...

[SteveB]

It looks fine, I just don't understand where the markup for the individual help pages comes from. The auto setup creates templates that have no template file.

[Macrura]

Right, they are just body fields rendered in the accordion; you would setup the help root and then the help pages themselves, and then select which templates to show on;

all markup for the help page itself would be done in the ckeditor

[SteveB]

I have a ckeditor field I'd re-use for this and my "body" field was going to be a plain text field, though I don't have to do it that way. When does the accordion markup get made anyway? I tried putting something like die('Yikes') in ProcessAdminHelp  ___execute() but it had no impact. I'm still a bit murky on the life cycle of process module pages.

[Macrura]

the process admin help does not interact with the help tabs; the process module only gives you like a global page where all of the help docs are in 1 long accordion.

the help tab on the page editor is rendered in the help tab module, so it does a selector to see if there are any matching help docs based on the template select and then I think it uses a hardcoded body field, so in terms of that, i would probably need to implement a setting to allow users to select which field will contain the markup...

i will check it out and get back

[SteveB]

Got it! Markup comes from AdminHelpTab->hookBuildForm() or ProcessAdminHelp->___execute() depending on where you're looking at the content.

I made a couple small changes to use a different field and also to disallow editing from the help tab display, except for superuser.

[Macrura]

cool, glad it's working out; i just added table css, from uikit to the scoped css; not sure how needed it is, but i just started using tables in my documentation and saw there was no styling;
 

/* ========================================================================
   Component: Table
 ========================================================================== */
/*
 * 1. Remove most spacing between table cells.
 * 2. Block element behavior
 * 3. Style
 */
.help-doc table {
  /* 1 */
  border-collapse: collapse;
  border-spacing: 0;
  /* 2 */
  width: 100%;
  /* 3 */
  margin-bottom: 15px;
}
/*
 * Add margin if adjacent element
 */
* + .help-doc table {
  margin-top: 15px;
}
.help-doc table th,
.help-doc table td {
  padding: 8px 8px;
  border-bottom: 1px solid #dddddd;
}
/*
 * Set alignment
 */
.help-doc table th {
  text-align: left;
}
.help-doc table td {
  vertical-align: top;
}
.help-doc table thead th {
  vertical-align: bottom;
}
/*
 * Caption and footer
 */
.help-doc table caption,
.help-doc table tfoot {
  font-size: 12px;
  font-style: italic;
}
.help-doc table caption {
  text-align: left;
  color: #999999;
}
/*
 * Active State
 */
.help-doc table tbody tr.uk-active {
  background: #f0f0f0;
}
/* Sub-modifier: `uk-table-middle`
 ========================================================================== */
.help-doc table-middle,
.help-doc table-middle td {
  vertical-align: middle !important;
}
/* Modifier: `uk-table-striped`
 ========================================================================== */
.help-doc table-striped tbody tr:nth-of-type(odd) {
  background: #fafafa;
}
/* Modifier: `uk-table-condensed`
 ========================================================================== */
.help-doc table-condensed td {
  padding: 4px 8px;
}
/* Modifier: `uk-table-hover`
 ========================================================================== */
.help-doc table-hover tbody tr:hover {
  background: #f0f0f0;
}

** i'll be adding the table styles to the next update

[justb3a]

First I want to thank you for this module 

I missed only one little thing and therefore I sent you a pull request.

I added a litte script which adds a hash to the url when clicking an item. On the other hand, if you enter such an url, the related item will be expanded and the page scrolls to this position. This way it is possible to send an url to an editor without having to say, open this link and after that click on the third headline.

https://www.domain.com/processwire/setup/admin-help/#foo

[Macrura]

@justb3a - thanks, and i accepted the pull req and i'll up the version and add the table css tomorrow...

[bernhard]

hi @Macrura

thank you for your efforts on this. it's similar to what i was up to do on my own. do you think it would be possible and not too much effort to have doc-pages available via urlsegments?

the problem with the # tags is, that it does not work in panels. or at least i don't know how  it would be nice to be able to link to the docs via links like this:

<a href="/admin/setup/admin-help/myhelptopic?modal=panel" class="pw-panel">help for myhelptopic</a>

 

[Macrura]

@bernhard - sure, let me know what context this applies to - for example if you are viewing the help tab, or help modal on the page editor, or showing the help topic in the process module? I haven't worked with panels yet, so if you have any further details on how and when that comes into play, let me know how to replicate the issue etc..

[bernhard]

I read my post again.. Sorry for being too short and unclear.

My situation is that I want to place some links to the docs in several places of my custom process modules (eg in field descriptions or the like). That means I don't have the page editor and thus no help tab. I can easily link to the docs process page but then all help sites are visible. That's not what I want.

I want to link directly to ONE help topic. Bea's solution with the anchor tags does not work in modals because the modal does not open the link at the intended position. And it would be better to have only the intended topic visible in this case in my opinion.

I hope you understand what I mean now?

[Macrura]

yes, thanks for the clarification - ultimately this module should be improved to allow for showing help topics on their own pages, and a better help overview page where the contents are all listed under categories...  i probably can't work on that till July, but i do expect at some point to make this module better and as you say link to specific help topics..

for now though you can use the hash feature that was coded by @justb3a :

 

[bernhard]

thank you macrura but the hash feature is not working in panels as i stated above

anyhow - one click more than needed is ok for my client. thats nothing with priority so far. just wanted to throw in this idea and i'm happy if this finds it's way into this module. if not sooner, than later. totally fine for me  i'm sure it would not be a big addition t

edit: added a PR (quickfix) on github to support query strings like /?docs=my-single-docs-page taking the pagename of the docs page as parameter

[Macrura]

cool, ok thanks – will accept/merge asap.

[Macrura]

Updates have been made to this module that hopefully help usage:

• better CSS styling, improved styling of lists
• config options added for Help Tab
  • Tab Title
  • Tab Color
  • Tab Icon, or no icon
  • Modal width in px, or if not set, full width
  • Better overall Admin Theme support, incl. AdminThemeUiKit
• Instructions added to main module screen to prevent confusion
• Retain ability to run setup again if FieldtypeTemplates is installed after first run

[mel47]

Hello,

Thanks for your module, it does exactly what I wanted without complication. However, have 1 question/suggestion.

Since I will not be the one that will fill the documentation, I gave permissions to modify help-doc to my admin users. It works well, if they created the page from the tree hierarchy. However from admin menu, the "create doc" button and "edit" link will not appear. Looking to your code, only superuser will saw those. 

Could I override ride this without modifying directly in code? I guess adding a permission "admin-helper" could solve this?

Thanks

Mel

PS For now I commented lines 91, 108, 127 in ProcessAdminHelp.module and solved my problem but I guess it's not the better way... ?

[Macrura]

@mel47

right, there are some shortcomings to the module; it is sort of a construction kit module, and those lines were put in and sometimes i do comment those on some sites, i was too lazy to setup permissions or config settings for that stuff; This module probably needs some work, bit i may not be able to get to it for some weeks or months.

In the meantime, I tried to come up with a better system for managing documentation that could be usable on a much larger scale, and it is somewhat backwards compatible with this one, in the sense that the ProcessDocumentation gives you a lot more options; It doesn't do the accordion view; but it does have granular permissions for the help docs, and supports PDF export for any document, which is very helpful in the case that there is long documentation and the user wants to read it offline.

 

[MarkE]

Hi @Macrura. I just found this module and it looks very much like what I was going to do from scratch for my current development - i.e. have a help file for each template but also as part of a general help page. I installed it and made a minor mod - to allow help-index pages to have help-index children (plus a body field). This works nicely in the accordion as a hierarchical drop-down.

However, it seems like the module is no longer supported and you are suggesting ProcessDocumentation instead. I also note that there seems to be another module - ContextHelpTemplate - that is more up-to-date than AdminHelpTab in allowing more options for display.

So I am a bit confused. What do you recommend for my help pages (it would be nice to use pw-panel)?

[Macrura]

@MarkE - should be ok to use this, and i wouldn't say that this module is no longer supported, if there were to be a bug report, pull request, or feature request, this module is still live and functioning, and may receive future updates, especially with regards to permissions and flexibility of use.

But in the meantime as mentioned above, ProcessDocumentation is a bit of a larger scale module and was designed so that it would be possible to have unlimited documentation pages, all accessible from the top admin menu, as well as the ability to download the PDF; In conjunction with the ContextHelpTemplate, you can achieve the same functionality ad Admin Help, so that you have a tab for help right on the page editor, which can open in the panel (instead of wiretab) if preferred. So in that sense, ProcessDocumentation is an evolution of this module, but doesn't necessarily replace it for simpler use cases. It is also possible that this module, AdminHelp could use updates to support pw panel, or other features of ProcessDocumentation.

[MarkE]

Thanks. I've hacked my copy as follows:

1. To allow use of Hanna codes in the body
2. To add a pop-out button next to the edit button in the tab

Let me know if you are interested in incorporating these very simple changes.

Also, as I said earlier, I changed the help-index template to allow recursion.

P.S. I might look at re-styling the accordion, which occupies a lot of screen real-estate.