Class: SForm

Source Location: /SForm.php

Class SForm

Class Overview

I am the alpha and the omega, I am the form.

The SForm is the root for all elements, and they will not fully funcion without being rooted to a SForm. All rendering operations should begin with SForm::render(), validation begins with SForm::validate(), and processing can be accomplished with SForm::toArray(). For more information on SForm usage, see the package documentation.

Located in /SForm.php [line 1668]

SForm_Element
   |
   --SForm_Container
      |
      --SForm

Author(s):

API Tags:

See:	SForm.php
See:	SForm::__construct()

Properties

Methods

[ Top ]

Inherited Properties, Constants, and Methods

Inherited Properties

Inherited Methods

Inherited Constants

Inherited From SForm_Container

SForm_Container::$chFilters

SForm_Container::$chRules

SForm_Container::$emptyTag

Inherited From SForm_Element

SForm_Element::$addName

SForm_Element::$attributes

SForm_Element::$defId

SForm_Element::$errors

SForm_Element::$filters

SForm_Element::$locked

SForm_Element::$parent

SForm_Element::$required

SForm_Element::$rules

SForm_Element::$validated

SForm_Element::$valueSet

Inherited From SForm_Container

SForm_Container::addElement()

Adds an element to this container

SForm_Container::applyFilter()

Apply a filter to the elements

SForm_Container::count()

Return number of children

SForm_Container::createElement()

Creates an element

SForm_Container::current()

Return the current element

SForm_Container::freeze()

Set the frozen status of this container and its children

SForm_Container::getChildren()

Return the current element

SForm_Container::getElement()

Returns an element using the Local ID

SForm_Container::getGlobalElement()

Returns an element using the Global ID

SForm_Container::hasChildren()

Does the current element have children?

SForm_Container::key()

Return the key of the current element

SForm_Container::lock()

Add any requested filters and rules, then lock this container

SForm_Container::next()

Advance pointer and return the new current

SForm_Container::removeElement()

Removes an element from this group

SForm_Container::render()

Render this container and all elements in it

SForm_Container::rewind()

Move the current element to the first one

SForm_Container::toHtml()

Create a HTML representation of this container

SForm_Container::valid()

Is the current ponter valid?

SForm_Container::validate()

Is this valid?

Inherited From SForm_Element

SForm_Element::__construct()

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

SForm_Element::addRule()

Add a rule to this element

SForm_Element::assignParent()

Assign this element's parent

SForm_Element::autoAK()

Generates an access key and updated label

SForm_Element::createRule()

Creates & returns a rule

SForm_Element::escHtml()

Escape HTML in a consistant manner

SForm_Element::filter()

Apply a filter to the value

SForm_Element::filterValue()

Filters the value

SForm_Element::freeze()

Set if this element is frozen

SForm_Element::getAttribute()

Get an attribute in $this

SForm_Element::getAttributesString()

Creates an HTML attribute string from an array

SForm_Element::getErrorHtml()

Do we have any errors?

SForm_Element::getGlobalId()

This is the page-wide unique ID

SForm_Element::getLabel()

Return the label string (no markup)

SForm_Element::getLabelHtml()

Return the label with markup added

SForm_Element::getLocalId()

A Locally usable ID

SForm_Element::getOption()

Get a global option

SForm_Element::getRequest()

Returns a value from the request

SForm_Element::getValue()

The value of this element

SForm_Element::isFrozen()

Is this element marked as frozen?

SForm_Element::isRequired()

Is this element required?

SForm_Element::lock()

Locks & adds any last minute stuff

SForm_Element::render()

Append this leaf element to the render queue

SForm_Element::setAttribute()

Set an attribute in $this

SForm_Element::setDefault()

Set the default value of this element

SForm_Element::setOption()

Set a global option

SForm_Element::setValue()

Set the value of this element

SForm_Element::toHidden()

Do we have any hidden tags to append?

SForm_Element::toHtml()

Create a HTML representation of this element

SForm_Element::toHtmlFin()

Close an open HTML tags

SForm_Element::toJavaScript()

Retrieve any JavaScript that should be run onsubmit

SForm_Element::toString()

How does this value look as a HTML string?

SForm_Element::unsetAttribute()

Unset an attribute

SForm_Element::validate()

Is this a valid element?

SForm_Element::wasSubmitted()

Was this form submitted?

[ Top ]

Property Summary

array	$defaults	Defaults are stored here
string	$tag	Why yes, this is a form
boolean	$trackSubmit	Are we tracking the submit?

[ Top ]

Method Summary

SForm	__construct()	Create a form
object Added	addGroup()	Create a group and add it to this form
void	addRuleDep()	Add a rule to given field(s)
void	display()	Prints this form to std out
void	enableFileUpload()	Enables file uploading
string	exportValue()	Returns an element's value
object Requested	getGlobalElement()	Get an element by its Global ID
string	getGlobalId()	All children of this form inheret their IDs from it.
mixed	getRequest()	Returns a value from the request
void	process()	Process the results of the form
void	render()	Renders a form with the provided renderer
void	setDefaults()	Set the default values of local elements
array	toArray()	Returns a nested array of all returned values
boolean	validate()	Is this valid?
boolean	wasSubmitted()	Was this form submitted?

[ Top ]

Properties

array $defaults = array() [line 1682]

Defaults are stored here

API Tags:

Usedby:	SForm::render()
Access:	protected
Deprecated:

[ Top ]

string $tag = 'form' [line 1674]

Why yes, this is a form

API Tags:

Access:

protected

Redefinition of:

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

[ Top ]

boolean $trackSubmit [line 1689]

Are we tracking the submit?

API Tags:

Access:

protected

[ Top ]

Methods

Constructor __construct [line 1738]

SForm __construct(
string
$id, [string
$method = 'post'], [string
$action = ''], [array
$attributes = null], [boolean
$trackSubmit = true] 
)

Create a form

The ID parameter sets both the Global ID and the Local ID to be the same, since we are at the top level. All children of this form will use this ID as a prefix to their Global IDs.

The method determines how we will send the data that is input. A 'get' method sends the data in the URL after a '?' and 'post' sends the data in the body of the HTTP request. An advantage of using 'get' is the results of the submission can be book marked. A disadvantage of using 'get' is that a form can be maliciously submitted without the user's knowledge by making them access the URL (ex: an embedded imag). 'get' requests are also awkward for large amounts of data.

The action is what URL to send the data to. Generally you want to send the data back to the original URL so you can continue processing it and present errors if needed.

Include extra attributes if you feel lucky.

$trackSubmit inserts an extra hidden element. If this element isn't included in the submission, it is ignored. It defaults to true. Be careful when setting this to false, because the submission may then validate without a button ever being clicked. You might want to add a required rule to prevent this from happening.

Changes from HTML_QuickForm: $target has been removed because it is not in XHTML 1.1. Use $attributes if you wish to add it back.

$action is required in XHTML 1.1, so if one isn't provided, $_SERVER ['SCRIPT_URL'] is used.

$trackSubmit has been set to true by default, because otherwise a form without required elements may validate without being submitted.

$id does not apply a 'name' attribute to the form because this is illegal in XHTML 1.1.

Parameters:

string	$id:	This form's ID
string	$method:	Method attribute of the form ('post' or 'get')
string	$action:	Action attribute of the form
array	$attributes:	Custom attributes for this form
boolean	$trackSubmit:	Track whether this form was submitted.

API Tags:

Uses:

$request

Redefinition of:

SForm_Element::__construct(): Construct with an identity. Optionally add a label and more attributes.

[ Top ]

addGroup [line 2072]

object Added addGroup(
array
$elements, [string
$id = null], [string
$label = null] 
)

Create a group and add it to this form

This is depreciated because you can just do this yourself by creating a group (or fieldset) and adding to the form via SForm::. It's less confusing, also.

Parameters:

array	$elements:	Elements in group
string	$id:	Group name
string	$label:	Group label

API Tags:

Return:	group
Access:	public
Deprecated:

[ Top ]

addRuleDep [line 1941]

void addRuleDep(
mixed
$element, string
$message, string
$type, [string
$format = ''], [string
$validation = 'server'] 
)

Add a rule to given field(s)

Please use addRule() instead. This is only here for compatability reasons.

Parameters:

mixed	$element:	Element name(s)
string	$message:	Error message
string	$type:	Type of rule
string	$format:	Extra data
string	$validation:	Where to preform validation

API Tags:

Access:	public
Deprecated:

[ Top ]

display [line 2020]

void display(
[object Renderer
$rend = null] 
)

Prints this form to std out

Parameters:

object Renderer

$rend:

to use

API Tags:

Access:

public

[ Top ]

enableFileUpload [line 2040]

void enableFileUpload(
)

Enables file uploading

This is not currently working. Please sprice@pricepages.org request if needed.

API Tags:

Access:

public

[ Top ]

exportValue [line 1920]

string exportValue(
string
$name 
)

Returns an element's value

Parameters:

string

$name:

Element to retrieve value for

API Tags:

Return:	Element's value
Access:	public
Deprecated:

[ Top ]

getGlobalElement [line 1798]

object Requested getGlobalElement(
string
$id 
)

Get an element by its Global ID

Retrieves an element based on it's Global ID. When at all possible, I'd suggest that you retrieve elements via getElement().

Parameters:

string

$id:

Global ID

API Tags:

Return:	element (or null)
Access:	public

Redefinition of:

SForm_Container::getGlobalElement(): Returns an element using the Global ID

[ Top ]

getGlobalId [line 1843]

string getGlobalId(
)

All children of this form inheret their IDs from it.

When parent::getGlobalId() is called on a child, it calls its parent's getGlobalId() method and appends the results to its own Local ID. When the calling reaches the SForm level, it's at the root and there are no more parents, so the Local ID is returned.

API Tags:

Return:	The Local and Global ID
Access:	public
Uses:	SForm_Element::getLocalId()

Redefinition of:

SForm_Element::getGlobalId(): This is the page-wide unique ID

[ Top ]

getRequest [line 2086]

mixed getRequest(
string
$val 
)

Returns a value from the request

Parameters:

string

$val:

Value to retrieve

API Tags:

Return:	Value or null
Access:	protected

Redefinition of:

SForm_Element::getRequest(): Returns a value from the request

[ Top ]

process [line 2054]

void process(
mixed
$callback 
)

Process the results of the form

This method is depreciated because it takes less code and you gain more functionality if you just call the callback function yourself. Use toArray() to get the array, then call the function. That simple.

Parameters:

mixed

$callback:

Callback function

API Tags:

Access:	public
Deprecated:

[ Top ]

render [line 1983]

void render(
SForm_Renderer
$rend 
)

Renders a form with the provided renderer

Render the form using the given renderer. If any defaults have been applied using setDefaults(), they are applied to the local elements here.

Parameters:

object The

$rend:

renderer to use

API Tags:

Access:	public
Uses:	SForm_Container::render()
Uses:	SForm::$defaults

Redefinition of:

SForm_Container::render(): Render this container and all elements in it

[ Top ]

setDefaults [line 1907]

void setDefaults(
array
$defaults 
)

Set the default values of local elements

This is here for HTML_QuickForm compatability. Please use SForm_Element::setDefault() instead. The reasoning is that all operations that are associated with perticular elements should operate on those elements, so this usage makes more sense.

Also, when using QF, I found myself simply collecting values into an array at the same layer as element creation. After the the array was completed, I had to pass it through various layers of my program to finally set the defaults. Using SForm_Element::setDefault() makes things easier, also.

Internally, element defaults are stored and set in render() using the SForm_Element::setDefault() method at render time. Any calls to SForm_Element::setDefault() will be overridden by the values in this form. The elements are retrieved using getElement(). This is due to the internal differences between QF and SForm. It doesn't mesh exactly with QuickForm, and you have been warned. Maybe you should use SForm_Element::setDefault() instead.

Parameters:

array

$defaults:

List of defaults for the elements.

API Tags:

Access:	public
Deprecated:
See:	SForm_Container::getElement()
See:	SForm::render()
See:	SForm_Element::setDefault()

[ Top ]

toArray [line 1856]

array toArray(
)

Returns a nested array of all returned values

Uses the default renderer to collect the values of all elements into an array. If objects are nested, then the array is nested also.

API Tags:

Return:	Values of this form in an array.
Access:	public
Uses:	SForm_Renderer

[ Top ]

validate [line 2011]

boolean validate(
)

Is this valid?

Validates this form. Keep in mind that no rules can be added after an element is validated because that would invalidate the validation. If there was no request submitted, it is assumed that validation is not passed.

Rules can be added via addRule().

API Tags:

Return:	Is this form valid?
Access:	public
Uses:	SForm_Container::validate()

Redefinition of:

SForm_Container::validate(): Is this valid?

[ Top ]

wasSubmitted [line 1867]

boolean wasSubmitted(
)

Was this form submitted?

API Tags:

Return:	Has it been submitted?
Access:	public

Redefinition of:

SForm_Element::wasSubmitted(): Was this form submitted?

[ Top ]

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

	SForm

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