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

Improve form controller docs

This commit is contained in:
Samuel Georges 2017-03-23 08:48:26 +11:00
parent f8e7fa03e0
commit 330a41f39c
5 changed files with 212 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -14,9 +14,27 @@ use ApplicationException;
use Exception;
/**
* Form Controller Behavior
* Adds features for working with backend forms.
* Adds features for working with backend forms. This behavior
* will inject CRUD actions to the controller -- including create,
* update and preview -- along with some relevant AJAX handlers.
*
* Each action supports a custom context code, allowing fields
* to be displayed or hidden on a contextual basis, as specified
* by the form field definitions or some other custom logic.
*
* This behavior is implemented in the controller like so:
*
* public $implement = [
* 'Backend.Behaviors.FormController',
* ];
*
* public $formConfig = 'config_form.yaml';
*
* The `$formConfig` property makes reference to the form configuration
* values as either a YAML file, located in the controller view directory,
* or directly as a PHP array.
*
* @see http://octobercms.com/docs/backend/forms Back-end form documentation
* @package october\backend
* @author Alexey Bobkov, Samuel Georges
*/
@ -87,14 +105,22 @@ class FormController extends ControllerBehavior
}
/**
* Prepare the widgets used by this action
* @param Model $model
* Initialize the form configuration against a model and context value.
* This will process the configuration found in the `$formConfig` property
* and prepare the Form widget, which is the underlying tool used for
* actually rendering the form. The model used by this form is passed
* to this behavior via this method as the first argument.
*
* @see Backend\Widgets\Form
* @param October\Rain\Database\Model $model
* @param string $context Form context
* @return void
*/
public function initForm($model, $context = null)
{
if ($context !== null)
if ($context !== null) {
$this->context = $context;
}
$context = $this->formGetContext();
@ -158,7 +184,8 @@ class FormController extends ControllerBehavior
}
/**
* Prepares common form data
* Prepares commonly used view data.
* @param October\Rain\Database\Model $model
*/
protected function prepareVars($model)
{
@ -172,8 +199,9 @@ class FormController extends ControllerBehavior
//
/**
* Create Controller action
* @param string $context Explicitly define a form context.
* Controller "create" action used for creating new model records.
*
* @param string $context Form context
* @return void
*/
public function create($context = null)
@ -196,7 +224,13 @@ class FormController extends ControllerBehavior
}
/**
* Ajax handler for saving from the creation form.
* AJAX handler "onSave" called from the create action and
* primarily used for creating new records.
*
* This handler will invoke the unique controller overrides
* `formBeforeCreate` and `formAfterCreate`.
*
* @param string $context Form context
* @return mixed
*/
public function create_onSave($context = null)
@ -233,9 +267,12 @@ class FormController extends ControllerBehavior
//
/**
* Edit Controller action
* @param int $recordId The model primary key to update.
* @param string $context Explicitly define a form context.
* Controller "update" action used for updating existing model records.
* This action takes a record identifier (primary key of the model)
* to locate the record used for sourcing the existing form values.
*
* @param int $recordId Record identifier
* @param string $context Form context
* @return void
*/
public function update($recordId = null, $context = null)
@ -256,8 +293,14 @@ class FormController extends ControllerBehavior
}
/**
* Ajax handler for updating the form.
* @param int $recordId The model primary key to update.
* AJAX handler "onSave" called from the update action and
* primarily used for updating existing records.
*
* This handler will invoke the unique controller overrides
* `formBeforeUpdate` and `formAfterUpdate`.
*
* @param int $recordId Record identifier
* @param string $context Form context
* @return mixed
*/
public function update_onSave($recordId = null, $context = null)
@ -287,8 +330,13 @@ class FormController extends ControllerBehavior
}
/**
* Ajax handler for deleting the record.
* @param int $recordId The model primary key to delete.
* AJAX handler "onDelete" called from the update action and
* used for deleting existing records.
*
* This handler will invoke the unique controller override
* `formAfterDelete`.
*
* @param int $recordId Record identifier
* @return mixed
*/
public function update_onDelete($recordId = null)
@ -313,9 +361,12 @@ class FormController extends ControllerBehavior
//
/**
* Preview Controller action
* @param int $recordId The model primary key to preview.
* @param string $context Explicitly define a form context.
* Controller "preview" action used for viewing existing model records.
* This action takes a record identifier (primary key of the model)
* to locate the record used for sourcing the existing preview data.
*
* @param int $recordId Record identifier
* @param string $context Form context
* @return void
*/
public function preview($recordId = null, $context = null)
@ -340,8 +391,18 @@ class FormController extends ControllerBehavior
//
/**
* Render the form.
* @param array $options Custom options to pass to the form widget.
* Method to render the prepared form markup. This method is usually
* called from a view file.
*
* <?= $this->formRender() ?>
*
* The first argument supports an array of render options. The supported
* options can be found via the `render` method of the Form widget class.
*
* <?= $this->formRender(['preview' => true, section' => 'primary']) ?>
*
* @see Backend\Widgets\Form
* @param array $options Render options
* @return string Rendered HTML for the form.
*/
public function formRender($options = [])
@ -355,7 +416,10 @@ class FormController extends ControllerBehavior
/**
* Returns the model initialized by this form behavior.
* @return Model
* The model will be provided by one of the page actions or AJAX
* handlers via the `initForm` method.
*
* @return October\Rain\Database\Model
*/
public function formGetModel()
{
@ -363,7 +427,10 @@ class FormController extends ControllerBehavior
}
/**
* Returns the form context from the postback or configuration.
* Returns the active form context, either obtained from the postback
* variable called `form_context` or detected from the configuration,
* or routing parameters.
*
* @return string
*/
public function formGetContext()
@ -372,8 +439,9 @@ class FormController extends ControllerBehavior
}
/**
* Internal method, prepare the form model object
* @return Model
* Internal method used to prepare the form model object.
*
* @return October\Rain\Database\Model
*/
protected function createModel()
{
@ -383,7 +451,9 @@ class FormController extends ControllerBehavior
}
/**
* Returns a Redirect object based on supplied context and parses the model primary key.
* Returns a Redirect object based on supplied context and parses
* the model primary key.
*
* @param string $context Redirect context, eg: create, update, delete
* @param Model $model The active model to parse in it's ID and attributes.
* @return Redirect
@ -411,8 +481,9 @@ class FormController extends ControllerBehavior
}
/**
* Internal method, returns a redirect URL from the config based on
* Internal method that returns a redirect URL from the config based on
* supplied context. Otherwise the default redirect is used.
*
* @param string $context Redirect context, eg: create, update, delete.
* @return string
*/
@ -436,6 +507,7 @@ class FormController extends ControllerBehavior
/**
* Parses in some default variables to a language string defined in config.
*
* @param string $name Configuration property containing the language string
* @param string $default A default language string to use if the config is not found
* @param array $extras Any extra params to include in the language string variables
@ -456,9 +528,12 @@ class FormController extends ControllerBehavior
//
/**
* Renders a single form field.
* @param string Field name
* @return string The field HTML markup.
* View helper to render a single form field.
*
* <?= $this->formRenderField('field_name') ?>
*
* @param string $name Field name
* @return string HTML markup
*/
public function formRenderField($name)
{
@ -466,7 +541,10 @@ class FormController extends ControllerBehavior
}
/**
* Renders the form in preview mode.
* View helper to render the form in preview mode.
*
* <?= $this->formRenderPreview() ?>
*
* @return string The form HTML markup.
*/
public function formRenderPreview()
@ -475,7 +553,13 @@ class FormController extends ControllerBehavior
}
/**
* Helper to check if a form tab has fields.
* View helper to check if a form tab has fields in the
* non-tabbed section (outside fields).
*
* <?php if ($this->formHasOutsideFields()): ?>
* <!-- Do something -->
* <?php endif ?>
*
* @return bool
*/
public function formHasOutsideFields()
@ -484,8 +568,12 @@ class FormController extends ControllerBehavior
}
/**
* Helper for custom layouts. Renders Outside Fields.
* @return string The area HTML markup.
* View helper to render the form fields belonging to the
* non-tabbed section (outside form fields).
*
* <?= $this->formRenderOutsideFields() ?>
*
* @return string HTML markup
*/
public function formRenderOutsideFields()
{
@ -493,7 +581,13 @@ class FormController extends ControllerBehavior
}
/**
* Helper to check if a form tab has fields.
* View helper to check if a form tab has fields in the
* primary tab section.
*
* <?php if ($this->formHasPrimaryTabs()): ?>
* <!-- Do something -->
* <?php endif ?>
*
* @return bool
*/
public function formHasPrimaryTabs()
@ -502,8 +596,12 @@ class FormController extends ControllerBehavior
}
/**
* Helper for custom layouts. Renders Primary Tabs.
* @return string The tab HTML markup.
* View helper to render the form fields belonging to the
* primary tabs section.
*
* <?= $this->formRenderPrimaryTabs() ?>
*
* @return string HTML markup
*/
public function formRenderPrimaryTabs()
{
@ -511,7 +609,13 @@ class FormController extends ControllerBehavior
}
/**
* Helper to check if a form tab has fields.
* View helper to check if a form tab has fields in the
* secondary tab section.
*
* <?php if ($this->formHasSecondaryTabs()): ?>
* <!-- Do something -->
* <?php endif ?>
*
* @return bool
*/
public function formHasSecondaryTabs()
@ -520,8 +624,12 @@ class FormController extends ControllerBehavior
}
/**
* Helper for custom layouts. Renders Secondary Tabs.
* @return string The tab HTML markup.
* View helper to render the form fields belonging to the
* secondary tabs section.
*
* <?= $this->formRenderPrimaryTabs() ?>
*
* @return string HTML markup
*/
public function formRenderSecondaryTabs()
{
@ -529,8 +637,9 @@ class FormController extends ControllerBehavior
}
/**
* Returns the widget used by this behavior.
* @return Backend\Classes\WidgetBase
* Returns the form widget used by this behavior.
*
* @return Backend\Widgets\Form
*/
public function formGetWidget()
{
@ -538,7 +647,17 @@ class FormController extends ControllerBehavior
}
/**
* Helper to get a unique ID for the form widget.
* Returns a unique ID for the form widget used by this behavior.
* This is useful for dealing with identifiers in the markup.
*
* <div id="<?= $this->formGetId()">...</div>
*
* A suffix may be used passed as the first argument to reuse
* the identifier in other areas.
*
* <button id="<?= $this->formGetId('button')">...</button>
*
* @param string $suffix
* @return string
*/
public function formGetId($suffix = null)
@ -548,9 +667,10 @@ class FormController extends ControllerBehavior
/**
* Helper to get the form session key.
*
* @return string
*/
public function formGetSessionKey($suffix = null)
public function formGetSessionKey()
{
return $this->formWidget->getSessionKey();
}
@ -740,5 +860,4 @@ class FormController extends ControllerBehavior
call_user_func_array($callback, [$widget, $widget->model, $widget->getContext()]);
});
}
}

13
modules/backend/behaviors/ImportExportController.php
View File

@ -16,9 +16,20 @@ use SplTempFileObject;
use Exception;
/**
* Import/Export Controller Behavior
* Adds features for importing and exporting data.
*
* This behavior is implemented in the controller like so:
*
* public $implement = [
* 'Backend.Behaviors.ImportExportController',
* ];
*
* public $importExportConfig = 'config_import_export.yaml';
*
* The `$importExportConfig` property makes reference to the configuration
* values as either a YAML file, located in the controller view directory,
* or directly as a PHP array.
*
* @package october\backend
* @author Alexey Bobkov, Samuel Georges
*/

13
modules/backend/behaviors/ListController.php
View File

@ -8,9 +8,20 @@ use ApplicationException;
use Backend\Classes\ControllerBehavior;
/**
* List Controller Behavior
* Adds features for working with backend lists.
*
* This behavior is implemented in the controller like so:
*
* public $implement = [
* 'Backend.Behaviors.ListController',
* ];
*
* public $listConfig = 'config_list.yaml';
*
* The `$listConfig` property makes reference to the list configuration
* values as either a YAML file, located in the controller view directory,
* or directly as a PHP array.
*
* @package october\backend
* @author Alexey Bobkov, Samuel Georges
*/

13
modules/backend/behaviors/RelationController.php
View File

@ -10,9 +10,20 @@ use October\Rain\Database\Model;
use ApplicationException;
/**
* Relation Controller Behavior
* Uses a combination of lists and forms for managing Model relations.
*
* This behavior is implemented in the controller like so:
*
* public $implement = [
* 'Backend.Behaviors.RelationController',
* ];
*
* public $relationConfig = 'config_relation.yaml';
*
* The `$relationConfig` property makes reference to the configuration
* values as either a YAML file, located in the controller view directory,
* or directly as a PHP array.
*
* @package october\backend
* @author Alexey Bobkov, Samuel Georges
*/

13
modules/backend/behaviors/ReorderController.php
View File

@ -6,9 +6,20 @@ use ApplicationException;
use Backend\Classes\ControllerBehavior;
/**
* Reorder Controller Behavior
* Used for reordering and sorting records.
*
* This behavior is implemented in the controller like so:
*
* public $implement = [
* 'Backend.Behaviors.ReorderController',
* ];
*
* public $reorderConfig = 'config_reorder.yaml';
*
* The `$reorderConfig` property makes reference to the configuration
* values as either a YAML file, located in the controller view directory,
* or directly as a PHP array.
*
* @package october\backend
* @author Alexey Bobkov, Samuel Georges
*/