简介
Bureaucracy是一个用于在DokuWiki中创建HTML表单的插件。
入力验证由插件自动处理，不需要编码。 基于表单入力的内容和事先指定的模板，可以自动生成邮件或创建新的页面。
Bureaucracy插件可以用来实现用户咨询，用户发表等诸多网站应用功能。
使用方法
让我们从一个例子开始：
<form>
Action mail me@example.com
Thanks "Thanks for submitting your valuable data."
Fieldset "A set of fields"
Textbox "Employee Name" "=Your Name"
number "Your Age" >13 <99
email "Your E-Mail Address"
textbox "Occupation (optional)" !
password "Some password"
fieldset "even more fields"
select "Please select an option" "Peaches|Apples|Oranges"
static "Some static text that could be an agreement"
yesno "Read the agreement?"
textarea "Tell me about your self"
textbox "You need to write 'agree' here" /^agree$/
submit "Submit Query"
</form>
如上所示，我们可以定义一个电子邮件地址，将数据发送到该电子邮件地址，并在用户提交表单时显示感谢文本。
字段
表单里可以定义各类字段(Field)：
通过指定类型和标签来定义字段(Field)。字段集(Fieldset)及有些字段(Field)如提交按钮(Submit)的标签是可选的有些字段(Field)如选择框(Select)需要设定其他参数可以在主要选项之后添加其他约束当参数包含空格时，它们需要用双引号引起来
以下是要填写的各个字段：
action
第一个参数需指定表单的动作模式，当前支持的模式有：mail（邮件）, template（模板）和script（脚本），可通过其他插件扩展动作模式。
另外，可以定义多个action字段以使表单同时支持多个动作模式。mail(邮件）的其他参数：:一个或多个电子邮件地址（必填）template（模板）模式的其他参数:
用作模板的页面文件的路径（必填)所创建新页面的路径名或路径名前缀（必填）新页面路径中使用多个字段值时的分隔符（可选）script（脚本）模式的其他参数:在conf/plugin/bureaucracy/ 目录下的脚本文件名
thanks定义提交表单时显示的文本消息。 （可选的）
fieldset
创建一组字段
static静态文本
wiki支持wiki文法的静态文本
textbox单行文本输入框，需指定标签
password密码输入框，需指定标签
email邮件地址输入框，需指定标签。输入值会被进行有效性验证
参数@@将字段值标记为邮件操作的回复地址。
number
数值输入框，需指定标签。输入值会被进行有效性验
textarea
多行文本输入框，需指定标签。默认10行大小，可使用参数xN（x23）（可选）修改。
yesno
复选框，需指定标签
select 单选框，需指定标签和选项列表（用“|”分隔，如 "Peaches|Apples|Oranges" )。
multiselect多选框，需指定标签和选项列表（用“|”分隔，如 "Peaches|Apples|Oranges" )。
radio
一组单选框，需指定标签和选项列表（用“|”分隔，如 "Peaches|Apples|Oranges" )。
hidden不可见字段。
submit提交按钮，可指定标签（可选）
。user / users用户选择框，需指定标签。
date日期（格式：YYYY-MM-DD)输入框，需指定标签。
time时间（格式：(H)H:MM(:SS))输入框，需指定标签。
usemailtemplate template_id
addpage page_tpl page_tgt
labels标签，参数是一个Wiki页面，其中包含标签翻译列表
file文件选择框，需指定标签。
data_aliastextbox (需Data插件)qianjie
struct_field +
struct_fieldhidden (需Struct插件)
struct_schema (需Struct插件)约定如果数字前接符号”>“，表示输入数据必须大于该数字。如果数字前接符号”<“，表示输入数据必须小于该数字。符号”=“用于指定缺省值符号”!“用于指定字段可选符号“^”用于指定缺省焦点符号“@”用于在template处理模式中指定字段值作为页面路径名的一部分符号“@@”用于在mail处理模式中指定字段值作为回复的邮件地址在数字字段中使用数字0000，入力值位数不够的情况下将会在前面自动补0在数字字段中使用++，每次提交表单时将自动增加计数。用/字符括起来的正则表达式用于限定输入值，如：/ ^ [0-9 \ /（）+ \-] + $ /
适用于电话号码，仅允许数字和字符（）-+ /外部标签
缺省情况下，字段的标签直接定义在表单中。但我们也可以把标签统一定义在一个单独的wiki页面文件里，然后在表单里用labels字段指定该页面文件名，这点在需要对应多语言时尤其有用。
<form>
action mail me@example.com
labels mylabels
fieldset "field"
textbox "name"
number "age" >13 <99
submit "submit"
</form>
标签定义页面需要包含一个Wiki列表，其中包含名为label = translation的项目：
* field = Tell us about yourself"
* name = Your Name
* age = Your Age
* submit = Send your Data
显示结果如下：
动作模式
Bureaucracy插件执行以下处理：
显示表单验证用户输入将用户输入传送给动作模式
最后一步的处理， 如上所述，需在动作字段中定义要使用的动作。 当前支持三种模式：邮件，模板和脚本。 可以轻松添加其他模式（例如，将数据存储在数据库中）。
mail(邮件)模式
这是一个简单的动作模式。 使用默认值时，所有用户输入将通过电子邮件发送到配置的电子邮件地址。 请参阅上面的示例如何使用它。 可以指定多个收件人邮件地址，以空格分隔。
下面的例子将电子邮件自动发送到用户输入的地址：
Fieldset "Some Information"
Textbox "Employee Name"
email Email_Address
Action mail @@email_address@@
字段usemailtemplate用于定义电子邮件的模板。 模板应包含两个代码块，其中包含发送邮件的文本和html版本。 页面上的其他文本将被忽略。 在模板中，您可以使用占位符。字段subject用于定义主题使用选项@@标记字段，该字段值将作为邮件的“回复”地址
下面的例子定义了邮件的模板和主题：
action mail @MAIL@ forename@surname.name
usemailtemplate your:template
subject "new special subject"
下面时模板文件的内容：
======Mail template page======
<code html>
Dear @@Your Name@@,
You are <b>great<b>, you just <i>purchased</i> our @@What do you want@@!
We will deliver it fast as possible, see the
<a href="http://example.com/conditions">conditions</a>.
Kind regards,
Future Machines company
</code>
<code text>
Dear @@Your Name@@,
You are great, you just purchased our @@What do you want@@!
We will deliver it fast as possible, see [1].
Kind regards,
Future Machines company
[1] http://example.com/conditions
</code>
template(模板)模式
template模式使用给定的页面作为模板，将用户输入替换已定义的占位符从而创建新的Wiki页面。
定义方法如下：
action template [template] [destination] [separator]
template可以是一个页面可以是一个名字空间（尾随冒号）。
该名称空间所包含的所有子名称空间和页面都将被复制到目标位置，替换模式将应用于所有页面。如果指定下划线（_）作为模板名称时，插件将尝试使用目标名称空间的已配置名称空间模板。destination
指定新页面的创建位置。 这通常是一个名称空间（尾随冒号）。 separator
可以使用多个表单字段值创建新的页面名称。 此字符定义了将它们串联在一起时的分隔符。
（定义结果页面）
使用template模式时，我们需要定义应在何处创建结果页面。 这有多种方法。
方法1是指定一个输出名称空间，并使用@符号标记命名字段。
<form>
action template userstpl users: :
fieldset "Create Your User Page"
select "What's your Continent?" "Europe|N. America|S. America|Asia|Australia|Africa" @
textbox "What's your Name?" @
textarea "Enter a short bio" !
submit
</form>
上面这个例子将使用Continent和name字段创建一个新页面。 例如。 如果我在这些字段中填写“Europe”和“andi”，则结果页面将是users：europe：andi。
方法2通过在destination参数中使用占位符（由@@字符包围的字段名称。 另外，可以使用任何strftime参数）并在字段定义中省略@标记来实现对生成的页面名称进行更多控制。
<form>
action template userstpl "users:%Y:@@What's your Name?@@:start"
fieldset "Create Your User Page"
select "What's your Continent?" "Europe|N. America|S. America|Asia|Australia"
textbox "What's your Name?"
textarea "Enter a short bio" !
yesno "Do have publication?"
fieldset "Add your publications" "Do have publication?"
textarea "Publications:"
addpage users:publicationtemplate publications
fieldset "Finish"
submit
</form>
上面的代码将基于系统年份（2019）和我的名字创建一个命名空间，并在其中创建一个起始页面：users：2019：andi：start
方法3当使用特殊的addpage（添加页面）字段。这个方法可以根据入力情况有选择的创建某些页面。
addpage additionaltpl somepage
上例中的第二个字段集通过复选框添加了发布页面。 这里，其他页面的模板位于绝对路径上：users：publicationtemplate。 仅当选中yesno字段时，才会在users：2019：andy：start：publications上创建附加页面
（创建页面模板）
模板需要包含与表单相同的字段，并且还可以使用其他一些占位符。 其中一些可以用作表单字段的默认值：
Placeholderaction@@Field label@@
##Field label##将由用户填写到表单中的实际值代替@curNS(arg)@
@getNS(arg)@
@noNS(arg)@
@p_get_first_heading(arg)@将由相应的dokuwiki函数的结果替换。 arg可以都是静态值(例如。 @curNS（some：test：value）@),或字段的占位符(例如 @p_get_first_heading（@@ field @@）@)。
@@Field label|Nice alternative@@对于空字段，显示缺省文本
@NSBASE@生成页面的名字空间@YEAR@, @MONTH@, @DAY@, @TIME@, @TIMESEC@当前的年，月，日，时间@LANG@从设定中获得的语言代码@TRANS@从表单的页面ID获得的语言代码
对于上面示例中的userstpl，我们可以定义成以下的页面
====== @@What's your Name?@@ ======
I'm living in @@What's your Continent?@@. I'm a user since %Y-%m-%d.
@@Enter a short bio|FIXME please fill in your biography@@
结果将看起来像这样
====== Andreas Gohr ======
I'm living in Europe. I'm a user since 2007-12-23.
It's me :-)
（user字段信息）
使用一个或多个user字段时，可以在模板中使用所选用户的其他数据：
“ @@ user.name @@”
替换为用户全名“ @@ user.mail @@”
替换为用户电子邮件地址“ @@ user.grps @@”
由用户grps替换，逗号分隔“ @@ user.grps（separator）@@”
由用户组替换，并由“ separator”分隔'@@ users（separator）@@'-
替换为用户昵称列表，并以'separator'分隔'@@ users（separator）.name'-
用用户全名列表替换，用'separator'分隔'@@ users（separator）.mail'-
用用户电子邮件列表替换，用'separator'分隔
可以省略分隔符，然后使用逗号作为分隔符。 例如。 @@ users.mail @@，@@ users.name @@，不支持@@ users.grps @@
script(脚本)模式
script模式将表单数据提交给PHP脚本，PHP脚本可以对数据执行任何所需的操作。
PHP脚本必须放在conf/plugin/bureaucracy /目录中，它必须包含一个名为helper_plugin_bureaucracy_handler_scriptname的类，并实现接口dokuwiki\plugin\ bureaucracy\interfaces\bureaucracy_handler_interface，这意味着该类必须具有handleData（$ fields，$ thanks）方法，并以字段和thank-message作为参数。 如果成功，则返回结果消息，如果发生错误，则返回false。
下面是一个简单的script模式的例子，仅实现了在DokuWiki的调试日志中打印表单的数据。
<form>
action script example.php
textbox "Type something"
submit "Write to log"
</form>
conf/plugin/bureaucracy/example.php
<?php
use dokuwiki\plugin\bureaucracy\interfaces\bureaucracy_handler_interface;
class helper_plugin_bureaucracy_handler_example implements bureaucracy_handler_interface {
/**
* Log the form fields to DokuWiki's debug log
*/
public function handleData($fields, $thanks)
{
dbglog($fields, __FILE__ . ': ' . __LINE__);
dbglog($thanks, __FILE__ . ': ' . __LINE__);
return $thanks;
}
}
