Class WFDynamic

Description

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.

It's perfect for repeating data, tabular data, etc. You can also use multiple ones on the same page.

There are two modes of operation for WFDynamic. These two modes allow for great flexibility in layout of the managed widgets.

  1. By default, the WFDynamic will output the NEXT widget each time the {WFDynamic id="XXX"} is output in the template. In this case, you will need to ensure that if your array has N entries then you output the WFDynamic tag N times in the template. The upside of this mode is that there is great flexibility in layout as you can place the widgets wherever you like them. The downside is that you need to make sure that your template has a loop in it that iterates N times so that you can be sure all widgets will be displayed.
  2. The other option, called oneShotMode, will output one entry for each item in the array when the {WFDynamic id="XXX"} tag is used in your template. In this case, each widget will be separated by the HTML snippet in oneShotSeparatorHTML. The upside to this mode is its simplicity; it's great if you just need a list of checkboxes or labels for each item in the array. The downside is that you cannot position each widget inside of a larger layout in all cases as they are all clumped together.
NOTE: (DEPRECEATED -- USE PROTOTYPES NOW) If you want to assign a formatter to the widgets, simply assign a formatter to the WFDynamic and it will be re-used for all dynamically created widgets too.

PROTOTYPES

Oftentimes you want to have customized attributes on the widget you are creating via WFDynamic. For instance, using formatters, setting default options, or other properties. WFDynamic now supports "prototypes". Simply add a child to the WFDynamic named "<id of WFDynamic>Prototype" and configure it as you would normally. WFDynamic will use this prototype object as the basis for all objects created. If you do use a prototype, there is no need to supply the widgetClass.

BINDINGS VIA PROTOTYPES

You can specify "simpleBindKeyPath" style bindings via prototypes as well. To bind a property of the prototype to a keyPath of each object in the WFDynamic's ArrayController, simply add a binding to the prototype object, bind it to the same array controller you configured for WFDynamic, set the controller key to "#current#", and set the desired Model Key Path.

WFDYNAMIC AND THE VIEW HIERARCHY OF CREATED WIDGETS WFDynamic creates widgets. However, WFDynamic is a "magic" widget and should be transparent to its parent and the created children. WFDynamic will add its dynamic widgets to the parent WFView object of the WFDynamic, thus creating the widgets as children of that object as if they had been created normally. HOWEVER: At this time, the WFDynamic is still in the view hierarchy as another child of the parent. So, at this point, WFViews that expect children such as WFRadioGroup should skip any WFDynamics they find when processing their children.

PHOCOA Builder Setup:

Required:

Optional:

  • todo: I think maybe that WFDynamic should be completely transparent to the view heirarchy. However, currently, subclasses of WFDynamic may not agree. Please check them out and see if this can all be refactored in a better, more consistent way. Maybe WFDynamic should be final? Definitely look into this and WFCheckboxGroup as well. There are related todo's in there.

Located in /framework/widgets/WFDynamic.php (line 53)

WFObject
   |
   --WFView
      |
      --WFWidget
         |
         --WFDynamic
Direct descendents
Class Description
WFSelectionCheckbox WFSelectionCheckbox is used to create numerous checkboxes representing a selection of items in an array.
Variable Summary
Method Summary
static void exposedProperties ()
WFDynamic __construct ( $id,  $page)
void addChild (WFView $view)
assoc_array createWidgets ()
array managedWidgets ()
void render ([ $blockContent = NULL])
void restoreState ()
void setArrayController ( $ac)
void setParentFormID ()
void setPrototype (WFView $view)
void setSimpleBindKeyPath ( $kp)
void setUseUniqueNames ( $useUniqueNames)
void setWidgetClass ( $widgetClass)
void setWidgetConfig (array $config)
Variables
WFArrayController $arrayController (line 58)
  • var: The array controller that will be used to create widgets for. One widget will be created for each item in the controller. Example: #module#myArrayController
  • access: protected
array $createdWidgets (line 82)
  • var: An array of the widget ID's created by the dynamic control. Used during rendering to iterate through the widgets.
  • access: protected
int $createdWidgetsChangeCount (line 119)
  • var: The arrayController's changeCount when createdWidgets was last called
  • access: protected
boolean $oneShotMode (line 107)
  • var: TRUE if all managed widgets should be output at the first occurence of the {WFDynamic id="XXX"} tag. False if the next occurence of the managed widgets should be output at each occurence of the tag.
  • access: protected
string $oneShotSeparatorHTML (line 111)
  • var: If oneShotMode is enabled, this is the HTML that will be used to separate each widget. Default is <br />.
  • access: protected
boolean $processedWidgetConfig (line 74)
  • var: Tracks whether or not the widgetConfig has been updated based on other settings yet. WFDynamic subclasses may want to look at this var to determine whether to do any initial setup.
  • access: protected
object WFView $prototype (line 115)
  • var: A prototype object to use for each widget created. Can be NULL.
  • access: protected
integer $renderIteration (line 78)
  • var: The current iteration, used during rendering.
  • access: protected
string $simpleBindKeyPath (line 103)
  • var:

    The keyPath on the class managed by arrayController to use as the value for each created widget.

    Very often, we simply want to link a WFDynamic to a particular modelKey of the current object, and this is a way to do this without having to write code. A good example of this is using a WFLabel to show the value of every item in an array.

    If this property is non-null, it has the same effect as declaring the following config option:

    1.       $options array(
    2.               'value' => array(
    3.                   'bind' => array(
    4.                       'instanceID' => '#current#',
    5.                       'controllerKey' => '',
    6.                       'modelKeyPath' => $simpleBindKeyPath
    7.                       )
    8.                   )
    9.               );

  • access: protected
boolean $useUniqueNames (line 66)
  • var: Use unique names (HTML input name) for each widget? Or use the same for every widget (for instance, when using radios or checkboxes you may want to set this to true)
  • access: protected
string $widgetClass (line 62)
  • var: The class name of the WFWidget subclass to create. Examples: WFLabel, WFTextField, etc.
  • access: protected
array $widgetConfig (line 70)
  • var: The configuration array for the dynamic widget.
  • access: protected

Inherited Variables

Inherited from WFWidget

WFWidget::$bindings
WFWidget::$class
WFWidget::$errors
WFWidget::$formatter
WFWidget::$hasRestoredState
WFWidget::$hidden
WFWidget::$name
WFWidget::$value
WFWidget::$widgetLabel

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
static method exposedProperties (line 143)
  • access: public
static void exposedProperties ()

Redefinition of:
WFWidget::exposedProperties()

Redefined in descendants as:
Constructor __construct (line 124)

Constructor.

WFDynamic __construct ( $id,  $page)
  • $id
  • $page

Redefinition of:
WFWidget::__construct()
Constructor.

Redefined in descendants as:
addChild (line 199)

To implement our prototype functionality, we need to detect when a child object named "<id>Prototype" has been added.

If a prototype object is detected, we set up the prototype for the WFDynamic.

void addChild (WFView $view)

Redefinition of:
WFView::addChild()
Add a child view to this view.
calculateParent (line 254)

Get the parent WFView for the WFDynamic.

The WFDynamic is basically used to dynamically add children to the parent of whatever it's under. So for things like WFRadioGroup and WFCheckboxGroup it's important that the parent "Group" widget gets directly assigned all objects created by WFDynamic.

  • return: The parent WFView, or NULL if the WFDynamic does not have a parent.
object WFView calculateParent ()
canPushValueBinding (line 176)
void canPushValueBinding ()

Redefinition of:
WFWidget::canPushValueBinding()
Does this widget use the "value" binding to WRITE data back to the bindings?
createWidgets (line 402)

Create the dynamic widgets.

Allows for creation of n widgets based on an WFArrayController. Various options allow you to set up nearly any type of widget that is repeated for all objects in an array. Great for managing selection, editing data from joins, etc.

Once the objects are instantiated, configured, and bound as appropriate, restoreState() will be called. You can be sure that when this function exits that your widgets are in the same state as statically instantiated widgets from the page.

This will be called AFTER the _PageDidLoad method... which is what we need to wait for before creating our widgets. WFPage makes this call.

Module code may need to call this function again, particularly if the content of they arrayController is changed by the current action.

  • return: An array of 'widgetID' => widget for all newly created widgets.
  • todo: Anything else wrong with calling more than once? This should be idempotent as well as re-callable with different data.
assoc_array createWidgets ()

Redefined in descendants as:
getLastRenderedWidget (line 314)

Get the last rendered widget.

  • return: The instance of the last rendered widget.
  • throws: object WFException If you call this function before any widgets have been rendered.
object WFWidget getLastRenderedWidget ()
managedWidgets (line 241)

Get an array of all of the widgets managed by this WFDynamic instance.

  • return: An array of WFWidget subclasses that were created by this WFDynamic.
array managedWidgets ()
processWidgetConfig (line 346)

Process the widget config.

The widgetConfig is the options to use for creating the dynamic widgets. Based on various other settings, the widgetConfig may be altered. The alteration process need happen only once per WFDynamic instance. The processing should be delayed until just before creating the widgets.

void processWidgetConfig ()
render (line 320)
void render ([ $blockContent = NULL])
  • $blockContent

Redefinition of:
WFView::render()
Render the view into HTML.

Redefined in descendants as:
  • WFSelectionCheckbox::render() : Just before rendering, we want to update the checked status of all managed checkboxes to reflect the selection status of the arrayController.
restoreState (line 624)
void restoreState ()

Redefinition of:
WFWidget::restoreState()
Restore the UI state of this widget from the $_REQUEST data.

Redefined in descendants as:
setArrayController (line 230)
void setArrayController ( $ac)
  • $ac
setParentFormID (line 171)
void setParentFormID ()
setPrototype (line 186)

Set the WFView object to be used as the prototype for all instances created.

void setPrototype (WFView $view)
  • object WFView $view: The WFView object to be used as the prototype.
setSimpleBindKeyPath (line 220)
void setSimpleBindKeyPath ( $kp)
  • $kp
setUseUniqueNames (line 166)
void setUseUniqueNames ( $useUniqueNames)
  • $useUniqueNames
setWidgetClass (line 225)
void setWidgetClass ( $widgetClass)
  • $widgetClass
setWidgetConfig (line 302)

Set the config that will be used for the dynamic creation of widgets. See createWidgets for documentation on the config array.

  • throws: If the passed parameter is not a PHP array.
void setWidgetConfig (array $config)
  • array $config:

    The widgetConfig to use for creation of widgets. Format:

    1.   array(
    2.       // enter as many widget property names as you like.
    3.       'widgetPropName' => array(
    4.                               'custom' => array(
    5.                                               'iterate' => true false,
    6.                                               'keyPath' => 'modelKeyPath' KeyPath of the object to use for this iteration.
    7.                                                                           Only used if 'iterate' == trueand then it's optional.
    8.                                                                           If 'iterate' == true, then uses the nth value from the 'value' array.
    9.                                                                           If 'iterate' == '#identifier#', then uses the identifierHashForObject() for the current object.
    10.                                                                           NOTEif the array controller is in indexed modewill use the index of the object.
    11.                                                                           If 'iterate' == falsethen uses the 'value' for EVERY iteration.
    12.                                               'value' => mixed            Either an array or a primitivedepending on the setting of 'iterate'.
    13.                                               )
    14.                               // use this binding config (similar format as widget .config file)
    15.                               'bind' => array(
    16.                                               'instanceID' => 'outletName' or
    17.                                                               '#module#' (to use the moduleor
    18.                                                               '#custom# (to use object specified in 'custom' above) or
    19.                                                               '#current#' (to use the object of the current iteration)
    20.                                               'controllerKey' => 'controllerKey',
    21.                                               'modelKeyPath' => 'modelKeyPath',
    22.                                               'options' => array(// bindings options
    23.                                               )
    24.                           )
    25.       )

    This format lets you arbitrarily configure any property of any type of widget.

    For each property, you can choose to use the same 'value' for EVERY widget, or you can use a different value for each widget, the nth item in 'value' for the nth instance.

Inherited Methods

Inherited From WFWidget

WFWidget::__construct()
WFWidget::addError()
WFWidget::addErrors()
WFWidget::bind()
WFWidget::bindingByName()
WFWidget::bindings()
WFWidget::canPushValueBinding()
WFWidget::errors()
WFWidget::exposedBindings()
WFWidget::exposedProperties()
WFWidget::formattedValue()
WFWidget::formatter()
WFWidget::hasRestoredState()
WFWidget::hidden()
WFWidget::name()
WFWidget::processBindingOptions()
WFWidget::propagateValueToBinding()
WFWidget::pullBindings()
WFWidget::pushBindings()
WFWidget::restoreState()
WFWidget::setFormatter()
WFWidget::setHidden()
WFWidget::setName()
WFWidget::setupExposedBindings()
WFWidget::setValue()
WFWidget::setWidgetLabel()
WFWidget::unbind()
WFWidget::value()
WFWidget::valueForBinding()
WFWidget::widgetLabel()

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:19:56 -0400 by phpDocumentor 1.4.2