Module Preview: Process Documentation

[Macrura]

Released:

https://modules.processwire.com/modules/process-documentation/

https://github.com/outflux3/ProcessDocumentation

This is a new module that will be released soon - the purpose is to allow you to create help pages in the admin. This differs from the Admin Help module in the approach, and will be kept totally separate.

The Admin Help modules provides the ability to make a help tab on any page edit screen (and optionally make that pop up in a lightbox), as well as a single process page showing all of the help pages in a single accordion.

This module's workflow is different - first you can create your help pages any way you want using any template and any field for the body text.

You can create unlimited admin help pages, using ProcessDocumentation, select the page to display, and then users can click on that in your menu to access the help page. You can create a folder structure by creating a top level menu item using ProcessList, and then various help pages under that parent using ProcessDocumentation.

The module comes with 2 internally used textformatters, one of them adds classes needed to the markup for some elements to allow styling within the content and not conflict with admin theme rules (e.g. ol, ul, blockquote, table etc.).

The other textformatter allows you to implement jQueryUI tabs within your help page, using a simple shortcode/token format. The styling for the jQueryTabs widget matches that of the standard processwire admin theme tabs, so that users will feel familiar with the interface.

Instructions:

1) Install the ProcessDocumentation module. It will also install the 2 textformatters.

You don't need to apply those textformatters to any field, they are just used internally by the module and called in the correct order to make them work.

2) Select the field to use for the content display (e.g. body).

3) Create your content. If you want to use tabs, this is the syntax:

{tab=My First Tab}

Some content

{tab=My 2nd Tab}

Some more content

{/tabs} Make sure to close the tabs or the page will break...

you need 2 or more tabs for it to work.

You can only currently have 1 set of tabs per page.

You should be able to safely use lists and tables.

4) Create the process page under the admin. Select ProcessDocumentation as the process and then select the page to show from the tree.

5) Now you should have the menu item in your menu if you are using Reno it will be on the left, and under a parent if you setup a parent in the tree. Clicking on that will render the help page. This example uses 7 tabs. If you are superuser, you will see the edit process settings. Other users will see the edit content only, which allows them to edit the content of the help doc, make corrections or additions.

If you need to prevent access to any documentation pages by any role, you just add the name of the process page to the permissions and then don't check it for that role. The module has a defined permissionMethod that checks to see if that permission is defined, and then if the user has it. Not defining individual help page permissions means they are visible to anyone with the documentation permission.

There is more work to be done on CSS, and other small details.

[clsource]

Awesome job!.

Seems this could become very handy when making projects for clients.

[szabesz]

Looks great! Thanks in advance for sharing!

Can it be used like a Dashboard? If the module could support "custom php" then would it be possible to generate output based on database queries as well? 

[bernhard]

4 minutes ago, szabesz said:

Can it be used like a Dashboard? If the module could support "custom php" then would it be possible to generate output based on database queries as well? 

that's exactly what process modules do  there's no need to write a processmodule that renders custom php if a processmodule itself already renders custom php.

the key is to use pw's built in inputfields, especially InputfieldMarkup. then you have a consistent UI and all the features that the pw admin offers by default (toggling fields, setting widths, fieldsets, ajax loading etc).

[Macrura]

2 hours ago, szabesz said:

Looks great! Thanks in advance for sharing!

Can it be used like a Dashboard? If the module could support "custom php" then would it be possible to generate output based on database queries as well? 

Yes, it can totally serve as a makeshift dashboard; if you are able to make the markup how you need it within CK editor, then it would work but wouldn't be able to replace the page tree as the landing because usually like in the dashboard module there is code in place to handle that; but as a sub-page dashboard it would work. (alternately maybe you could use a hook in ready.php to set the page as the admin landing page, instead of page tree..

If you need custom PHP, you can just use Hanna Code Textformatter and your options are pretty unlimited; for example you could build a super simple dashboard with some buttons or information using those hanna codes to output the required markup for your dashboard; for simple sites this could be preferable to trying to build a custom dashboard from scratch; the dashboard redux module i use has around 13 fields, a few templates and a lot of page references, as well as requires icon picker, color picker; you could achieve almost the same type of dashboard layout by using some nested hanna codes...

[szabesz]

Thanks for the explanation! I still haven't find the time to go about implementing a dashboard and generally speaking I'm looking for a "versatile" way of doing it right off the bat that is why your module made me think: why not kill two birds with one stone? Bernhard is right saying that I "just need a process module" but why not build upon an already working solution if possible?

[bernhard]

2 hours ago, szabesz said:

but why not build upon an already working solution if possible?

that's exactly what i mean  nothing will work better than process modules

but i get your point. and for simple documentation and text it's for sure easier to type some text into a textarea than writing it into modules. but as soon as it gets to some more complex content i would strongly recommend going with process modules. it's easier than one might think!

but we are getting offtopic. @Macrura thanks for sharing this! its a very welcome and much needed addition  

[Macrura]

I was able to build a decent widget based dashboard using only this module and some hanna codes; And using @Robin S's hanna code dialog, i was able to build a widget based dashboard in a few minutes, with text and buttons.

these are all based off the dashboard redux module markup and styling; the outer container hanna code loads the styles needed, so no need to actually add those to the module css files.

1) the CK editor view of the dashboard (page that is rendered):

2) the resulting page:

also, i added the ability to disable the default CSS file from loading, allowing users to make their own styling for the dashboard pages; this way you can load whatever font you want, and style it to match your goal design for the doc pages.

Here is what the unstyled page would look like, (and using the built-in, native jQuery UI tabs):

Here is the styled version, loading default CSS (currently optimized for Reno Theme):

Here is the latest module config screen:

[bernhard]

hi macrura!

nice to see the progress. i hope nobody gets me wrong but i still think that going with native pw modules (fields) could have some real benefits. i try to explain what i mean and how i came to that opinion...

my first impression when i saw your screenshot was, "very nice". i then asked myself how easy that could be built with a process module and InputfieldMarkup... The dashboard example would be quite easy, consisting of only 3 fields with some markup. but still it would need some coding, of course - and that might be a little more work and a little more time needed than your quick ckeditor solution. but still i'm confessed that working with native pw fields is much cleaner than hacking around with hanna codes and several nested tags inside a ckeditor field. that feels like i get thrown back to my old joomla days where we had only this one huge content field and had to do all the magic with messing around with tags and replacements and so on  i hope you get what i'm trying to say.

btw: i was thinking if i'm messing up your thread with my post, but as it is a preview thread i think discussion should be welcome

now my idea that could combine both worlds:

first i thought, "why not using some InputfieldMarkup for the content instead of the whole Process?". you are creating a process page that renders one field of a selected documentation page. i thought, what if we had some fields on that page where we can select the content that gets rendered. then i thought we already have this kind of fields: InputfieldRuntimemarkup.

So we would need a quick and easy way to arrange those fields! We already have it: The template editor. I'm using ProcessPageEdit all around my CRM application and it works well for presenting data. It has a clean interface and all you need for arranging your content (fieldsets, tabs, toggles etc - i already mentioned that in my post above).

So what if we showed the ProcessPageEdit of the documentations page directly to the user? Admins could modify content quickly and easily and for users we could set the visibility to "locked". this would result in something like that:

 

ckeditor fields would get rendered as HTML, image fields would get rendered as gallery and we could do whatever we want with RuntimeMarkup fields. We would have all the built-in pw magic, we would have a consistant styling (for all admin themes, not only for the one your stylesheets are optimized) and many other benefits.

what do you think?

[Macrura]

for my application i don't think showing the process page edit on the help page would work, b/c how would the textformatter apply the styles and how would the tabs get rendered? Maybe i'm misunderstanding though - does setting the visibility to locked render the page content somehow - sorry just got confused from your image.

yes, i agree about the nested shortcodes and the bad-old-joomla days that i never want to remember.. The point of building that shortcode based dashboard was basically a proof-of-concept to show that the module itself is flexible enough to handle display of anything you put into your CK editor, including some complex shortcodes, and specifying your own custom CSS files etc.. so more of a test case than something i would ever recommend.

i think this module should really be optimized for showing beautifully styled documentation, so the focus is on body field/ck editor presentation and the CSS needed to get there, along with the additional ability to show tabs for navigating and simplifying the UI for related documentation content.

I think your ideas would be great for a separate module, but i think i still need to understand more what you mean about it; apropos building a dashboard as fast/easily as possible, i am interested; my dashboard redux module works well and each widget can be shown based on user role, permission or the actual user; so it is optimized for sites where you want different widgets to show for different users/roles/perms; but for super simple builds where you just need to get a dashboard up fast, i think what you are suggesting sounds promising..

[cstevensjr]

I'm looking forward to your newest module.  It would benefit my internal/external work tremendously.  I hope you don't change the focus of what you are creating.

[gmclelland]

I think I understand what @bernhard is saying, but the gif is hard for me to understand.

Basically, I think he is saying "Why be limited to using one field with shortcodes, when you can render an entire help page that has multiple fields"?  With InputfieldRuntimeMarkup you can render the entire help page with ALL it's fields as you wish on the page that needs contextual help.  So you could create a fieldgroup tab(HELP) on your basic-page that includes one InputfieldRuntimeMarkup that renders your help page inside of it.

I haven't tried InputfieldRuntimeMarkup yet, but I like where this is going...

 

[Macrura]

1) the purpose of using the process module is so that you can have single pages for the documentation articles, that are navigable from the primary admin nav and bookmarkable so you can send users a link to the article; There isn't any plan for template contextual help because that is already covered by Admin Help module.

Also using the jquery tabs is completely optional; In its simplest use case, you'd just render some text there on that page for your users to read and refer to; maybe some global instructions for things they get confused about, an embedded video, or links to some tutorials on ck editor, or even some instructions about how modules work, or SEO consideration...

2) In the scenario where let's say you do want to render some very complex help page, say with tabs, accordions, or some complex charts that need custom javascript, and you don't want to use the built in tabs shortcodes, and you don't want to use hanna codes;

you'd like to be able to display the output of a template file field that generates the markup for your help page, because you are doing your tabs in a repeater, and you also have a table that you are generating with a table field etc.;

I believe that you would not need RuntimeMarkup for this; the module would simply need a switch between rendering a single field (default behavior), vs. using the template class to render the page using that custom template;

so in that case you'd only need to have a field to input the path to the custom template file for rendering the help page, if i understand correctly; Said template file would be able to self-control its own dependencies for styles and script so you'd also disable the default style from loading;

As far as i can predict, this should be a fairly simple addition to the module and shouldn't have any negative effect on the typical/simple use case;

[Macrura]

This module is on Github,

https://github.com/outflux3/ProcessDocumentation

in case any one wants to test it; will wait till i have time to run test cases before releasing..

[bernhard]

28 minutes ago, Macrura said:

will wait till i have time to run test cases before releasing..

are you talking about any kind of automated testing? or manual testing for hand picked use cases?

[Macrura]

manual testing basically, also unsure of minimum pw and php requirements also need to install/uninstall a few times, make sure it all works right;

[Macrura]

So now there are 2 modes that the process pages can be rendered in, Field Render Mode and Template Render Mode;

in field render mode, you just select the field to render and that's it; if you use the built in CSS, shortcodes and such you can output those simple tabbed help pages or just plain wikis.

if you need more options you can disable the default css and use your own css file, or multiple css files; a.k.a Field Render Mode, advanced settings.

Here is a simple wiki page, using a custom CSS file (to make it a bit more wiki-looking):

In Template Render Mode, you activate that by just putting the name of the directory where you will store the template files, within your templates directory. This mode is not mutually exclusive of Field Render Mode; they both work depending on the factors;

Once you are in Template Render Mode, you have to load all of your own dependencies; in other words, the module just lets that file take over, and renders it; The only thing the module does in this mode is sets output formatting to true on the page being rendered, before sending into the wireRenderFile method.

Here is an example of a page being rendered in Template Render Mode; for this to work it requires a matching php file to the name of the page, so this is being rendered by news-help.php inside the folder:

Here is the code in the news-help.php file.

$jqt = $modules->get("TextformatterJqueryUITabs");
$mcs = $modules->get("TextformatterMarkupCSS");

$body = $page->body;
$mcs->format($body);
$jqt->format($body);

$config->styles->add("/processwire_test1/site/modules/ProcessDocumentation/ProcessDocumentationDefault.css");

echo '<div class="help-doc">';

echo $body;

echo '</div>';

The only exception to the use of both modes is if you create a default.php file in the folder; if you do that, then the module will always render the pages using that file; So this way you can have all of your document pages being output by that one file and not have to create new php files for every new doc page;

Since you can do anything you want in those php files, you could show some content from another site. Here is an example where the php file loads a github readme file:

$markdown = file_get_contents("https://raw.githubusercontent.com/outflux3/InputfieldSelectize/master/README.md");
$tfmd = $modules->get("TextformatterMarkdownExtra");
$tfmd->format($markdown);
$config->styles->add("/processwire_test1/site/templates/docu-templates/test-wiki.css");
echo '<div class="help-doc">';
echo $markdown;
echo '</div>';

... and the page:

[dotnetic]

On 10/17/2017 at 8:32 PM, Macrura said:

You can create a folder structure by creating a top level menu item using ProcessList, and then various help pages under that parent using ProcessDocumentation

@Macrura I tried to make a folder structure, but it does not work.

First I created the page "Dokumentation" which has the process "ProcessList" assigned, as you wrote.
And it has two children with the template "documentation". 

The menu item "Dokumentation" appears (I am using AdminThemeUikit), but when I click on it, I am redirected to a page that says: "The process returned no content." 

So what did I do wrong? Maybe you can describe the exact steps to be taken, to get a folder structure documentation.

Another question: Is it possible to render the page in a panel instead of redirecting?

[Macrura]

@jmartsch

(1) did you select a page to display and is the field containing the content populated on that selected page?

9 minutes ago, jmartsch said:

Another question: Is it possible to render the page in a panel instead of redirecting?

yes, it is, but you'll need the other module, called ContextHelpTemplate, and that module can work with PD

https://github.com/outflux3/ContextHelpTemplate

[dotnetic]

@Macrura Thank you for the quick answer ?

I done that before, but then changed the process to "ProcessList" as you wrote in your inital post, because I want to show the children in a list.

When I revert to use ProcessDocumentation for the page, I just get the default behaviour. I selected a page that is in the page tree, not under admin, so my customer can change the content if he wants to.

Now the documentation menu item takes me to the page I selected, but how do I get a listing of the child pages on this page?

[Macrura]

you need 1 process page for each displayable doc page.

[dotnetic]

So you have to recreate your help folder structure in admin, right? 

I have to say that this is very cumbersome.

It would be easy if you just create ONE page under admin with process "ProcessDocumentation" and select a page from the page tree.
If that page has children, display them somehow (in a list, as submenus, etc). This could be configurable.
This would make this module a lot more user friendly.

[Macrura]

i understand it may be more work, but as far as i know there is no way to magically create virtual admin process pages on the fly, each 'page' in the admin that you want to be viewable and access controlled needs to have a real page.

[dotnetic]

Is https://github.com/outflux3/ContextHelpTemplate really meant to be used in conjunction with ProcessDocumentation, or is it just for AdminHelp? 

Because it seems to be very tailored to AdminHelp.

I installed it, and set the setting to open in modal, but my "Dokumentation" menu item link still opens a normal page.

[Macrura]

you might be misunderstanding this. Context help for templates means you need to add a template select field to the page holding the content to be shown on that template.  Notice how you are missing that whole setting - you need the fieldtype, then the field and add it to the doc page template, then select the template where to show the doc.