Class WFWidget

Description
Description | Descendents | Vars (details) | Methods (details)

The base "widget" class. In our framework, all html form widgets are necessarily WFWidget subclasses.

Widgets are WFView subclasses that add capabilities such as state maintainance/restoration, error tracking, formatters, and editability.

SUBCLASSING GUIDE: Very important instructions on subclassing WFWidget should be put here. The basics for now, if your widget is simple, you get bindings for free. Just write restoreState() if needed, and implement canPushValueBinding(). Oh yeah, and one more thing, ALWAYS get/set the value directly via $this->value or $this->value = $newValue. If you call value() or setValue($newValue), the formatters will run again and probably goof up your data.

Each subclass can also set up a list of its bindable properties and binding options. This is done by implementing the setupExposedBindings() method. It's quite easy to view the binding setup for a widget, just cd to the framework/ directory and run:

php showBindings.php WFWidgetSubclass

And you will see a nicely formatted list of all available bindings and options.

Formatter support: Using value(), setValue() will provide automatic formatter support. Generally, the idea is that setValue() will take the passed "raw" value and convert it into the "formatted" value. The $value member thus should always contain the "formatted" representation if the widget is using a formatter. Conversely, value() will take the "formatted" representation stored internally and turn it back into a "raw" value.

  • todo:

    Should the class property be moved up to WFView? Probably yes

    Implements: WFKeyValueBindingCreation

    • Provides a base implementation of bindings support.

  • abstract:

Located in /framework/widgets/WFWidget.php (line 44) 

WFObject
   |
   --WFView
      |
      --WFWidget
Direct descendents
Description | Descendents | Vars (details) | Methods (details)
Class Description
WFAppcelerator This widget is an Appcelerator (http://appcelerator.org) container.
WFBreadCrumb A breadcrumb widget for our framework.
WFBulkUpload A Bulk Upload widget for our framework.
WFCheckbox A Checkbox widget for our framework.
WFCheckboxGroup The WFCheckboxGroup is the "interface" object used to interact with a set of WFCheckbox widgets.
WFDieselFacet A Dieselpoint Facet widget for our framework.
WFDieselKeyword A Dieselpoint Keyword search widget for our framework.
WFDieselNav The Dieselpoint Faceted Navigation UI placeholder.
WFDynamic A Dynamic widget for our framework. The dynamic widget is a meta-widget that automatically creates multple widgets for you, based on an array controller.
WFDynarchMenu A Menu widget for our framework. Uses Dynarch Menu.
WFForm A wrapper for HTML Form Elements.
WFHidden A Hidden widget for our framework.
WFHTMLArea A HTML WYSIWYG Editor widget for our framework.
WFImage An Image widget for our framework.
WFLabel A Label widget for our framework.
WFLink A Link widget for our framework.
WFMessageBox A Label widget for our framework.
WFModuleView The WFModuleView allows for the easy inclusion of module/page based components in your template.
WFPaginatorNavigation A Paginator Navigation widget for our framework.
WFPaginatorSortLink A Paginator sort link widget.
WFPaginatorSortSelect A Paginator sort select widget.
WFPaginatorState A special form field used in conjuction with WFPagination in MODE_FORM.
WFPassword A Password widget for our framework.
WFRadio A Radio Button widget for our framework.
WFRadioGroup The WFRadioGroup is the "interface" object used to interact with a set of WFRadio widgets.
WFSelect A Select widget for our framework.
WFSubmit A Submit widget for our framework.
WFTabView The WFTabView widget provides a tabbed-interface wrapper around several templates.
WFTextArea A TextField widget for our framework.
WFTextField A TextField widget for our framework.
WFUpload A Upload widget for our framework.
WFYAHOO A YAHOO base class for our framework.
Variable Summary
Description | Descendents | Vars (details) | Methods (details)
array $bindings
string $class
array $errors
mixed $formatter
boolean $hasRestoredState
boolean $hidden
string $name
mixed $value
string $widgetLabel
Method Summary
Description | Descendents | Vars (details) | Methods (details)
static void exposedProperties ()
WFWidget __construct ( $id,  $page)
void addError ( $theError)
void addErrors ( $arr)
void bind ( $bindLocalProperty,  $bindToObject,  $bindToKeyPath, [ $options = NULL])
object WFBinding bindingByName (string $bindingName)
array bindings ()
boolean canPushValueBinding ()
array errors ()
void exposedBindings ()
mixed formattedValue (string $string)
object A formatter ()
boolean hasRestoredState ()
boolean hidden ()
string name ()
void processBindingOptions (string $boundProperty, assoc_array $options, reference &$boundValue)
mixed propagateValueToBinding (string $bindingName, mixed $value)
void pullBindings ()
void pushBindings ()
void restoreState ()
void setFormatter (object A $formatter)
void setHidden (boolean $hidden)
void setName (string $name)
array setupExposedBindings ()
void setValue (mixed $value)
void setWidgetLabel (string $widgetLabel)
void unbind ( $bindLocalProperty)
mixed value ()
mixed valueForBinding ( $prop,  $binding)
* widgetLabel ()
Variables
Description | Descendents | Vars (details) | Methods (details)
array $bindings (line 53)
  • var: All of the bound properties for the widget.
  • access: protected
string $class (line 84)
  • var: The css class to use for the item.
  • access: protected
Redefined in descendants as:
array $errors (line 57)
  • var: An array of WFError objects containing a list of all errors in the form.
  • access: protected
mixed $formatter (line 65)

The WFFormatter subclass to use to format the data, or NULL to not use one.

  • access: protected
boolean $hasRestoredState (line 61)
  • var: Has the widget restored its state from the form data yet?
  • access: protected
boolean $hidden (line 80)
  • var:

    Whether or not the widget is hidden. Hidden controls WILL NOT BE IN THE HTML OUTPUT.

    If you want to hide content related to a widget that should also be hidden if the widget is hidden, see smarty_block_WFViewHiddenHelper.

    If you are looking for the Hidden HTML input type, see WFHidden.

  • todo: Should this be moved up into WFView? If so, make sure block.WFViewHiddenHelper.php still works.
  • access: protected
string $name (line 49)
  • var: The name of the widget. Used as the HTML name.
  • access: protected
mixed $value (line 70)
  • var: The VALUE of the widget. Various subclasses will have different meanings for it, but it is part of our WFWidget so that we can automatically deal with formatters.
  • access: protected
string $widgetLabel (line 89)
  • var: The label for this widget.
  • see: WFWidgets::setWidgetLabel()
  • access: protected

Inherited Variables

Inherited from WFView

WFView::$children
 WFView::$cssImports
 WFView::$enabled
 WFView::$id
 WFView::$importInHead
 WFView::$jsActions
 WFView::$jsEvents
 WFView::$jsImports
 WFView::$originalOnEvent
 WFView::$page
 WFView::$parent
Methods
Description | Descendents | Vars (details) Methods (details)
static method exposedProperties (line 111)
  • access: public
static void exposedProperties ()
Redefinition of:
WFView::exposedProperties()
Redefined in descendants as:
Constructor __construct (line 96)

Constructor.

Sets up the smarty object for this module.

WFWidget __construct ( $id,  $page)
  • $id
  • $page
Redefinition of:
WFView::__construct()
Constructor.
Redefined in descendants as:
addError (line 550)

Our WFWidgets can keep track of all errors that occurred when processing their values. This allows you to add an error to the widget.

void addError ( $theError)
  • object A $theError: WFError object describing the error.
addErrors (line 561)
void addErrors ( $arr)
  • $arr
bind (line 283)

Set up a binding.

void bind ( $bindLocalProperty,  $bindToObject,  $bindToKeyPath, [ $options = NULL])
  • $bindLocalProperty
  • $bindToObject
  • $bindToKeyPath
  • $options
bindingByName (line 747)

Get the binding for a particular local property on this object instance.

  • return: The WFBinding for this instance on the local property passed, or NULL if there is no binding.
object WFBinding bindingByName (string $bindingName)
  • string $bindingName: The local property to get the binding for.
bindings (line 736)

Get all bindings for this object instance.

  • return: An array of attached bindings for this instance.
array bindings ()
canPushValueBinding (line 678)

Does this widget use the "value" binding to WRITE data back to the bindings?

If the control is non-editable, client should return FALSE.

If the control is editable, and you only use the built-in value property, then subclasses should return TRUE.

If the control is editable, and the subclass does not make use of the built-in value property, then should return FALSE.

NOTE: this callback is used *instead* of the read-only setting of the binding setup for the "value" binding only. This is a special case for the "value" property of WFWidget so that WFWidget subclasses can easily make themselves read-only without looking for their binding setup and editing the read-only attribute.

NOTE: contrast this with the WFView::$enabled setting. The canPushValueBinding setting is an inherent property of the widget class; enabled is a setting that is toggleable at runtime.

  • return: Return TRUE to have the base WFWidget class automatically push your 'value' binding. FALSE to skip pushing bindings for the "value" property.
  • abstract:
boolean canPushValueBinding ()
Redefined in descendants as:
errors (line 573)

Retrieve all errors for this widget.

  • return: An array of WFError objects.
array errors ()
exposedBindings (line 243)

Get a list of all exposed bindings. If a subclass has overridden a bindable property, the definition from the subclass will be used.

void exposedBindings ()
formattedValue (line 202)

Get the formatted value for the passed string.

If there was an error in the formatting, we return NULL as a flag so the caller knows that no value could be determined.

  • return: The value from the formatter, if there is one, or the original otherwise.
  • access: protected
mixed formattedValue (string $string)
  • string $string: The string from the UI.
formatter (line 234)

Retreive the formatter for this widget.

object A formatter ()
hasRestoredState (line 619)

Returns whether or not the control has already restored its UI state with restoreState().

If the value is TRUE, means that the control has already ATTEMPTED to restore state. It may not have found any state, though.

  • return: TRUE if it has already restored the state, FALSE otherwise.
boolean hasRestoredState ()
hidden (line 167)

Get whether or not the widget should be hidden.

Hidden widgets simply do not appear in the HTML output.

  • return: Whether or not to hide the widget.
boolean hidden ()
name (line 593)

Get the name of the widget.

  • return: The name of the widget.
string name ()
processBindingOptions (line 541)

Pass the list of binding options to the subclass for modification of the value.

The default implementation currently makes NO changes. In the future, if there are any bindings options shared by all, they will be processed here.

void processBindingOptions (string $boundProperty, assoc_array $options, reference &$boundValue)
  • string $boundProperty: The name of the bound property being processed.
  • assoc_array $options: The binding options for this binding.
  • reference &$boundValue: A referene to the bound value, so that you can change it based on options as needed.
Redefined in descendants as:
propagateValueToBinding (line 696)

Propagate the value from the UI widget to the bound object.

This method will automatically call the validator for the binding, if it exists. If the value is valid, it will also push the value onto the bound object with setValueForKeyPath.

Any validation errors are stored in the widget's error list.

If the value of the widget is equivalent to an empty string ($value === '') then value is converted into PHP NULL. Since all values in widgets come from the UI, and there is no distinction in the UI world b/w "" and NULL, we normalize all "" values to NULL. It is left up to objects to then distinguish between NULL and "" (via normalization in Key-Value Validation).

  • return: The cleaned-up value from validateValueForKeyPath()
mixed propagateValueToBinding (string $bindingName, mixed $value)
  • string $bindingName: The name of the binding to propagate back to the bound object.
  • mixed $value: The value from the UI widget (submitted by the form).
pullBindings (line 406)

Go through all bindings and pull the values into our widget.

Will give the class an option to modify the bound value based on all binding options.

void pullBindings ()
pushBindings (line 633)

Each widget should implement this callback if there are any bindable properties whose values are to be propagated back to the bound objects.

For each bound property, use the propagateValueToBinding method to perform validation and propagate the value back to the bound object. Don't forget that the value may be cleaned up by propagateValueToBinding and that you should update the value(s) of your widget so that it will reflect the the new value if it was edited.

The default implementation of pushBindings() only works for "value". If a widget needs to push a value via bindings to other properties, he should override pushBindings().

void pushBindings ()
Redefined in descendants as:
restoreState (line 607)

Restore the UI state of this widget from the $_REQUEST data.

Subclasses should impement this to make their widgets stateful. Subclasses should call the SUPER method.

IMPORTANT!!! This method is ONLY FOR RESTORING THE VALUE OF THE WIDGET FROM THE FORM DATA!!!

  • see: pushBindings For information about how bound values are propagated back to the bound objects.
void restoreState ()
Redefined in descendants as:
setFormatter (line 223)

Attach a formatter to the widget.

void setFormatter (object A $formatter)
  • object A $formatter: WFFormatter object.
Redefined in descendants as:
setHidden (line 155)

Set whether or not the widget should be hidden.

Hidden widgets simply do not appear in the HTML output.

void setHidden (boolean $hidden)
  • boolean $hidden: Whether or not to hide the widget.
setName (line 583)

Set the HTML 'name' of the widget.

void setName (string $name)
  • string $name: The name of the HTML widgets. Where appropriate, subclasses should use the name in their output.
setupExposedBindings (line 265)

Set up all exposed bindings for this widget.

The default implementation sets up bindings available for all WFWidgets. Subclasses must call super method.

array setupExposedBindings ()
Redefined in descendants as:
setValue (line 124)

Set the value used by the widget.

Subclasses that use value, setValue automatically get formatter support.

void setValue (mixed $value)
  • mixed $value: The value used by the widget.
Redefined in descendants as:
setWidgetLabel (line 179)

Set the "label" used for this widget field.

The label is the "field label" that describes the widget. Used primarly by WFAutoForm.

void setWidgetLabel (string $widgetLabel)
  • string $widgetLabel: The label for this widget.
unbind (line 336)

Set up a binding.

void unbind ( $bindLocalProperty)
  • $bindLocalProperty
value (line 143)

Get the value for the widget.

Subclasses that use value, setValue automatically get formatter support.

  • return: The value returned by the widget.
mixed value ()
Redefined in descendants as:
valueForBinding (line 348)

Returns the value determined by the binding.

  • return: The value to use as determined by resolving the binding.
  • throws: Exception under various circumstances if the value cannot be determined.
mixed valueForBinding ( $prop,  $binding)
  • $prop
  • $binding
widgetLabel (line 189)

The widget's label.

  • return: string The label for this widget.
* widgetLabel ()

Inherited Methods

Inherited From WFView

WFView::__construct()
WFView::addChild()
WFView::allConfigFinishedLoading()
WFView::children()
WFView::cloneWithID()
WFView::enabled()
WFView::exposedProperties()
WFView::getForm()
WFView::getJSActions()
WFView::getListenerJS()
WFView::getListenerJSInScriptTag()
WFView::getOnEvent()
WFView::getWidgetDir()
WFView::getWidgetWWWDir()
WFView::id()
WFView::importCSS()
WFView::importJS()
WFView::jsEndHTML()
WFView::jsStartHTML()
WFView::page()
WFView::parent()
WFView::removeChild()
WFView::render()
WFView::setEnabled()
WFView::setId()
WFView::setJSonBlur()
WFView::setJSonClick()
WFView::setListener()
WFView::setOnEvent()
WFView::setParent()
WFView::yuiPath()

Inherited From WFObject

WFObject::__construct()
WFObject::exposedProperties()
WFObject::getClass()
WFObject::keyPathToTargetAndKey()
WFObject::setValueForKey()
WFObject::setValueForKeyPath()
WFObject::setValuesForKeys()
WFObject::validatedSetValueForKey()
WFObject::validatedSetValueForKeyPath()
WFObject::validateObject()
WFObject::validateValueForKey()
WFObject::validateValueForKeyPath()
WFObject::valueForKey()
WFObject::valueForKeyPath()
WFObject::valueForStaticKey()
WFObject::valueForStaticKeyPath()
WFObject::valueForTargetAndKeyPath()
WFObject::valueForUndefinedKey()
WFObject::valueForUndefinedStaticKey()
WFObject::valuesForKeyPaths()
WFObject::valuesForKeys()
WFObject::_valueForStaticKey()
WFObject::__toString()

Documentation generated on Thu, 14 May 2009 16:20:41 -0400 by phpDocumentor 1.4.2