TPS
/
ORIENT
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
This commit is contained in:
Luke Towers 2018-08-15 21:00:31 -06:00
parent f12f3af37f
commit 4078e6a56f
2 changed files with 168 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
modules/backend/behaviors/FormController.php
View File

@ -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)

178
modules/backend/widgets/Form.php
View File

@ -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()]);
}
}