Macrura

Module Preview: Process Documentation

Recommended Posts

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.

modules-list1.jpg.82afbcc73d0c2585af5b45e176c1a1a9.jpg

modules-list2.jpg.c7ed3d8757d3a2138de8c1c7600ffb3a.jpg

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

module-config.jpg.39759de82bcc1453de012bdf2f8553b8.jpg

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.

edit-content.thumb.jpg.ac97f888c33855ebaea01fbf20b5b90e.jpg

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.

process-page.jpg.c08703156214f51e417c49245b4d2833.jpg

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.

help-page.thumb.jpg.3896f980d8a530a8404a976f031c303b.jpg

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.

  • Like 15

Share this post


Link to post
Share on other sites

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? 

Share this post


Link to post
Share on other sites
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).

Share this post


Link to post
Share on other sites
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...

  • Like 2

Share this post


Link to post
Share on other sites

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

  • Like 1

Share this post


Link to post
Share on other sites
2 hours ago, szabesz said:

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

that's exactly what i mean :P 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 :) 

Share this post


Link to post
Share on other sites

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

59e757526ef9d_Edit_Page__Markup_Dashboard__localhost.thumb.jpg.13c6bca47ee2f75e060c0a196fb2a02c.jpg

2) the resulting page:

59e756e227718_Example_Dashboard__ProcessWire__localhost.thumb.png.8c2be035626a57f61adbe69781164fd7.png

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

News_Help_no_css.thumb.png.3f638f20ab4e6db4514c59787d922494.png

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

News_Help_reno_css.thumb.png.9facbfcbb9df81a1732309cce78ca993.png

Here is the latest module config screen:

Modules_config.png.2600f4fbd3884300cf02792649dbce1e.png

  • Like 4

Share this post


Link to post
Share on other sites

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:

 dashboard.gif.4fbbb2fa9308d2bfe38d189f42dd3241.gif

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?

  • Like 1

Share this post


Link to post
Share on other sites

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

  • Like 1

Share this post


Link to post
Share on other sites

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.

  • Like 1

Share this post


Link to post
Share on other sites

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

 

Share this post


Link to post
Share on other sites

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;

  • Like 3

Share this post


Link to post
Share on other sites
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?

Share this post


Link to post
Share on other sites

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;

Share this post


Link to post
Share on other sites

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

59e8a9b3dc098_My_Wiki_Page__ProcessWire__localhost.thumb.jpg.bd9b77fae51b4bbcd1c842499a8bc3da.jpg

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:

ForkLift.jpg.c2f72bed4db3f5f87aef3e1fffa4f4e4.jpg

59e8a9b54f18e_News_Help__ProcessWire__localhost.thumb.jpg.db9b7aed2a90bb66cd8ae2094208e166.jpg

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:

59e8ac2b3c82d_Github_Readme__ProcessWire__localhost.thumb.jpg.d38b984369751542630c718db4ca6980.jpg

  • Like 3

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now


  • Recently Browsing   0 members

    No registered users viewing this page.