Class SForm_Element

Description

A element is a "leaf" that is actually rendered

All elements and containers are decendents of this class. That said, this class is intended to cover as much common functionality as possible.

  • abstract:
  • access: public

Located in /SForm.php (line 145)


	
			
Direct descendents
Class Description
SForm_Container A container holds one or more elements
SForm_Elm_Hidden The hidden element
SForm_Elm_Checkable A base for checkbox or radio elements
SForm_Elm_Text A text element
SForm_Elm_Textarea A textarea element
SForm_Elm_Button A button element
SForm_Elm_Select A select list
SForm_Elm_Header A header element
Variable Summary
static integer $defId
boolean $addName
array $attributes
boolean $emptyTag
array $errors
array $filters
boolean $locked
object $parent
boolean $required
array $rules
string $tag
boolean $validated
boolean $valueSet
Method Summary
static string escHtml (string $str)
static string getAttributesString (array $attributes)
static string getOption (string $name)
static void setOption (string $name, string $value)
SForm_Element __construct ([string $id = null], [string $label = null], [array $attributes = null])
object The addRule (mixed $rule, [ $message = null], [ $arg2 = null], [ $arg3 = null], [ $arg4 = null], [ $arg5 = null], [ $arg6 = null])
void assignParent (SForm_Container $parent)
mixed autoAK (string $lbl, string $ak)
object Created createRule (string $rule, [string $message = null], [ $arg2 = null], [ $arg3 = null], [ $arg4 = null], [ $arg5 = null], [ $arg6 = null])
void filter (mixed $callback)
string filterValue ( $val)
void freeze ([boolean $bool = true])
string getAttribute (string $attr)
string getErrorHtml ()
string getGlobalId ()
string getLabel ()
void getLabelHtml ([mixed $accesskey = true])
string getLocalId ()
mixed getRequest (string $val)
mixed getValue ()
boolean isFrozen ()
boolean isRequired ()
void lock ()
void render (SForm_Renderer $rend)
void setAttribute (string $attr, [string $value = null])
void setDefault (string $value)
void setValue (string $value)
string toHidden ()
string toHtml ()
string toHtmlFin ()
string toJavaScript ()
string toString ()
void unsetAttribute (string $attr)
boolean validate ()
boolean wasSubmitted ()
Variables
static integer $defId = 0 (line 305)

Number the elements if not given an ID

  • access: protected
boolean $addName = true (line 171)

Should we add the 'name' attribute?

  • access: protected

Redefined in descendants as:
array $attributes = array() (line 312)

Attributes for this tag

boolean $emptyTag = true (line 164)

Is this element's tag empty?

A tag is empty if it can't contain elements. Examples of empty tags include '<input />' and '<img />'. Non-empty tags include '<form>' and '<fieldset>'.

  • access: protected

Redefined in descendants as:
array $errors = array() (line 269)

What were the results of the validation?

All error strings returned by validation are saved here. If there is no error string, then there was no error.

  • access: protected
array $filters = array() (line 277)

A list of filter callbacks

boolean $locked = false (line 234)

Are the rules & filters prevented from being modified?

When the rules are rendered (or otherwise used), they are locked to prevent someone from adding an additonal rule. This would invalidate any calculations done using the previous ruleset.

object $parent = null (line 181)

What is the parent to this element?

This points to some subclass of SForm_Container. It is set in SForm_Container::addElement().

boolean $required = false (line 245)

Is this a required element?

If an element is marked as required, the 'required' rule is added at render time and modifications can be made to the label HTML which mark this element as required.

array $rules = array() (line 223)

Rules to apply to this element

  • access: protected
string $tag = 'input' (line 153)

This is the element's tag ('input', 'select', 'form', etc) and should be set by the children as needed.

  • access: protected

Redefined in descendants as:
boolean $validated = false (line 255)

Has this element been validated?

Validated elements have a finished $errors array and will not be validated again.

  • access: protected
boolean $valueSet = false (line 188)

Has the value for this element been set?

Methods
static escHtml (line 938)

Escape HTML in a consistant manner

  • return: Text HTML escaped
  • access: public
static string escHtml (string $str)
  • string $str: Text to escape
static getAttributesString (line 924)

Creates an HTML attribute string from an array

  • return: HTML string
  • access: protected
static string getAttributesString (array $attributes)
  • array $attributes: Attributes as: attribute => value
static getOption (line 868)

Get a global option

All available options are pre-set in the $options array, so we will be avoiding some frusteration if we throw an error on a bad option selection. Otherwise, we could think that we are retrieving a null value, but we have just misspelled the index.

  • return: Option value
  • access: public
  • uses: $options
static string getOption (string $name)
  • string $name: Option name
static setOption (line 848)

Set a global option

All available options are pre-set in the $options array, so we will be avoiding some frusteration if we throw an error on a bad option selection. Otherwise, we could think that we are retrieving a null value, but we have just misspelled the index.

  • access: public
  • uses: $options
static void setOption (string $name, string $value)
  • string $name: Option name
  • string $value: Option value
Constructor __construct (line 399)

Construct with an identity. Optionally add a label and more attributes.

$id is the Local ID of this element, and is similar to its name. If none is supplied, one will be created. The Local ID is different than the 'id' attribute that appears in the rendered form. The id attribute is referred to as the Global ID, and is the concatenation of the parent's Global ID, a colon, and this Local ID. The ID must contain only chars acceptable in the ID SGML token for the resulting page to be valid.

The $label is the the short string that describes this element. If it is rendered as HTML, it will automatically be enclosed in '<label>' tags which referr to the Global ID of this element. If enabled, an appropriate access key will also be found for this element. The access key will be rendered with '<span class="ak">' and '</span>' tags surrounding it. If you wish to communicate with your users that this access key may be used to access this field, I suggest that you use CSS like: '.ak{text- decoration:underline;}'.

Any additonal $attributes may be added and will be displayed when the element is rendered as HTML.

SForm_Element __construct ([string $id = null], [string $label = null], [array $attributes = null])
  • string $id: Local ID of this element
  • string $label: Textual label for this element
  • array $attributes: Array of extra attributes

Redefined in descendants as:
addRule (line 979)

Add a rule to this element

A rule assigned to this element will be controled by this element. All validation will come through this element, and any errors will be returned via this element. All JavaScript will also be transmitted via this element.

If the first argument is a rule object, it will simply be added to this element. If it is a string, it is assumed that you want to create a rule which is linked to this element.

Each rule can only be assigned to one element, but that element does not need to be used by the rule. For example: an element might validate two elements in a group, but if the element is added to the group, then any errors will be displayed at the group level.

object The addRule (mixed $rule, [ $message = null], [ $arg2 = null], [ $arg3 = null], [ $arg4 = null], [ $arg5 = null], [ $arg6 = null])
  • mixed $rule: The rule to add
  • $message
  • $arg2
  • $arg3
  • $arg4
  • $arg5
  • $arg6
assignParent (line 1159)

Assign this element's parent

void assignParent (SForm_Container $parent)
  • object Parent $parent: to assign
autoAK (line 591)

Generates an access key and updated label

Uses an access key to generate a marked up label.

If access key is simply true, it generates an access key by searching through the chars of the label for the first one that is a regular char ([a-z0- 9]) and is not already in use. If none are found, numbers starting from the left side of the std keyboard are used.

  • return: Array of updated label if possible, null otherwise
  • usedby: SForm_Element::getLabelHtml()
  • access: protected
  • uses: markupLabelAK() - Markup the label with the found key
  • uses: $accesskeys - Determine which keys are used
mixed autoAK (string $lbl, string $ak)
  • string $lbl: Label
  • string $ak: Requested access key
createRule (line 1019)

Creates & returns a rule

  • return: rule
  • access: protected
object Created createRule (string $rule, [string $message = null], [ $arg2 = null], [ $arg3 = null], [ $arg4 = null], [ $arg5 = null], [ $arg6 = null])
  • string $rule: Name of the rule
  • string $message: Error message for the rule
  • $arg2
  • $arg3
  • $arg4
  • $arg5
  • $arg6
filter (line 1063)

Apply a filter to the value

This is passed a callback function which applies some sort of filter to any value returned from getValue(). Any additonal arguments to this function will be appended to the arguments of the callback function.

This cannot be called after validate() or render(), because the element is locked.

  • access: public
void filter (mixed $callback)
  • mixed $callback: Callback function
filterValue (line 501)

Filters the value

Filters a value that is about to be returned from getValue().

string filterValue ( $val)
  • $val
freeze (line 1128)

Set if this element is frozen

void freeze ([boolean $bool = true])
  • boolean $bool: Is it frozen?

Redefined in descendants as:
getAttribute (line 909)

Get an attribute in $this

string getAttribute (string $attr)
  • string $attr: Attribute to get
getErrorHtml (line 1080)

Do we have any errors?

Did this element's validation generate any errors? If it did, return those errors as an HTML string. Each error is seperated by a '
' tag.

  • return: Any errors that were produced
  • access: public
string getErrorHtml ()
getGlobalId (line 443)

This is the page-wide unique ID

The Global ID is a page-unique id which is a concatination of the parent's Global ID, a colon, and the Local ID. This is done so that element groups can be nested arbitrarily deeply with non-uniqe IDs (ex: an array: '0','1','2'...).

The Global ID is used as the 'id' HTML attribute and is typically also used as the 'name' attribute.

The Global ID cannot be determined until the element is "rooted" to a SForm object.

  • return: A globally usable ID
  • access: public
string getGlobalId ()

Redefined in descendants as:
getLabel (line 687)

Return the label string (no markup)

  • return: The raw label
  • access: public
  • uses: $label
string getLabel ()

Redefined in descendants as:
getLabelHtml (line 649)

Return the label with markup added

Generates the marked up 'label' tag. This includes the 'for' attribute, which links this label to the appropriate form element. The label allows software (and the people who use it) to understand the layout of your form without being able to view it. If the element is required, the value of option 'requiredSym' is appended to the beginning of the label.

If requested, an access key is generated, and added to the tag. The access key links this label to a specific element. Not only does an access key make the page more friendly for people with motor disabilities, it will now be easier to quickly navigate the fields in your form for data entry.

Access keys can be enabled, set, or disabled via the passed parameters. By default, $ak is true and an access key is generated. If a char is passed, that char is used as the access key and the label is marked up approriately. If false is passed, no access key is used.

void getLabelHtml ([mixed $accesskey = true])
  • mixed $accesskey: Do we automatically generate an access key?

Redefined in descendants as:
getLocalId (line 465)

A Locally usable ID

The local ID is the name that a parent uses to identify its child element.

string getLocalId ()
getRequest (line 1173)

Returns a value from the request

  • return: Value or null
  • access: protected
mixed getRequest (string $val)
  • string $val: Value to retrieve

Redefined in descendants as:
getValue (line 480)

The value of this element

The value returned is the same as if the form was rendered, displayed, then submitted by the user, in its current state.

mixed getValue ()
isFrozen (line 1138)

Is this element marked as frozen?

  • return: Is this element frozen?
  • access: public
  • uses: $frozen
boolean isFrozen ()
isRequired (line 1148)

Is this element required?

boolean isRequired ()
lock (line 701)

Locks & adds any last minute stuff

This is here to be overridden as needed by subclasses to add any rules, filters, and values immidiately before they are locked. Remember to check if it's already locked first, because an element may be locked more than once.

void lock ()

Redefined in descendants as:
render (line 953)

Append this leaf element to the render queue

The renderer is passed to this element so it can call whichever method is wanted. (ie: toHtml(), toJavaScript(), and/or toString()).

void render (SForm_Renderer $rend)
  • object The $rend: renderer to use

Redefined in descendants as:
setAttribute (line 883)

Set an attribute in $this

void setAttribute (string $attr, [string $value = null])
  • string $attr: Attribute to set
  • string $value: Value to set (sets value = attribute if null)
setDefault (line 533)

Set the default value of this element

This sets the default value of this element. If there is a user-submitted value or a setValue(), it overrides this one.

void setDefault (string $value)
  • string $value: Element's value.

Redefined in descendants as:
setValue (line 519)

Set the value of this element

This sets the current value of the element, overriding any current value.

void setValue (string $value)
  • string $value: Element's value.
toHidden (line 808)

Do we have any hidden tags to append?

Append hidden tags seperately from regular HTML tags so they can be collected at the end of the form. That way the visible part of the form is parsed and displayed to the user first.

By default, hidden elements are only generated when this element is frozen.

string toHidden ()

Redefined in descendants as:
toHtml (line 754)

Create a HTML representation of this element

Creates a HTML tag appropriate to input a value for this element. At minimum, 'id' and 'name' attributes are included. Additonal attributes can be added via the methods appropriate for the element. Custom attributes can be added via setAttribute().

If this element is frozen, the string representation is returned instead of an input field.

string toHtml ()

Redefined in descendants as:
toHtmlFin (line 787)

Close an open HTML tags

string toHtmlFin ()

Redefined in descendants as:
toJavaScript (line 726)

Retrieve any JavaScript that should be run onsubmit

Locks the rules and iterates through them to produce a JavaScript string appropriate to be run on submission of the form.

string toJavaScript ()
toString (line 832)

How does this value look as a HTML string?

string toString ()

Redefined in descendants as:
unsetAttribute (line 898)

Unset an attribute

void unsetAttribute (string $attr)
  • string $attr: Attribute to unset
validate (line 1102)

Is this a valid element?

Performs server side validation using any of the added rules. Calls lock() to provide a chance to load any intrinsic rules.

boolean validate ()

Redefined in descendants as:
wasSubmitted (line 1187)

Was this form submitted?

  • return: Has it been submitted?
  • access: public
boolean wasSubmitted ()

Redefined in descendants as:

Documentation generated on Mon, 23 Oct 2006 09:27:42 -0500 by phpDocumentor 1.3.0