Formcat class for PHP
V1.01 Jan 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官方网站 Smarty官方网站 SmartyValidate
简介
I.旅程开始
1.什么是Formcat
2.需求
3.安装
4.一个简单范例
II.Formcat应用在模版
5.概述
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.版权信息
I. 旅程开始.
1. 什么是Formcat
"Formcat",是聪明的小猫,:).一个表单客户端校验插件.当你使用"Formcat"后,你不需要再编写大量的脚本去校验表单输入的内容.
"再见了繁琐耗时的任务,Formcat Go Go GO!".
你必须启用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}
内
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(array $params)
所有属性会传回到$params,它作为一个数组形式出现.你可以通过$params['max']或使用extract($params)解包.
输出内容(返回值)为生成的JAVASCRIPT
范例:
function js_validator_noWhiteSpace($params){
extract($params);
$message = (empty($message))?sprintf($this->defaultErrMsg,$field):$message;
$focusStr = ($focus===false || $focus=='false' || $focus=='FALSE') ?'':'fc.'.$field.".focus();\n";
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)
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.