{{toc numerate=1}}
The goal is to have a help option at hand like we know it from command line commands and have a common way to document all available parameters of each action. This way the user as well as the developer has all information accessible inside the application.
===Parameter===
##help=1## print help and exit.
To print only the help, the action must process and output the help parameter first.
====Set default====
%%(php)
<?php
// set defaults
$help ??= 0;
%%
====Without template====
%%(php)
<?php
if ($help)
{
echo $this->help($info, 'paragraphs');
return;
}
%%
====With template====
%%(php)
<?php
if ($help)
{
$tpl->help = $this->help($info, 'anchor');
return;
}
%%
%%
[ === main === ]
[ ' help ' ]
%%
=====Discard other template output=====
All following parts must be wrapped in a definition to not get printed with the help. This way the non existing definitions in the template array prevent the output.
%%(php)
<?php
if ($condition)
{
$tpl->parent_variable = $variable;
}
$tpl->definition = true;
%%
%%
[= parent _ =
<span>[ ' variable | filter ' ]</span>
=]
[= definition _ =
<tag>
[ ' _t: Hello ' ]
</tag>
=]
%%
===Example===
##~{{edit help=1}}##
{{edit help=1}}
====Example action====
action/edit.php
%%(php)
<?php
if (!defined('IN_WACKO'))
{
exit;
}
$info = <<<EOD
Description:
Creates a link to the edit handler, if the user has the right to edit the given page.
Usage:
{{edit}}
Options:
[page="EditThisPage"]
[text="your text"]
EOD;
// set defaults
$help ??= 0;
$page ??= '';
$text ??= '';
$tag = $page ? $this->unwrap_link($page) : $this->tag;
$href = $this->href('edit', $tag);
if ($help)
{
$tpl->help = $this->help($info, 'edit');
return;
}
if (!$text)
{
$text = $this->_t('EditText');
}
if ($this->has_access('write'))
{
$tpl->l_href = $href;
$tpl->l_text = $text;
}
%%
action/template/edit.tpl
%%
[ === main === ]
[ ' help ' ]
[= l _ =
<a href="[ ' href | e attr ' ]" title="[ ' _t: EditTip ' ]">[ ' text | e ' ]</a>
=]
%%
===Help function===
class/wacko.php
%%(php)
<?php
// ...
// help action wrapper
function help(string $info, string $action): string
{
return $this->action('help', ['info' => $info, 'action' => $action]);
}
// ...
%%
===Help action===
If it can't find a related translation it defaults to the original help text.
action/help.php
%%(php)
<?php
if (!defined('IN_WACKO'))
{
exit;
}
// set defaults
$info ??= '';
$action ??= '';
// check for translated version
$lang = $this->get_user_language();
$help = [];
$lang_file = Ut::join_path('action/lang', 'help.' . $lang . '.php');
if (@file_exists($lang_file))
{
include $lang_file;
}
if (isset($help[$action]))
{
$info = $help[$action];
}
$tpl->help_text = $info;
%%
action/template/help.tpl
%%
[ === main === ]
[= help _ =
<pre class="help">
[ ' text | pre ' ]
</pre>
=]
%%
===Localization===
{{files}}
action/lang/help.de.php
%%(php)
<?php
if (!defined('IN_WACKO'))
{
exit;
}
$help = [
'changes' =>
<<<EOD
Beschreibung:
Zeigt die Liste der letzten Änderungen in jedem Cluster.
Verwendung:
{{changes}}
Optionen:
[page="Cluster"]
[date="YYYY-MM-DD"]
[max=Number]
[title=1]
[noxml=1]
EOD,
'edit' =>
<<<EOD
Beschreibung:
Erstellt einen Verweis zum Bearbeiten einer bestimmten Seite, wenn der Nutzer das Recht hat diese zu bearbeiten.
Verwendung:
{{edit}}
Optionen:
[page="SeiteZumBearbeiten"]
[text="Dein Text"]
EOD,
];
%%
action/lang/help.ru.php
%%(php)
<?php
if (!defined('IN_WACKO'))
{
exit;
}
$help = [
'changes' =>
<<<EOD
Описание:
Выводит список последних изменений в каком-либо кластере.
Usage:
{{changes}}
Опции:
[page="Cluster"]
[date="YYYY-MM-DD"]
[max=номер]
[title=1]
[noxml=1]
EOD,
'edit' =>
<<<EOD
Описание:
Позволяет включить линк на правку другой страницы.
Usage:
{{edit}}
Опции:
[page="ДругаяСтраница"]
[text="your text"]
EOD,
];
%%
===CSS===
default.css
%%(hl css)
pre.help {
border: 1px solid lightgray;
border-radius: 3px;
padding: 10px;
}
%%
===Test===
%%
{{toc numerate=1}}
===admin_massregex===
{{admin_massregex help=1}}
===admin_recovery===
{{admin_recovery help=1}}
===admin_replace===
{{admin_replace help=1}}
===admincache===
{{admincache help=1}}
===adminupdate===
{{adminupdate help=1}}
===anchor===
{{anchor help=1}}
===authors===
{{authors help=1}}
===backlinks===
{{backlinks help=1}}
===blog===
{{blog help=1}}
===calendar===
{{calendar help=1}}
===categories===
{{categories help=1}}
===category===
{{category help=1}}
===changepassword===
{{changepassword help=1}}
===changes===
{{changes help=1}}
===comment===
{{comment help=1}}
===commented===
{{commented help=1}}
===comments===
{{comments help=1}}
===deleted===
{{deleted help=1}}
===edit===
{{edit help=1}}
===editsection===
{{editsection help=1}}
===embed===
{{embed help=1}}
===feed===
{{feed help=1}}
===filelinks===
{{filelinks help=1}}
===files===
{{files help=1}}
===forums===
{{forums help=1}}
===gallery===
{{gallery help=1}}
===groups===
{{groups help=1}}
===hashid===
{{hashid help=1}}
===help===
{{help help=1}}
===hits===
{{hits help=1}}
===imageslider===
{{imageslider help=1}}
===import===
{{import help=1}}
===include===
{{include help=1}}
===interwikilist===
{{interwikilist help=1}}
===lastedited===
{{lastedited help=1}}
===license===
{{license help=1}}
===login===
{{login help=1}}
===menu===
{{menu help=1}}
===mostcommented===
{{mostcommented help=1}}
===mostpopular===
{{mostpopular help=1}}
===mychanges===
{{mychanges help=1}}
===mychangeswatches===
{{mychangeswatches help=1}}
===mygroups===
{{mygroups help=1}}
===mypages===
{{mypages help=1}}
===mywatches===
{{mywatches help=1}}
===navigation===
{{navigation help=1}}
===news===
{{news help=1}}
===orphaned===
{{orphaned help=1}}
===pagebreak===
{{pagebreak help=1}}
===pageindex===
{{pageindex help=1}}
===pagelinks===
{{pagelinks help=1}}
===paragraphs===
{{paragraphs help=1}}
===randomimage===
{{randomimage help=1}}
===randompage===
{{randompage help=1}}
===randomphrase===
{{randomphrase help=1}}
===redirect===
{{redirect help=1}}
===registration===
{{registration help=1}}
===search===
{{search help=1}}
===tagcloud===
{{tagcloud help=1}}
===toc===
{{toc help=1}}
===topics===
{{topics help=1}}
===tree===
{{tree help=1}}
===upload===
{{upload help=1}}
===usergroups===
{{usergroups help=1}}
===userpages===
{{userpages help=1}}
===users===
{{users help=1}}
===usersettings===
{{usersettings help=1}}
===wanted===
{{wanted help=1}}
===watchers===
{{watchers help=1}}
===whatsnew===
{{whatsnew help=1}}
%%
===ToDo===
* build English help.en.php via script as template for other languages
* action array + template