View source for Action Help Option

{{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