|
Perforce Chronicle 2012.2/486814
API Documentation
|
A 'pub-sub' form is a form that can be modified via pub/sub. More...
Public Member Functions | |
| getTopic () | |
| Get the topic for publishing this form. | |
| hasTopic () | |
| Check if a topic has been set for this form. | |
| init () | |
| If this form has a topic set, automatically publish to collect any sub-forms and allow arbitrary modification of the form itself. | |
| isValid ($data) | |
| Validate the form - publish to the form topic + '/validate' to allow third-party involvement in validation. | |
| populate ($values) | |
| Populate the form from key-value array. | |
| publish ($subTopic=null, $args=null) | |
| Publish this form. | |
| publishSubForms () | |
| Collect sub-forms for this form by publishing to the form topic + '/sub-forms'. | |
| setTopic ($topic) | |
| Specify the topic to use when publishing this form. | |
Protected Attributes | |
| $_topic = null | |
A 'pub-sub' form is a form that can be modified via pub/sub.
Topics published:
<form-topic> - general form manipulation at init time <form-topic>.subForms - provide sub forms (via return) at init time <form-topic>.validate - validate form data (true for valid, false otherwise) <form-topic>.populate - populate form from data
| P4Cms_Form_PubSubForm::getTopic | ( | ) |
Get the topic for publishing this form.
| InvalidArgumentException | if no topic is set. |
{
if ($this->_topic === null) {
throw new P4Cms_Form_Exception("No topic set for this form");
}
return $this->_topic;
}
| P4Cms_Form_PubSubForm::hasTopic | ( | ) |
Check if a topic has been set for this form.
{
return !is_null($this->_topic);
}
| P4Cms_Form_PubSubForm::init | ( | ) |
If this form has a topic set, automatically publish to collect any sub-forms and allow arbitrary modification of the form itself.
Reimplemented in Content_Form_Content, Content_Form_Type, Site_Form_Configure, and Ui_Form_GridOptions.
{
if (!$this->hasTopic()) {
return;
}
// collect any sub-forms.
$this->publishSubForms();
// allow arbitrary modification of this form.
$this->publish();
}
| P4Cms_Form_PubSubForm::isValid | ( | $ | data | ) |
Validate the form - publish to the form topic + '/validate' to allow third-party involvement in validation.
Subscribers should return true if the data is valid and false otherwise. Errors can be added directly to the form object.
| array | $data | the data to validate. |
Reimplemented from P4Cms_Form.
Reimplemented in Content_Form_Type.
{
// allow third-parties to make adjustments to the
// form and influence the outcome of the validation.
$this->publish('preValidate', $data);
$isValid = parent::isValid($data);
// allow third-parties to validate the form
$feedback = $this->publish('validate', $data);
// any false feedback means the form is invalid.
foreach ($feedback as $valid) {
if (!$valid) {
$isValid = false;
$this->_errorsExist = true;
}
}
return $isValid;
}
| P4Cms_Form_PubSubForm::populate | ( | $ | values | ) |
Populate the form from key-value array.
Extended to publish to form topic + '/populate' so that third-parties can participate.
| P4Cms_Record | array | $values | the values to populate the form from. |
Reimplemented from P4Cms_Form.
Reimplemented in Content_Form_Content.
{
parent::populate($values);
// turn records into arrays before publishing so that
// subscribers consistently get array input.
if ($values instanceof P4Cms_Record) {
$values = $values->getValues();
}
$this->publish('populate', $values);
return $this;
}
| P4Cms_Form_PubSubForm::publish | ( | $ | subTopic = null, |
| $ | args = null |
||
| ) |
Publish this form.
Happens automatically on init() if the topic has been set. Pass subTopic to append a suffix to the topic. Pass additional args to be included in the publish call (always includes the form instance by default).
| string | $subTopic | optional - suffix to add to the form topic. |
| mixed | $args | optional - all arguments besides the topic are passed as arguments to the handler |
{
$topic = $subTopic
? $this->getTopic() . P4Cms_PubSub::TOPIC_DELIMITER . $subTopic
: $this->getTopic();
// inject topic and form into args.
$args = func_get_args();
array_splice($args, 0, 1, array($topic, $this));
return call_user_func_array(
array('P4Cms_PubSub', 'publish'),
$args
);
}
| P4Cms_Form_PubSubForm::publishSubForms | ( | ) |
Collect sub-forms for this form by publishing to the form topic + '/sub-forms'.
Sub-forms are automatically normalized for consistent presentation and added.
{
$feedback = $this->publish('subForms');
// process sub-form feedback.
foreach ($feedback as $subForms) {
if (!is_array($subForms)) {
$subForms = array($subForms);
}
foreach ($subForms as $subForm) {
// skip cases where the subscriber decided not to return a form
if (!isset($subForm)) {
continue;
}
if (!$subForm instanceof Zend_Form || !$subForm->getName()) {
P4Cms_Log::log(
"Encountered invalid pub-sub sub-form.",
P4Cms_Log::ERR
);
P4Cms_Log::log(print_r($subForm, true), P4Cms_Log::DEBUG);
// skip form.
continue;
}
$name = $subForm->getName();
// ensure consistent sub-form markup.
static::normalizeSubForm($subForm, $name);
// add it.
$this->addSubForm($subForm, $name);
}
}
return $this;
}
| P4Cms_Form_PubSubForm::setTopic | ( | $ | topic | ) |
Specify the topic to use when publishing this form.
| string | $topic | the topic to use when publishing this form. |
| InvalidArgumentException | if topic is not a string or null |
{
if (!is_string($topic) && !is_null($topic)) {
throw new InvalidArgumentException("Form topic must be a string or null");
}
$this->_topic = $topic;
return $this;
}
P4Cms_Form_PubSubForm::$_topic = null [protected] |