CouchCMS • View topic - <cms:anytag help='1'/> => HEPA: Help Pages Addon

Forum for discussing general topics related to Couch.

5 posts Page 1 of 1

<cms:anytag help='1'/> => HEPA: Help Pages Addon

: trendoman; Registered User

: Posts: 2900; Joined: Thu May 22, 2014 3:57 pm

by trendoman » Fri Jun 14, 2019 11:35 am

I request help and collaboration from developers to empower the new custom parameter and create short version of documentation for each Couch tag.

In my personal code collection now exists a file that gives each tag a new optional help parameter. It is easy now to write something like

Code: Select all

<cms:pages help='1'>

and refresh the page to see embedded HTML with info on cms:pages tag. Or any other tag which demands looking for documentation, for example If I need to work with users and quickly see possible values of parameter redirect of process_login tag -

Code: Select all

<cms:process_login redirect='1' help='1' />
<!-- redirect='0':   // no redirection -->
<!-- redirect='1':   // redirect to current page -->
<!-- redirect='2':   // link supplied as querystring parameter (this is default behaviour) -->
<!-- redirect='url': // link supplied as parameter to this tag -->

The way my code is structured is this - when tag executes it senses the request for help and inserts after its normal result a customizable html template loaded dynamically from a folder /html_templates/{tag-name}.html. So, for pages tag, the file would be html_templates/pages.html and its content is whatever HTML you want there. It will be loaded and embedded into your page in browser.

Now whenever I request help via custom parameter - I only need to refresh my page. You may very well place there your own design of documentation and display whatever - only parameters or only examples or your custom notes.

I will respond to every PM for a demo of this feature and ask you, couchers, to help create these little HTML templates with documentation for each tag. This custom addon will be freely given to those that help and all doc templates shared among us.

Join COUCH:TALK channel here https://t.me/couchcms_chat
Ryazania — a framework to boost productivity with Add-ons viewtopic.php?f=2&t=13475
Support my efforts to help the community https://boosty.to/trendo/donate

Last edited by trendoman on Mon Jun 24, 2019 4:43 am, edited 3 times in total.

: trendoman; Registered User

: Posts: 2900; Joined: Thu May 22, 2014 3:57 pm

by trendoman » Wed Jun 19, 2019 6:05 am

I am going to move all HTML to help files whose content will be loaded inside <pre> tags -

Code: Select all

        $tmp = <<<HTML
        <pre>
            $body
        </pre>
HTML;

For example I have created a new file - arr_key_exists.html for existing undocumented tag and it will show me some help information when I write -

Code: Select all

<cms:arr_key_exists help='1'/>

: custom help page by @trendoman; 2019-06-19-032409.png (15.25 KiB) Viewed 3988 times

I wish many people could help each other and create their short version for each tag, attaching files in this topic and using whatever design they like.

Help Pages Addon

: trendoman; Registered User

: Posts: 2900; Joined: Thu May 22, 2014 3:57 pm

by trendoman » Fri Jun 21, 2019 6:11 pm

This is now a standalone Addon help-pages. Built to provide context help for all tags (including new tags and custom tags from forum) and all custom functions.

*See the next post for more cool features*

6/21/2019 - added help pages for custom functions, defined via <cms:func> tag. Same usage -

Code: Select all

<cms:call 'my-func' help='1' />

Again, help file is plain HTML with support of Couch tags. Example -

Code: Select all

In any function call I just add parameter help='1' - 
________________________________________
<cms:call 'ip' help='1' />



Sample content of autoloaded help file - "ip.html" - 
________________________________________

  _   _   _   _   _   _   _   _     _   _   _   _
 / \ / \ / \ / \ / \ / \ / \ / \   / \ / \ / \ / \
( f | u | n | c | t | i | o | n ) ( h | e | l | p )
 \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/   \_/ \_/ \_/ \_/


&lt;cms:func 'ip' /&gt; - definition

/**
*   Echoes Ip-address
*
*   @category Users
*   @example &lt;cms:call 'ip' /&gt;
*   @link
*   @author Anton Smirnov aka Trendoman <tony.smirnov@gmail.com>
*/

Result somewhere on your page -

: 2019-06-21-153055.png (9.42 KiB) Viewed 3964 times

You may wonder the reason - so here it is, I currently have coded over 60 custom functions in my code collection, so there is always a place for a good help file with examples, notes etc. Simply enumerating parameters of them (automatically) is just too limited.

: 2019-06-21-153143.png (77.06 KiB) Viewed 3964 times

Last edited by trendoman on Fri Jun 21, 2019 10:19 pm, edited 1 time in total.

Syntax check and hints

: trendoman; Registered User

: Posts: 2900; Joined: Thu May 22, 2014 3:57 pm

by trendoman » Fri Jun 21, 2019 9:56 pm

What happens in Couch when you write something like this? -

Code: Select all

<cms:input />

Answer: Couch will abort and show an Error about missing 'type' parameter.

How HEPA handles this instead? Allow me to have a foreword. Since today Addon features the next big thing - passing parameters of the tag to the help page itself, making it possible to program a SYNTAX ANALYZER. Example -

Write the same code with the help request -

Code: Select all

<cms:input help='1' />

Refresh the page and now 3 things happen -

(A) page will *not* abort and continue its running
(B) help page will be displayed
(C) all parameters passed to tag's code will be check-able.

: 2019-06-21-191534.png (24.26 KiB) Viewed 3956 times

So the missing parameter type can be recognized, as well as all the other parameters.

: syntax check; 2019-06-21-194156.png (6.93 KiB) Viewed 3954 times

In help page itself it looks very simple (yes, it supports Couch code) -

Code: Select all

<cms:if params.type = '' >
    <h5>(!) Missing a required parameter <strong>type</strong>.</h5>
    Following types are currently supported -
        text
        dropdown
        ..

    ---other params can be checked and hints provided--
</cms:if>

For other tags like <cms:pages>, we can parse the custom_field parameter and, for example, hint about the difference between single = and double == and explain the effect on the speed of filtering. In tag <cms:date> local date formats can be suggested, etc, etc. I hope you can see the potenial which is already available for programming.

Your feedback is eagerly awaited.

: trendoman; Registered User

: Posts: 2900; Joined: Thu May 22, 2014 3:57 pm

by trendoman » Mon Jun 24, 2019 4:40 am

I have set a new form of template, which will use for tags and functions.

So far, I have completed help pages for -
cms:is
cms:arr_key_exists
cms:arr_val_exists
cms:test

Post a reply

Previous Next

5 posts Page 1 of 1

Return to General Discussion