简介
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 \ /()+ \-] + $ /
适用于电话号码,仅允许数字和字符()-+ /
- / ^ [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_AddressAction 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上创建附加页面
(创建页面模板)
模板需要包含与表单相同的字段,并且还可以使用其他一些占位符。 其中一些可以用作表单字段的默认值:
Placeholder | action |
---|---|
@@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; }
}