From 4078e6a56f817f3bde7db3e9da8c81f4ef75aa1b Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Wed, 15 Aug 2018 21:00:31 -0600 Subject: [PATCH] Provide inline documentation for the FormWidget events: Documented the following: backend.form.beforeRefresh backend.form.refreshFields backend.form.refresh backend.form.extendFieldsBefore backend.form.extendFields model.form.filterFields --- modules/backend/behaviors/FormController.php | 1 + modules/backend/widgets/Form.php | 178 +++++++++++++++++-- 2 files changed, 168 insertions(+), 11 deletions(-) diff --git a/modules/backend/behaviors/FormController.php b/modules/backend/behaviors/FormController.php index 7462124d8..60f27aa09 100644 --- a/modules/backend/behaviors/FormController.php +++ b/modules/backend/behaviors/FormController.php @@ -788,6 +788,7 @@ class FormController extends ControllerBehavior /** * Called after the form fields are defined. * @param Backend\Widgets\Form $host The hosting form widget + * @param array $fields Array of all defined form field objects (\Backend\Classes\FormField) * @return void */ public function formExtendFields($host, $fields) diff --git a/modules/backend/widgets/Form.php b/modules/backend/widgets/Form.php index ae88098a7..4c0fffd32 100644 --- a/modules/backend/widgets/Form.php +++ b/modules/backend/widgets/Form.php @@ -354,8 +354,22 @@ class Form extends WidgetBase $result = []; $saveData = $this->getSaveData(); - /* - * Extensibility + /** + * @event backend.form.beforeRefresh + * Called before the form is refreshed, modify the $dataHolder->data property in place + * + * Example usage: + * + * Event::listen('backend.form.beforeRefresh', function((\Backend\Widgets\Form) $formWidget, (stdClass) $dataHolder) { + * $dataHolder->data = $arrayOfSaveDataToReplaceExistingDataWith; + * }); + * + * Or + * + * $formWidget->bindEvent('form.beforeRefresh', function ((stdClass) $dataHolder) { + * $dataHolder->data = $arrayOfSaveDataToReplaceExistingDataWith; + * }); + * */ $dataHolder = (object) ['data' => $saveData]; $this->fireSystemEvent('backend.form.beforeRefresh', [$dataHolder]); @@ -367,8 +381,22 @@ class Form extends WidgetBase $this->setFormValues($saveData); $this->prepareVars(); - /* - * Extensibility + /** + * @event backend.form.refreshFields + * Called when the form is refreshed, giving the opportunity to modify the form fields + * + * Example usage: + * + * Event::listen('backend.form.refreshFields', function((\Backend\Widgets\Form) $formWidget, (array) $allFields) { + * $allFields['name']->required = false; + * }); + * + * Or + * + * $formWidget->bindEvent('form.refreshFields', function ((array) $allFields) { + * $allFields['name']->required = false; + * }); + * */ $this->fireSystemEvent('backend.form.refreshFields', [$this->allFields]); @@ -395,8 +423,24 @@ class Form extends WidgetBase $result = ['#'.$this->getId() => $this->makePartial('form')]; } - /* - * Extensibility + /** + * @event backend.form.refresh + * Called after the form is refreshed, should return an array of additional result parameters. + * + * Example usage: + * + * Event::listen('backend.form.refresh', function((\Backend\Widgets\Form) $formWidget, (array) $result) { + * $result['#my-partial-id' => $formWidget->makePartial('$/path/to/custom/backend/partial.htm')]; + * return $result; + * }); + * + * Or + * + * $formWidget->bindEvent('form.refresh', function ((array) $result) use ((\Backend\Widgets\Form $formWidget)) { + * $result['#my-partial-id' => $formWidget->makePartial('$/path/to/custom/backend/partial.htm')]; + * return $result; + * }); + * */ $eventResults = $this->fireSystemEvent('backend.form.refresh', [$result], false); @@ -419,8 +463,46 @@ class Form extends WidgetBase return; } - /* - * Extensibility + /** + * @event backend.form.extendFieldsBefore + * Called before the form fields are defined + * + * Example usage: + * + * Event::listen('backend.form.extendFieldsBefore', function((\Backend\Widgets\Form) $formWidget) { + * // You should always check to see if you're extending correct model/controller + * if (!$widget->model instanceof \Foo\Example\Models\Bar) { + * return; + * } + * + * // Here you can't use addFields() because it will throw you an exception because form is not yet created + * // and it does not have tabs and fields + * // For this example we will pretend that we want to add a new field named example_field + * $widget->fields['example_field'] = [ + * 'label' => 'Example field', + * 'comment' => 'Your example field', + * 'type' => 'text', + * ]; + * }); + * + * Or + * + * $formWidget->bindEvent('form.extendFieldsBefore', function () use ((\Backend\Widgets\Form $formWidget)) { + * // You should always check to see if you're extending correct model/controller + * if (!$widget->model instanceof \Foo\Example\Models\Bar) { + * return; + * } + * + * // Here you can't use addFields() because it will throw you an exception because form is not yet created + * // and it does not have tabs and fields + * // For this example we will pretend that we want to add a new field named example_field + * $widget->fields['example_field'] = [ + * 'label' => 'Example field', + * 'comment' => 'Your example field', + * 'type' => 'text', + * ]; + * }); + * */ $this->fireSystemEvent('backend.form.extendFieldsBefore'); @@ -454,8 +536,62 @@ class Form extends WidgetBase $this->allTabs->secondary = new FormTabs(FormTabs::SECTION_SECONDARY, $this->secondaryTabs); $this->addFields($this->secondaryTabs['fields'], FormTabs::SECTION_SECONDARY); - /* - * Extensibility + /** + * @event backend.form.extendFields + * Called after the form fields are defined + * + * Example usage: + * + * Event::listen('backend.form.extendFields', function((\Backend\Widgets\Form) $formWidget) { + * // Only for the User controller + * if (!$widget->getController() instanceof \RainLab\User\Controllers\Users) { + * return; + * } + * + * // Only for the User model + * if (!$widget->model instanceof \RainLab\User\Models\User) { + * return; + * } + * + * // Add an extra birthday field + * $widget->addFields([ + * 'birthday' => [ + * 'label' => 'Birthday', + * 'comment' => 'Select the users birthday', + * 'type' => 'datepicker' + * ] + * ]); + * + * // Remove a Surname field + * $widget->removeField('surname'); + * }); + * + * Or + * + * $formWidget->bindEvent('form.extendFields', function () use ((\Backend\Widgets\Form $formWidget)) { + * // Only for the User controller + * if (!$widget->getController() instanceof \RainLab\User\Controllers\Users) { + * return; + * } + * + * // Only for the User model + * if (!$widget->model instanceof \RainLab\User\Models\User) { + * return; + * } + * + * // Add an extra birthday field + * $widget->addFields([ + * 'birthday' => [ + * 'label' => 'Birthday', + * 'comment' => 'Select the users birthday', + * 'type' => 'datepicker' + * ] + * ]); + * + * // Remove a Surname field + * $widget->removeField('surname'); + * }); + * */ $this->fireSystemEvent('backend.form.extendFields', [$this->allFields]); @@ -1030,7 +1166,27 @@ class Form extends WidgetBase * Advanced usage */ if (method_exists($this->model, 'fireEvent')) { - $this->model->fireEvent('model.form.filterFields', [$this]); + /** + * @event model.form.filterFields + * Called after the form is initialized + * + * Example usage: + * + * $model->bindEvent('model.form.filterFields', function ((\Backend\Widgets\Form) $formWidget, (stdClass) $fields, (string) $context) use (\October\Rain\Database\Model $model) { + * if ($model->source_type == 'http') { + * $fields->source_url->hidden = false; + * $fields->git_branch->hidden = true; + * } elseif ($model->source_type == 'git') { + * $fields->source_url->hidden = false; + * $fields->git_branch->hidden = false; + * } else { + * $fields->source_url->hidden = true; + * $fields->git_branch->hidden = true; + * } + * }); + * + */ + $this->model->fireEvent('model.form.filterFields', [$this, (object) $this->allFields, $this->getContext()]); } }