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
        <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'/>


2019-06-19-032409.png
custom help page by @trendoman
2019-06-19-032409.png (15.25 KiB) Viewed 2207 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 <tony.smirnov@gmail.com>
*/


Result somewhere on your page -
2019-06-21-153055.png
2019-06-21-153055.png (9.42 KiB) Viewed 2183 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
2019-06-21-153143.png (77.06 KiB) Viewed 2183 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
2019-06-21-191534.png (24.26 KiB) Viewed 2175 times


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

2019-06-21-194156.png
syntax check
2019-06-21-194156.png (6.93 KiB) Viewed 2173 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.

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
5 posts Page 1 of 1
cron