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.
Located in /SForm.php (line 145)
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 |
Number the elements if not given an ID
Should we add the 'name' attribute?
Attributes for this tag
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>'.
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.
A list of filter callbacks
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.
What is the parent to this element?
This points to some subclass of SForm_Container. It is set in SForm_Container::addElement().
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.
Rules to apply to this element
This is the element's tag ('input', 'select', 'form', etc) and should be set by the children as needed.
Has this element been validated?
Validated elements have a finished $errors array and will not be validated again.
Has the value for this element been set?
Escape HTML in a consistant manner
Creates an HTML attribute string from an array
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.
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.
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.
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.
Assign this element's parent
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.
Creates & returns a rule
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.
Filters the value
Filters a value that is about to be returned from getValue().
Set if this element is frozen
Get an attribute in $this
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.
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 the label string (no markup)
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.
A Locally usable ID
The local ID is the name that a parent uses to identify its child element.
Returns a value from the request
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.
Is this element marked as frozen?
Is this element required?
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.
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()).
Set an attribute in $this
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.
Set the value of this element
This sets the current value of the element, overriding any current value.
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.
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.
Close an open HTML tags
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.
How does this value look as a HTML string?
Unset an attribute
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.
Was this form submitted?
Documentation generated on Mon, 23 Oct 2006 09:27:42 -0500 by phpDocumentor 1.3.0