Formcat class for PHP
V1.02 Feb 2005 (c) 2005 Joey Wong 黄俊研(joey@163.com)[MSN:gzjoey@hotmail.com]
This software is dual licensed using BSD-Style
and LGPL. This means you can use it in compiled proprietary and commercial products.
链接: Formcat官方网站 Formcat
SourceForge Project Formcat
on Hotscripts
Smarty官方网站 SmartyValidate
简介
I.旅程开始
1.什么是Formcat及新增功能
2.需求
3.安装
4.一个简单范例
II.Formcat应用在模版
5.概述及catform扩展属性
6.校验器
6.1 notEmpty
6.2 isRange
6.3 isLength
6.4 cboxChecked
6.5 radioChecked
6.6 isSelected
6.7 isEmail
6.8 isInt
6.9 isFloat
6.10 isDate
6.11 isURL
6.12 isEqual
6.13 isFileSize
6.14 isFileType
6.15 dateCompare
6.16 isRestrict
6.17 isRegExp
III.Formcat应用于PHP程序
7.概述
8.增加自定义Javascript到校验函数中
IV. 自定义校验器
9.概述
10.扩展Formcat
V. 作者信息
VI.版权信息
简介
Formcat 是来自中国广州PHP爱好者黄俊研(Joey Wong)先生开发的类.主要用于WEB工程中,生成HTML表单客户端校验代码.它能非常快速,准确地通过formcat标记,自动生成校验所需的javascript.表单校验的繁琐工作,从此成为统一的,简单的小工作.
Formcat提供大量检验器,以适应主流校验的需要,例如可以检验"不为空"(notEmpty),"数值范围"(isRange),"字符长度"(isLength),"正确email"(isEmail),"是否选择了单选钮"等等.还提供了自定义校验器等扩展功能.自Formcat
1.02版后,还将提供catform扩展属性,以提供多元化校验及视觉导向相结合的功能.
Formcat支持单页面多表单校验.Formcat只提供客户端校验,而服务器端校验,推荐使用SmartyValite,结合Smarty官方发布的SmartyValidate,
是不二的客户端及服务器端校验强劲组合.
Formcat是PigCat PHP Development Framework开发框架(未公开)的一部分.Formcat只运行在Smarty模版引擎环境.
I. 旅程开始.
1. 什么是Formcat
"Formcat",是聪明的小猫,:).一个表单客户端校验插件.当你使用"Formcat"后,你不需要再编写大量的脚本去校验表单输入的内容.
"再见了繁琐耗时的任务,Formcat Go Go GO!".
- 版本新增功能:
1.02 - 修改了多个错误,并在{catform}标记中,增加了扩展属性,作用于整个表单校验.新增的两个属性是flashFocus和submitOnce.
1.01 - 原始Formcat版本,支持多表单校验,提供多种校验器,对表单进行客户端校验Javascript生成.
你必须启用session.方能正常使用Formcat.在你的PHP程序最上面,使用session_start()启动
Formcat也需要Smarty模版引擎环境.
3. 安装:
安装 Formcat:
* 复制"formcat.class.php"文件和"validators" 目录(lite version 不需要复制validator目录)到你程序所能包含的目录中.
* 复制所有在"plugins"目录的文件到Smarty的plugin目录.
4. 一个简单的范例:
以下以一个简单的范例介绍Formcat所表现的能力:
index.tpl (原来文件内容)
========================
<form name="formReg" action="register.php" method="POST">
Username : <input type="text" name="username"><br>
Password : <input type="password" name="pwd"><br>
Confirm Password : <input type="password" name="pwd2"><br>
Email: <input type="text" name="email"><br>
<center><input type="submit"></center>
</form>
index.tpl (经过加入Formcat标记)
===================================
{catform form="formReg"}
<form name="formReg" action="register.php" method="POST">
Username : <input type="text" name="username">
{formcat check="notEmpty" field="username" message="You
MUST input username."}
<br>
Password : <input type="password" name="pwd">
{formcat check="notEmpty" field="pwd" message="You
MUST input password."}
<br>
Confirm Password : <input type="password" name="pwd2">
{formcat check="notEmpty" field="pwd2" message="You
MUST input confirm password."}
{formcat check="isEqual" field="pwd" field2="pwd2"
message="The password Must be same as the confirm password"}
<br>
Email: <input type="text" name="email">
{formcat check="isEmail" field="email" message="You
should input a valid email address"}
<br>
<center><input type="submit"></center>
</form>
{/catform}
index.php
=======================================
<?php
session_start();
// you will need to setup Smarty if
// the defaults are not correct.
require('Smarty.class.php');
require('formcat/formcat.class.php');
$smarty =& new Smarty;
$fc = new formcat;
$smarty->register_outputfilter(array(&$fc,'fcOutputFilter'));
$smarty->display('form.tpl');
你能查看所输出的页面的HTML源文件,校验Javascript已经生成.
II.Formcat应用于模版中
5. 概述:
Formcat标记主要有两类 {catform}{/catform} 和 {formcat} 标记
{catform}{/catform} 是一对容器(Container)标记.主要用于在一个页面中,含有多个表单,识别对应的表单.无论页面上含有一个还是多少个表单,仍然需要使用此对标记.
{catform form="formname"}.....{/catform}
对应的校验标记 {formcat ...}必须在{catform}...{/catform}
内
Catform 扩展属性:
自Formcat 1.01后，Catform 扩展属性被加入．扩展属性应用于{catform}标记中，作用于对应的整个表单，以下是扩展属性使用的例子：
范例: {catform form="login" flashFocus="TRUE" submitOnce="TRUE"}
注意 : catform扩展属性为大小写敏感,所以必须严格按照以下格式出现,方起作用.大部分扩展功能在浏览器Internet
Explorer,FireFox,Opera上测试过．不排除在其他浏览器上不能正常使用．
- flashFocus
此扩展功能主要作用于带焦点停留的检验器(validator)上．当为"TRUE"时,当错误出现,不仅焦点会停留于发生错误的输入对象上，还会带颜色闪动效果，能明显地引导用户发现哪个输入部分出现问题.闪动提示将使用两个颜色值,交替产生闪动．此扩展属性只对具备focus属性的校验器(如:notEmpty,isLength等)起作用，其他的检验器则不起任何作用.
两个交替颜色默认值,可以非常方便地修改,只需要在"formcat.class.php"的开头部分,修改$flashColor,$flashColor2两个参数颜色值即可.还值得一提的参数是$keepFlashColor(默认值:1),它决定闪动提醒完毕后,输入对象的底色保持闪动提示的颜色($flashColor2),如果为0则闪动完毕后,还原原来的底色.$keepFlashColor参数可以于"formcat.class.php"的开头部分修改.
flashFocus是一个非常醒目的焦点提醒,也是一个绝好的构思,非常感谢来自法国的用户Sylvestre Ledru先生的贡献.
eg: {catform form="form_name" flashFocus="TRUE"}
- submitOnce
此扩展功能主要是避免用户多次点击发送按钮(submit button),当属性为"TRUE"时,用户点击了发送按钮后,发送按钮将暂时失效.已避免用户因各种原因,不断点击,造成不必要的麻烦.
当用户再点击发送按钮时,会出现警告提示.此警告提示的默认信息文字,可以修改.只需要在"formcat.class.php"中修改
"$defaultSubmitOnceMsg" 参数值即可.
eg: {catform form="form_name" submitOnce="TRUE"}
6. 校验器:
校验标记全部以{formcat ...} 作为起始. {formcat ...}中还含有很多属性.但每个校验器可能有不同的属性.基本来说,大部分校验器均具备"check","field","message"
和"focus"这些属性.
除了比较特别的"isDate"和"dateCompare"这两个校验器.但还是具备"check"这个属性
公共属性(基本校验器都具备)
"field" - 指定表单中的哪个元素需要校验
"check" - 校验器名称.
"message" - 出错信息,当错误发生,会出现这个出错信息.
"focus" - 可选属性(默认:TRUE).当出现错误时,JAVASCRIPT会把焦点放在"field"指定的元素(using
javascript's .focus())
让我们看看这些校验器:
6.1 notEmpty
"notEmpty": 校验输入内容不能为空.
eg: {formcat check="notEmpty" field="fieldname"
message="..."[ focus="false"]}
6.2 isRange
"isRange":校验输入的内容的值(仅用于数值型). "min" 最小值和"max"最大值必须具备
eg: {formcat check="isRange" field="fieldname" min="3" max="8" message="..." [ focus="false"]}
6.3 isLength
"isLength":校验输入的内容的长度. "min" 最小长度和"max"最大长度属性必须具备.
eg: {formcat check="isLength" field="fieldname"
min="5" max="12" message="..."[ focus="false"]}
6.4 cboxChecked
"cboxChecked": 校验是否已选择了checkbox
eg: {formcat check="cboxChecked" field="fieldname"
message="..."}
值得注意: cboxChecked允许"fieldname"使用数组方式命名. 例如: 有若干个checkbox命名为"job[]",而formcat标记可以是:{formcat
check="cboxChecked" field="jobs[]" message="must choose
a job title!"}.
6.5 radioChecked
"radioChecked": 校验是否已选择了Radio button
eg: {formcat check="radioChecked" field="fieldname"
message="..."}
6.6 isSelected
"isSelected": 检验是否选择了下拉菜单的某项
eg: {formcat check="isSelected" field="fieldname"
index="1" message="..."}
特定的属性:
index - 开始的菜单索引值,所选项目的索引必须大于这个index值
6.7 isEmail
"isEmail": 校验输入的内容的是否为合法的email地址
eg: {formcat check="isEmail" field="fieldname" message="..."
[ focus="false"]}
6.8 isInt
"inInt" : 校验输入的内容的是否为整数
eg: {formcat check="isInt" field="fieldname" message="..."
[ focus="false"]}
6.9 isFloat
"isFloat": 校验输入的内容的是否为浮点数
eg: {formcat check="isFloat" field="fieldname" message="..."
[ focus="false"]}
6.10 isDate
"isDate": 校验输入的内容的是否为合法日期,这个校验器仅为年月日分开成三个下拉菜单而服务.
"year","month","day"分别指向三个下拉菜单的元素.
eg: {formcat check="isDate" year="year field" month="month
field" day="day field"}
6.11 isURL
"isURL": 校验输入的内容的是否为合法的URL
eg: {formcat check="isURL" field="fieldname" message="..."
[ focus="false"]}
6.12 isEqual
"isEqual":校验field输入的内容和field2输入的内容是否一致.
eg: {formcat check="isEqual" field="fieldname1"
field2="fieldname2" message="..."[ focus="false"]}
特定的属性:
field2 - "field2" 的值必须和"field"的值一致.如果"focus"为TRUE(默认为:true),焦点将放在field2
6.13 isFileSize
"isFileSize":校验上传的文件,文件大小是否在min最小值和max最大值之间.(单位:"B"为字节,"K"为千字节,"M"为兆,"G"为gigabytes)
eg: {formcat check="isFileSize" field="file fieldname"
min="1M" max="5M" message="..."[ focus="false"]}
注意: "isFileSize" 校验器使用到ActiveX控件,有可能导致用户浏览器出现安全警告,所以强烈建议你尽量减少使用本
校验器,取而代之的是SmartyValidate或者其他服务器端的校验过程.
6.14 isFileType
"isFileType"::校验上传的文件,文件扩展名是否为"type"中的一种.
eg: {formcat check="isFileType" field="file fieldname"
type="jpg,gif,bmp" message="..."[ focus="false"]}
特定的属性:
type - 允许上传的文件类别,以逗号分隔.
6.15 dateCompare
"dateCompare": 对比日期,用"after_year"-"after_month"-"after_day"减"before_year"-"before_month"-"before_day"
如果结果小于0 ,则表示出错,显示错误信息.
如果"dateEqual"属性设为TRUE.那么[after_date]必须和[before_date]一致,即判断两个日期是否为同一日.
如果"compToday"属性设为TRUE.那么[before_date]将被替换成TODAY(当前日期),然后再与[after_date]对比,即
判断[after_day]是过去的日子还是未来的日子.
eg: {formcat check="dateCompare" after_year="yrfield1"
after_month="mfield1" after_day="dfield1" before_year="yrfield2"
before_month="mfield2" before_day="dfield2" [dateEqual="TRUE"]
[compToday="TRUE"]}
6.16 isRestrict
"isRestrict": 校验输入的内容的是否含有限制的字符(单个字符)
eg: {formcat check="isRestrict" field="fieldname"
restrict="restrict letters" message="..."[ focus="false"]}
特定的属性:
restrict - 限制字母列表.例如:如果你禁止输入email地址,可以使用restrict="@",又如:你不希望输入的内容包含空格,则可以使用
restrict=" "
还值得注意的是，这个restrict属性还有两个有用的关键字
"notab" - 限制所有制表符 ("\t\n\r")
"specialchars" - 限制大部分特殊符号 (><,[]{}?/+=|\\\'\\\":;~!@#*$%^&()`)
6.17 isRegExp
"isRegExp": 校验输入的内容的是否符合expression正则表达式．
eg: {formcat check="isRegExp" field="fieldname"
expression="regex" message="..."[ reverse="TRUE"
focus="false"]}
Unique Attribute:
expression - 正则表达式
reverse - 反向运算. 默认为FALSE,输入内容不得与"expression"所指的正则表达式匹配,如果为TRUE,则输入内容必须匹配"expression"所指的正则表达式.
注意: "expression"
中的正则表达式.写的时候要注意其形式,因为Formcat是使用javascript的RegExp对象.而且需要逃离PHP的过滤.
例如:整数的正则表达式:"\\b\\d+\\b"应该在Formcat tag中写成 {formcat check="isRegExp"
field="item" expression="\\\b\\\d+\\\b" reverse="TRUE"
message="item must be integer"}
7. Synopsis:
一般来说,在PHP中,我们如下开始Formcat:
<?php
session_start(); //don't forget
require('Smarty.class.php');
require('formcat/formcat.class.php');
....
$smarty =& new Smarty;
$fc = new formcat; //create an instance of formcat
//register the formcat::fcOutputFilter as an output filter of Smarty
$smarty->register_outputfilter(array(&$fc,'fcOutputFilter'));
....
$smarty->display('form.tpl');
?>
让我们回顾一下,Formcat开始的基本步骤:
1.必须在开头使用"session_start();"开启session.
2.包含"Smarty class" and "Formcat class" 文件.
3.创建Smarty实例和Formcat实例.
4.把"Formcat::fcOutputFilter"声明成Smarty的Output filter.
如果你是高级程序员,可以试图把这些步骤包装起来.
8. 增加自定义Javascript到校验函数中
Formcat具备了经常使用的校验器.但仍然有可能在一些特殊的项目中,需要使用其他与别不同的校验程序.这时你可以使用Formcat的方法
"addCustomJs()"增加自定义脚本到对应的表单校验主函数中.
方法:
function addCustomJs($formName,$jsStr)
============================================
eg:
$customJs = "if(fc['username'].value=='joey'){\n".
"alert('....');\n return false;\n}\n";
formcat::addCustomJs('frmLogin',$customJs);
------------------------------------------------------------------
增加自定义脚本到对应的表单("$formName")校验主函数中,注意只能使用Javascript
Formcat 1.01 有两个版本,其一是"PRO version" ,其二是"Lite version".他们基本是相同,唯一分别是"Lite
version" 包含了所有校验器函数于"formcat.class.php",所以很轻便,而"PRO version"则把所有校验器函数放置在validators目录,更方便扩充.
10. 扩展formcat:
很容易简单地扩充Formcat.让我们看看如何做:
Formcat's validator functions
===============================
void js_validator_criteriaName(obj &$formcat,array $params)
所有属性会传回到$params,它作为一个数组形式出现.你可以通过$params['max']或使用extract($params)解包.
$formcat 为 formcat 对象引用.
输出内容(返回值)为生成的JAVASCRIPT
范例:
function js_validator_noWhiteSpace(&$formcat,$params){
extract($params);
$message = (empty($message))?sprintf($formcat->defaultErrMsg,$field):$message;
$formcat->addFocus($field,$focus);
if($field!=''){
$str = "\n //check whitespace\n".
"var badChar = \"" "\"\n".
"var i;\n".
"for (i = 0; i < fc['".$field."'].value.length; i++){\n".
"var c = fc['".$field."'].value.charAt(i);\n".
"if (badChar.indexOf(c)>=0) {\n".
"alert('$message');\n".
$focusStr."return false;\n".
"}\n}\n";
return $str;
}
}
如果你使用的是 "Formcat lite version"，只需要把校验器函数放入"formcat.class.php"中,相反你必须建立一个文件(以"js_validator_criteriaName.php"形式命名)放置代码,然后把文件复制到"validators"目录中.
"Formcat" 校验器标记以如下形式:
{formcat check="criteriaName" attributeName="..."
.......}
V.Credits
作者 : Joey Wong (黄俊研)
特别鸣谢:
Charlotte Chan
Messju Mohr (from Smarty forum)
Monte Ohrt (from Smarty forum)
boots (from Smarty forum)
Ganesh (from India)
Sylvestre Ledru(from France)
VI. 版权信息
Copyright(c) 2005 JUSTTO.COM(峻图科技)and Joey Wong(黄俊研). All rights
reserved.
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or (at
your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
License for more details.