Jump to content
Macrura

Module: AdminHelp

Recommended Posts

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: help_setup_new.jpg

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

Example Help Tab (when using AdminHelpTab)

help_tab.jpg

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).

help_page_c.jpg

Accordion opened:

help_page_o.jpg

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.

  • Like 15

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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

  • Like 1

Share this post


Link to post
Share on other sites

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

  • Like 1

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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>

 

Share this post


Link to post
Share on other sites

@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..

  • Like 1

Share this post


Link to post
Share on other sites

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? :)

Share this post


Link to post
Share on other sites

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 :

 

  • Like 2

Share this post


Link to post
Share on other sites

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

  • Like 2

Share this post


Link to post
Share on other sites

cool, ok thanks – will accept/merge asap.

  • Like 2

Share this post


Link to post
Share on other sites

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
  • Like 2

Share this post


Link to post
Share on other sites

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... 😉

Share this post


Link to post
Share on other sites

@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.

 

  • Like 2

Share this post


Link to post
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


  • Recently Browsing   0 members

    No registered users viewing this page.

×
×
  • Create New...