Class: SForm_Rule

Source Location: /SForm.php

Class SForm_Rule

Class Overview

Create rules for elements

The SForm rules are very different than the QuickForm rules. Their advantages over QuickForm rules are twofold: They are designed to easily validate any number of elements simultaneously. They are also designed to throw an error (if needed) at any location in the form.

This means that you can easily create complex rules, such as validating a credit card number depnding on which type of credit card is selected. You can require a user to fill in identifying information if they don't have a user name. You can better control filling out billing vs. shipping information. You can also do any of this in JavaScript.

Much of this can even be done without defining a new class by using the SForm_Rule_Boolean to create an on-the-fly server and client side boolean statement.

Usage:

Because of the changes, the API is different. For example, this code from the original quick start guide:

$form->addElement('text', 'name', 'Enter your name:',
array('size' => 50, 'maxlength' => 255));
$form->addRule('name', 'Please enter your name', 'required', null,'client');

Can be changed into this, for the same functionality:

$form->addElement('text', 'name', 'Enter your name:',
array('size' => 50, 'maxlength' => 255));
$form->addRuleDep('name', 'Please enter your name', 'required', null,'client');

Note that in the example, addRule() has been changed to addRuleDep(), where 'Dep' stands for depriciated.

The correct SForm usage, though, is (shorthand):

$nameElm = $form->addElement('text', 'name', 'Enter your name:',
array('size' => 50, 'maxlength' => 255));
$nameElm->addRule('required', 'Please enter your name');

Or even (fully object oriented):

$nameElm = new SForm_Elm_Text('name', 'Enter your name:',
array('size' => 50, 'maxlength' => 255));
$reqRule = new SForm_Rule_Required('Please enter your name', $nameElm);
$nameElm->addRule($reqRule);
$form->addElement($nameElm);

Located in /SForm.php [line 2282]

Author(s):

API Tags:

Abstract:

Properties

Methods

[ Top ]

Direct descendents

Child Class	Description
SForm_Rule_Required	Is the given element required?
SForm_Rule_Maxlenth	Set the maximum number of chars in a value
SForm_Rule_Subset	Is the value in (or out of) this subset?
SForm_Rule_Boolean	Used to generate on-the-fly boolean rules

[ Top ]

Property Summary

static integer	$jsElmNum	The counter for temp local variables
static array	$jsElmVar	The names of local JavaScript variables
array	$elements	Which elements fall under this jurisdiction?
boolean	$hasParent	Has this rule been asigned to an element?
string	$message	NO YUO!
boolean	$validateOnClient	Should we use this rule with JavaScript?

[ Top ]

Method Summary

static string	escClient()	Escape client side variables
static string	genJSValue()	Returns JS to get a value and save it in the local variable
SForm_Rule	__construct()	Construct a rule with one element and one error message
void	assignParent()	Mark this rule as having a parent
string	createJSRule()	Create a basic if-then rule in JavaScript
void	isError()	Returns true if this element(s) fail validation
string	toJavaScript()	Get the JavaScript that should be run onsubmit
string	toString()	Returns a message describing the error and its cause
void	validateOnClient()	Should we run validation code on the client

[ Top ]

Properties

static integer $jsElmNum = 0 [line 2330]

The counter for temp local variables

API Tags:

Access:

protected

[ Top ]

static array $jsElmVar = array() [line 2323]

The names of local JavaScript variables

To save cycles and bytes, values are stored in local JavaScript variables before they are used in client side validation. This array is indexed by the Global ID, and the values are the names of the local variables.

API Tags:

Usedby:	SForm_Rule::genJSValue()
Access:	protected

[ Top ]

array $elements = array() [line 2312]

Which elements fall under this jurisdiction?

API Tags:

Access:

protected

[ Top ]

boolean $hasParent = false [line 2288]

Has this rule been asigned to an element?

API Tags:

Access:

protected

[ Top ]

string $message [line 2305]

NO YUO!

The message that is returned when an error is thrown. toHtml() can be overridden and the message made more dynamic, if desired.

API Tags:

Access:

protected

[ Top ]

boolean $validateOnClient = true [line 2295]

Should we use this rule with JavaScript?

API Tags:

Access:

protected

[ Top ]

Methods

static method escClient [line 2467]

static string escClient(
string
$str 
)

Escape client side variables

Use this to escape client side JavaScript text.

Parameters:

string

$str:

Text to escape

API Tags:

Return:	Escaped text
Access:	protected

[ Top ]

static method genJSValue [line 2494]

static string genJSValue(
SForm_Element
$elm 
)

Returns JS to get a value and save it in the local variable

Generate JavaScript code that creates a temperarory local variable. The name of the variable is stored in $jsElmVar, and can be used in by other functions as needed.

NOTE: This must be called for an element before the variable name in $jsElmVar can be used. Otherwise, there will be no entry in the array.

This will save some browser cycles when we don't need to index into the array for each usage. It will also save some bytes in the script so the same huge ID strings aren't repeated.

This will generate different code depending on the type of element used, some types of elements make it difficult to find their value in JavaScript.

Parameters:

object The

$elm:

object to get a value for

API Tags:

Return:	JavaScript code that saves the value in a local variable
Access:	protected
Uses:	SForm_Rule::$jsElmVar

[ Top ]

Constructor __construct [line 2356]

SForm_Rule __construct(
string
$message, SForm_Element
$element 
)

Construct a rule with one element and one error message

The first argument is always the error message, and the second argument is always an element or array of elements (as appropriate).

The elements passed here are not necessarily the element that validates this rule and throws an error message. This way, the rule can validate two or more fields in a group, but the error appears in the group. This rule will later be added to said element or container with SForm_Element::addRule().

By default, the message is static, but you are encouraged to create dynamic messages that address the specific error and element via SForm_Element::getValue() and SForm_Element::getLabel() respectively. Make sure, though, that messages still work on both the server side and client side.

The default usage of this rule only applies to one element, but it is designed to apply to any number of elements.

Parameters:

string	$message:	Default error message
object Element	$element:	to validate

Redefined in descendants as:

SForm_Rule_Maxlenth::__construct() : Setup client side checking
SForm_Rule_Subset::__construct() : Construct this rule
SForm_Rule_Boolean::__construct() : Create a free form boolean rule

[ Top ]

assignParent [line 2379]

void assignParent(
SForm_Element
$elm 
)

Mark this rule as having a parent

Each rule should be applied to one and only one element. This is done so we can evaluate each rule once and only once. This also applies for rendering JavaScript and generating error messages. Each rule can validate more than one element, but that is handled within the rule, not within the element.

Parameters:

object Parent

$elm:

of this rule

API Tags:

Usedby:	SForm_Element::addRule()
Access:	public
See:	SForm_Element::addRule()

[ Top ]

createJSRule [line 2449]

string createJSRule(
string
$jsPrefix, string
$jsTest 
)

Create a basic if-then rule in JavaScript

This serves as glue for most JavaScript rules. It should be fed a prefix that sets up a test, and the boolean test itself. If the test is found to be true, an error message is created an the offending element is flagged.

Parameters:

string	$jsPrefix:	JS code to be run before the test
string	$jsTest:	JS code that evaluates to true on error

API Tags:

Return:	Full JS test
Access:	protected

[ Top ]

isError [line 2407]

void isError(
boolean
0 
)

Returns true if this element(s) fail validation

Parameters:

boolean

Are the element values valid?

API Tags:

Access:	public
Abstract:

Redefined in descendants as:

SForm_Rule_Required::isError() : Does the element have a value?
SForm_Rule_Maxlenth::isError() : Is it too long?
SForm_Rule_Subset::isError() : Is the value in the set?
SForm_Rule_Boolean::isError() : Does the statement evaluate to true?

[ Top ]

toJavaScript [line 2436]

string toJavaScript(
)

Get the JavaScript that should be run onsubmit

This can be anything, but is generally a validation rule set up as an if- then statement. This code should be called by the Renderer, and is typically not directly accessed by users.

First a prefix is computed that sets up any needed calculations. A common example of this is retrieving the value of the element that you wish to test. If you are coding a new rule, take a look at genJSValue() because it will save the value into a local variable for you. The name of the generated variable is stored in $jsElmVar, and is indexed by the Global ID of the element.

The next part is the boolean test. Normally, an error is thrown if the test is true. A simple example would be "_name == ''". This detects whether there is a value stored in an element.

The last part of the rule is flagging the error in the JavaScript. This should be as simple as appending the error message and flagging the error in errFlag[]. This part is done for you in createJSRule().

API Tags:

Return:	JavaScript code
Access:	public
Usedby:	SForm_Element::toJavaScript()
Abstract:
See:	SForm_Rule::createJSRule()
See:	SForm_Rule::genJSValue()
See:	SForm_Rule::createJSRule()

Redefined in descendants as:

SForm_Rule_Required::toJavaScript() : Generate JavaScript to determine if there is a value
SForm_Rule_Maxlenth::toJavaScript() : Generate JavaScript to determine if the value is too long
SForm_Rule_Subset::toJavaScript() : Generate JS to find if the value is in the set
SForm_Rule_Boolean::toJavaScript() : Generates JS that will execute the boolean statement

[ Top ]

toString [line 2521]

string toString(
)

Returns a message describing the error and its cause

I'd encourage you to customize this function to explicitly state what element is causing the problem and how to remove it. Make sure that the error message isn't too long, though.

API Tags:

Return:	An error message
Access:	public

[ Top ]

validateOnClient [line 2398]

void validateOnClient(

$bool 
)

Should we run validation code on the client

This will enable or disable running JavaScript validation code on the client for this rule. By default, validation code is run. Rules that generate quite a bit of code or require a server connection (like a database) should be run only on the server.

Parameters:

$bool:

API Tags:

Access:

public

[ Top ]

Documentation generated on Mon, 09 Apr 2007 19:08:49 -0500 by phpDocumentor 1.3.0

	SForm Rules

[ class tree: SForm ] [ index: SForm ] [ all elements ]