Forum for discussing general topics related to Couch.
5 posts Page 1 of 1
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.

I am going to move all HTML to help files whose content will be loaded inside <pre> tags -
Code: Select all
        $tmp = <<<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 749 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.
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 <>

Result somewhere on your page -
2019-06-21-153055.png (9.42 KiB) Viewed 725 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 725 times
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 717 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 715 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 -

    ---other params can be checked and hints provided--

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.

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

So far, I have completed help pages for -
5 posts Page 1 of 1

Who is online

In total there are 5 users online :: 0 registered, 0 hidden and 5 guests
(based on users active over the past 5 minutes)

Users browsing this forum: No registered users and 5 guests