Class: SForm_Elm_Select

Source Location: /SForm.php

Class SForm_Elm_Select

Class Overview

A select list

Create a select option list, such as a drop down menu. This list can have any number of options, and SForm_Elm_Select will preserve their ordering. You are encouraged to use addOptGroup() to group options together, all opt groups are moved to the bottom of the list, and will also be in the order which they were created.

This select list supports intrinsic rules, so it will ensure that the value returned by this element is one of the valid ones in the given list. There are two ways of marking a rule as invalid: If you pass 'disabled' as an attribute to addOption(), the option will not be accepted. Also, you can explicitly set an option as disabled by passing it's value to invalidOption(). This would be useful if you have an option like "Please Select From the Options Below", but you didn't want the user to selecte it.

Usage:

//Create a new select element
$dataTypeElm = new SForm_Elm_Select('dataType', 'Data Type');
//Mark create an instruction, but mark it as invalid
$dataTypeElm->addOption('Select a Data Type', -1);
$dataTypeElm->invalidOption(-1);
//Iterate over my list of data types, some of them are disabled though
//Note that the option labels are in the $typeOpt array
foreach($dataTypes as $dataType => $valid){
if($valid){
$dataTypeElm->addOption($typeOpt[$dataType], $dataType);
} else {
$dataTypeElm->addOption($typeOpt[$dataType], $dataType,
array('disabled' => 'disabled'));
}
}
//Add this select element to the form
$form->addElement($dataTypeElm);

We are not inheriting from SForm_Container because this cannot contain elements, only options and optgroups. Also, speed is an issue with this, so we'll be writing some fast(er) 'n dirty code anyway.

Located in /SForm.php [line 3849]

SForm_Element
   |
   --SForm_Elm_Select

Properties

Methods

[ Top ]

Inherited Properties, Constants, and Methods

Inherited Properties

Inherited Methods

Inherited Constants

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_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

boolean	$emptyTag	This tag contains elements
array	$inOptGrp	Hash table of the optgroups
array	$invalid	Any invalid options
array	$optGroups	Group the children as needed
array	$options	The option "children" of this element
string	$tag	Change the tag to match the element

[ Top ]

Method Summary

SForm_Elm_Select	__construct()	Options can be passed to the constructor
void	addOptGroup()	Add an optgroup.
void	addOption()	Add an option to the list
void	invalidOption()	Make an option invalid
void	lock()	Add a intrinsic rule to only accept valid options
string	toHtml()	Render the list of options as HTML
string	toString()	Show this option as a string

[ Top ]

Properties

boolean $emptyTag = false [line 3862]

This tag contains elements

API Tags:

Access:

protected

Redefinition of:

SForm_Element::$emptyTag: Is this element's tag empty?

[ Top ]

array $inOptGrp = array() [line 3903]

Hash table of the optgroups

Intended so we can lookup which option is in which group easier and faster.

API Tags:

Access:

protected

[ Top ]

array $invalid = array() [line 3883]

Any invalid options

The values of invalid options are stored as the values of this array.

API Tags:

Access:

protected

[ Top ]

array $optGroups = array() [line 3893]

Group the children as needed

The opt group attribute arrays are stored here. Note that each attribute has at least one index: its 'label'.

API Tags:

Access:

protected

[ Top ]

array $options = array() [line 3874]

The option "children" of this element

A set of arrays containing the option's attributes, and the label of the option. The label is in the first index, the attributes (if any) are in the second index as key/value pairs. Keep in mind that there aren't always attributes. If there are none, the index should not be set.

API Tags:

Access:

protected

[ Top ]

string $tag = 'select' [line 3855]

Change the tag to match the element

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 ]

Methods

Constructor __construct [line 3913]

SForm_Elm_Select __construct(
[string
$id = null], [string
$label = null], [array
$options = null], [array
$attributes = null] 
)

Options can be passed to the constructor

Parameters:

string	$id:	Local ID of this element
string	$label:	Label of this element
array	$options:	Init with these options
array	$attributes:	Any extra attributes

API Tags:

Access:

public

Redefinition of:

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

[ Top ]

addOptGroup [line 4119]

void addOptGroup(
string
$grpLabel, array
$values, [array
$attributes = array()] 
)

Add an optgroup.

First arg is the optgroup label, the second is an array of element values. No element can be in two optgroups.

Parameters:

string	$grpLabel:	Label of the optgroup
array	$values:	Values that it applies to
array	$attributes:	Additional attributes of the optgroup

API Tags:

Access:

public

[ Top ]

addOption [line 3934]

void addOption(
string
$text, [string
$value = null], [array
$attributes = null] 
)

Add an option to the list

The only required part of the option is the user-visible text. If no value is passed, the text is what will be returned by the submission. You can also pass any other attributes, such as 'selected' or 'disabled'.

Parameters:

string	$text:	Text of option
string	$value:	Value of option
array	$attributes:	Any other attributes

API Tags:

Access:

public

[ Top ]

invalidOption [line 4020]

void invalidOption(

$value 
)

Make an option invalid

This is useful for options like "Select an option from the list", where you don't want the user to select it. The value passed here is taken into account when validating the form.

Parameters:

$value:

API Tags:

Access:

public

[ Top ]

lock [line 3990]

void lock(
)

Add a intrinsic rule to only accept valid options

Add a rule to this select element which requires that we only allow valid options. This is mainly to prevent malicious coders from inserting unexpected invalid data into the script.

Example: If you have some select options disabled, the user could craft their own form with the options not disabled and submit it to your page. With this intrinsic rule in place, disabled options are automatically not valid, and will be rejected.

It can also be used to ensure that if an option list says "Please Select From the Options Below", the user does so. Otherwise the form does not validate and an error is presented to the user.

API Tags:

Access:	protected
See:	SForm_Elm_Select::$invalid
See:	SForm_Elm_Select::invalidOption()
See:	SForm_Rule_Subset

Redefinition of:

SForm_Element::lock(): Locks & adds any last minute stuff

[ Top ]

toHtml [line 4042]

string toHtml(
)

Render the list of options as HTML

Creates the list of options and wraps them in <option> tags. The list of options is created in the order that they were submitted to this form, with the optgroups at the end of the list. If any options were created without values, they will not have value tags in the option list, and the submitted form will return the text of the option is its value.

API Tags:

Return:	Output HTML
Access:	public

Redefinition of:

SForm_Element::toHtml(): Create a HTML representation of this element

[ Top ]

toString [line 4147]

string toString(
)

Show this option as a string

Customize the string value so it returns the text what the user selected and not the value of what the user selected.

API Tags:

Return:	The selected option
Access:	public

Redefinition of:

SForm_Element::toString(): How does this value look as a HTML string?

[ Top ]

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

	SForm Elements

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