Revision [1656]

This is an old revision of DescribeActions made by DarTar on 2004-10-05 13:32:03.

 

Action Descriptor


One of the next steps for providing a comprehensive HelpInfo documentation is to add some clear information on all the actions shipped with the Wikka package (how to use them, what parameters they accept etc.).
I've written a metaction that retrieves automatically the list of actions stored in the actions/ folder and displays their description. This saves a lot of work and generates on-the-fly all the required infos.

Here's the two-step implementation:

1. Add descriptions to action files

The idea came from JavaWoman's use of phpDocumentor headers in her code.
To make action infos retrievable we just need to add a basic header like the following in every action:

<?php
    /**
    * Coffe action (actions/coffee.php)
    * Description: This action prepares a cup of great coffee every morning at 7:00 am
    * Usage:    {{coffee sugar="value"}}
    * Parameters:    
    *  - sugar (int):    specifies the number of spoonfuls of sugar. No value produces black coffee without sugar    
    */


We might consider allowing some basic phpDocumentor tags.

2. Create a parser to retrieve and print descriptions

The following action get the files stored in the actions/ folder, extracts action descriptions and prints them. I've set the character limit to 600, but this can be changed.
Save the following code as actions/actionlist.php and use it as {{actionlist}}

<?php
echo $this->Format("=== List of available actions === --- ");
$handle = opendir('actions/');
while (false !== ($file = readdir($handle))) {
        if ($file != "." && $file != "..") {
                echo "$file<br />\n";
                $fd = fopen("actions/".$file, "r");
                $contents = fread ($fd, "600");
                if (ereg( "(/\*)(.+)(\*/)", $contents, $desc)) {
                    $desc[0] = preg_replace("((/\*)|(\*/)|(\n\*))", "\n", $desc[0]);
                    echo $this->Format("@@".$contents."@@ --- ");
                    // Please replace in the previous line @@ with two % signs.
                    // Couldn't do it in a wikka highlighted code block!
                }

                fclose($file);
        }
}
closedir($handle);
?>


-- DarTar



CategoryDevelopment
There are 2 comments on this page. [Show comments]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki