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)先生開發的類(class).主要用于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生成.

2. 需求:

你必須啟用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先生的貢獻.

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

IV. 自定義校驗器:

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)解包.

輸出內容(返回值)為生成的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 (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.