Revision [1654]
This is an old revision of DescribeActions made by DarTar on 2004-10-05 13:20:34.
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
*/
/**
* 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( "(/\*)(.+)(\n\*/)", $contents, $desc)) {
$desc[0] = preg_replace("((/\*)|(\n\*/)|(\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);
?>
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( "(/\*)(.+)(\n\*/)", $contents, $desc)) {
$desc[0] = preg_replace("((/\*)|(\n\*/)|(\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