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.

1. Parameter

help=1 print help and exit.

To print only the help, the action must process and output the help parameter first.

1.1. Set default

<?php

// set defaults
$help        ??= 0;
	

1.2. Without template

<?php

if ($help)
{
    echo $this->help($info, 'paragraphs');
    return;
}
	

1.3. With template

<?php

if ($help)
{
    $tpl->help    = $this->help($info, 'anchor');
    return;
}
	

[ === main === ]
[ ' help ' ]	

1.3.1. 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

if ($condition)
{
    $tpl->parent_variable = $variable;
}

$tpl->definition = true;
	

[= parent _ =
	<span>[ ' variable | filter ' ]</span>
=]

[= definition _ =
	<tag>
		[ ' _t: Hello ' ]
	</tag>
=]	

2. Example

{{edit help=1}}

Description:
	Creates a link to the edit handler, if the user has the right to edit the given page.

Usage:
	{{edit}}

Options:
	[page="PageName"]
	[text="your text"]		

2.1. Example action

action/edit.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>
	=]	

3. Help function

class/wacko.php

<?php

// ...

    // help action wrapper
    function help(string $info, string $action): string
    {
        return $this->action('help', ['info' => $info, 'action' => $action]);
    }

// ...
	

4. Help action

If it can't find a related translation it defaults to the original help text.
action/help.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>
	=]	

5. Localization

action/lang/help.de.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

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,

];
	

6. CSS

default.css

pre.help {
    border: 1px solid lightgray;
    border-radius: 3px;
    padding: 10px;
}

7. 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}}	

8. ToDo

• build English help.en.php via script as template for other languages
  • action array + template