From cf8a31a76ca8db6ed990be4587567fbcabe1e867 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 27 Jun 2017 13:09:16 -0600 Subject: [PATCH] refactor: cleanup documentation --- docs/_partials/fields/field-blacklist.rst | 11 + docs/_partials/fields/field-settings.rst | 15 + docs/_partials/fields/formatter-callable.rst | 44 ++ docs/_partials/fields/formatter-element.rst | 49 +++ docs/_partials/fields/index.rst | 28 ++ docs/_partials/pages/form/elements.rst | 21 + docs/_partials/pages/form/submission.rst | 25 ++ docs/_partials/pages/form/submit-buttons.rst | 69 ++++ docs/_partials/pages/form/viewblocks.rst | 11 + docs/_partials/pages/index/buttons.rst | 154 +++++++ docs/_partials/pages/index/elements.rst | 2 + docs/_partials/pages/index/filters.rst | 2 + docs/_partials/pages/index/finder-scopes.rst | 102 +++++ docs/_partials/pages/index/multiple-pages.rst | 12 + docs/_partials/pages/index/viewblocks.rst | 2 + docs/basic-usage.rst | 6 +- docs/customizing-templates.rst | 139 +------ docs/form-pages/customizing-the-form-page.rst | 171 +------- docs/general-configuration/breadcrumbs.rst | 2 +- .../site-title-options.rst | 13 +- docs/index-pages/components/gallery.rst | 2 +- docs/index-pages/components/table.rst | 2 +- .../customizing-the-index-page.rst | 389 +----------------- 23 files changed, 596 insertions(+), 675 deletions(-) create mode 100644 docs/_partials/fields/field-blacklist.rst create mode 100644 docs/_partials/fields/field-settings.rst create mode 100644 docs/_partials/fields/formatter-callable.rst create mode 100644 docs/_partials/fields/formatter-element.rst create mode 100644 docs/_partials/fields/index.rst create mode 100644 docs/_partials/pages/form/elements.rst create mode 100644 docs/_partials/pages/form/submission.rst create mode 100644 docs/_partials/pages/form/submit-buttons.rst create mode 100644 docs/_partials/pages/form/viewblocks.rst create mode 100644 docs/_partials/pages/index/buttons.rst create mode 100644 docs/_partials/pages/index/elements.rst create mode 100644 docs/_partials/pages/index/filters.rst create mode 100644 docs/_partials/pages/index/finder-scopes.rst create mode 100644 docs/_partials/pages/index/multiple-pages.rst create mode 100644 docs/_partials/pages/index/viewblocks.rst diff --git a/docs/_partials/fields/field-blacklist.rst b/docs/_partials/fields/field-blacklist.rst new file mode 100644 index 00000000..33fa05aa --- /dev/null +++ b/docs/_partials/fields/field-blacklist.rst @@ -0,0 +1,11 @@ +Removing Fields from output +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You may also use the ``scaffold.fields_blacklist`` configuration key to remove +fields from the output if you are using the default automatic field population +functionality: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.fields_blacklist', ['created', 'modified']); diff --git a/docs/_partials/fields/field-settings.rst b/docs/_partials/fields/field-settings.rst new file mode 100644 index 00000000..d60bd357 --- /dev/null +++ b/docs/_partials/fields/field-settings.rst @@ -0,0 +1,15 @@ +Setting options for specific fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you wish to use the default automatic field population functionality but want +to specify settings for a few of the fields, you can use the +``scaffold.field_settings`` configuration key: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.field_settings', [ + 'title' => [ + // options here + ] + ]); diff --git a/docs/_partials/fields/formatter-callable.rst b/docs/_partials/fields/formatter-callable.rst new file mode 100644 index 00000000..15a1f816 --- /dev/null +++ b/docs/_partials/fields/formatter-callable.rst @@ -0,0 +1,44 @@ +Formatting with a Callable +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + This functionality currently only applies to ``index`` and ``view`` pages. + +The most immediate way of formatting a field is by passing a callable function +or object to the ``formatter`` option. Callable functions or objects will +receive 3 arguments: + +* ``$name`` The name of the field to be displayed +* ``$value`` The value of the field that should be outputted +* ``$entity`` The entity object from which the field was extracted + +For example, imagine that when displaying the ``published_time`` property, we +wanted to also display who approved the article: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.fields', [ + 'title', + 'published_time' => [ + 'formatter' => function ($name, $value, $entity) { + return $value->nice() . sprintf(' (Approved by %s)', $entity->approver->name); + } + ], + ]); + +You may also specify formatters using the ``scaffold.field_settings`` +configuration key. This is useful if you want to display all fields but wish to +only configure the settings for one or two. + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.field_settings', [ + 'published_time' => [ + 'formatter' => function ($name, Time $value) { + return $value->nice() . sprintf(' (Approved by %s)', $entity->approver->name); + } + ], + ]); diff --git a/docs/_partials/fields/formatter-element.rst b/docs/_partials/fields/formatter-element.rst new file mode 100644 index 00000000..70817440 --- /dev/null +++ b/docs/_partials/fields/formatter-element.rst @@ -0,0 +1,49 @@ +Formatting with an Element +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + This functionality currently only applies to ``index`` and ``view`` pages. + +Sometimes you want to execute more complex formatting logic, that may involve +the use of view helpers or outputting HTML. Since building HTML outside of the +view layer is not ideal, you can use the ``element`` formatter for any of your +fields. + +For example, consider this example where we want to link the ``published_time`` +to the same index action by passing some search arguments: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.fields', [ + 'published_time' => [ + 'formatter' => 'element', + 'element' => 'search/published_time', + 'action' => 'index' + ] + ]); + +We have instructed the formatter to use ``search/published_time`` element. Then, +it is just a matter of creating the element file with the right content: + +.. code-block:: php + + // src/Template/Element/search/published_time.ctp + + echo $this->Html->link($value->timeAgoInWords(), [ + 'action' => $options['action'], + 'published_time' => $value->format('Y-m-d') + ]); + +After this, when displaying the ``published_time`` field, there will the will be +a link similar to this one:: + + 4 days ago + +Element files will have available at least the following variables: + +* ``$value``: The value of the field +* ``$field``: The name of the field it is intended to be rendered +* ``$context``: The entity from which the value came from +* ``$options``: The array of options associated to the field as passed in ``scaffold.fields`` diff --git a/docs/_partials/fields/index.rst b/docs/_partials/fields/index.rst new file mode 100644 index 00000000..4189e4e3 --- /dev/null +++ b/docs/_partials/fields/index.rst @@ -0,0 +1,28 @@ +Customizing Fields +------------------ + +Fields may be specified via the ``scaffold.fields`` configuration key. By +default, this will contain a list of all columns associated with the Table being +in scope. To limit the fields used, simply specify an array of fields. + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.fields', ['title', 'description']); + +You may also specify an options array. For forms, *CrudView* makes use of the +``FormHelper::inputs()`` method and will pass your array values as options when +generating the output. + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.fields', [ + 'title', + 'thread_id' => [ + 'type' => 'text' + ], + 'featured' => [ + 'checked' => 'checked' + ] + ]); diff --git a/docs/_partials/pages/form/elements.rst b/docs/_partials/pages/form/elements.rst new file mode 100644 index 00000000..27d73cd3 --- /dev/null +++ b/docs/_partials/pages/form/elements.rst @@ -0,0 +1,21 @@ +Available Elements +------------------ + +All the *CrudView* templates are built from several elements that can be +overridden by creating them in your own ``src/Template/Element`` folder. The +following sections will list all the elements that can be overridden for each +type of action. + +In general, if you want to override a template, it is a good idea to copy the +original implementation from +``vendor/friendsofcake/crud-view/src/Template/Element`` + +action-header + Create ``src/Template/Element/action-header.ctp`` to have full control over + what is displayed at the top of the page. This is shared across all page + types. + +form/buttons + Create ``src/Template/Element/form/buttons.ctp`` to change what is displayed + for form submission. You can expect the ``$formSubmitButtonText`` and + ``$formSubmitExtraButtons`` variables to be available diff --git a/docs/_partials/pages/form/submission.rst b/docs/_partials/pages/form/submission.rst new file mode 100644 index 00000000..c7e502d9 --- /dev/null +++ b/docs/_partials/pages/form/submission.rst @@ -0,0 +1,25 @@ +Form Submission +--------------- + +Form Submission Redirect +~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the Crud plugin will redirect all form submissions to the +controller's ``index`` action. This can be changed by setting the +``_redirect_url`` view variable: + +.. code-block:: php + + $this->set('_redirect_url', ['action' => 'home']); + +Form Submission Check +~~~~~~~~~~~~~~~~~~~~~ + +By default, closing the a form page in your browser will result in lost data. +However, you may force a user prompt by enabling dirty form checks using the +``scaffold.form_enable_dirty_check`` configuration key: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.form_enable_dirty_check', true); diff --git a/docs/_partials/pages/form/submit-buttons.rst b/docs/_partials/pages/form/submit-buttons.rst new file mode 100644 index 00000000..0af476e6 --- /dev/null +++ b/docs/_partials/pages/form/submit-buttons.rst @@ -0,0 +1,69 @@ +Submit Buttons +-------------- + +Changing the Submit Button Text +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can change the submit button text from it's default using the +``scaffold.form_submit_button_text`` configuration key. + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.form_submit_button_text', _('Submit')); + +Modifying the Default Extra Buttons +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, we should the following extra buttons for forms: + +- Save & continue editing: Results in a form submission +- Save & create new: Results in a form submission +- Back: A link to the index page + +To use the defaults, you may either omit the configuration key **or** set it +to true: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.form_submit_extra_buttons', true); + +You can also customize this by using the ``scaffold.form_submit_extra_buttons`` +configuration key as follows: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.form_submit_extra_buttons', [ + [ + 'title' => __d('crud', 'Save & continue editing'), + 'options' => ['class' => 'btn btn-success btn-save-continue', 'name' => '_edit', 'value' => true], + 'type' => 'button', + ], + [ + 'title' => __d('crud', 'Save & create new'), + 'options' => ['class' => 'btn btn-success', 'name' => '_add', 'value' => true], + 'type' => 'button', + ], + [ + 'title' => __d('crud', 'Back'), + 'url' => ['action' => 'index'], + 'options' => ['class' => 'btn btn-default', 'role' => 'button', 'value' => true], + 'type' => 'link', + ], + ]); + +Specified values will override the defaults, and will be output in the order +specified. + +Disabling the Default Extra Buttons +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Rather than modifying the default extra buttons, you can also disable them +completely: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.form_submit_extra_buttons', false); diff --git a/docs/_partials/pages/form/viewblocks.rst b/docs/_partials/pages/form/viewblocks.rst new file mode 100644 index 00000000..c5e6abd3 --- /dev/null +++ b/docs/_partials/pages/form/viewblocks.rst @@ -0,0 +1,11 @@ +Available Viewblocks +-------------------- + +The following custom view blocks are available for use within forms: + +- ``form.sidebar``: Rendered on the side of a form. Will also change the form + width +- ``form.before_create``: Rendered before ``FormHelper::create()`` is called +- ``form.after_create``: Rendered after ``FormHelper::create()`` is called +- ``form.before_end``: Rendered before ``FormHelper::end()`` is called +- ``form.after_end``: Rendered after ``FormHelper::end()`` is called diff --git a/docs/_partials/pages/index/buttons.rst b/docs/_partials/pages/index/buttons.rst new file mode 100644 index 00000000..cdb38432 --- /dev/null +++ b/docs/_partials/pages/index/buttons.rst @@ -0,0 +1,154 @@ +Index Buttons +------------- + +By default, the included index buttons are generated based on the mapped Crud +actions. You can customize available buttons by using the ``scaffold.actions`` +key: + +.. code-block:: php + + $action = $this->Crud->action(); + + // restrict to just the add button, which will show up globally + $action->config('scaffold.actions', [ + 'add' + ]); + + // restrict to just the delete/edit/view actions, which are scoped to entities + $action->config('scaffold.actions', [ + 'delete', + 'edit', + 'view', + ]); + +You can also specify configuration for actions, which will be used when +generating action buttons. + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.actions', [ + 'duplicate' => [ + // An alternative title for the action + 'link_title' => 'Duplicate this record', + + // A url that this action should point to + 'url' => ['action' => 'jk-actually-this-action'], + + // The HTTP method to use. Defaults to GET. All others result in + // a ``FormHelper::postLink`` + 'method' => 'POST', + + // Whether to scope the action to a single entity or the entire table + // Options: ``entity``, ``table`` + 'scope' => 'entity', + + // All other options are passed in as normal to the options array + 'other' => 'options', + ] + ]); + +Customizing primaryKey position in the url +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For entity-scoped actions, we will append the ``primaryKey`` of the record to +the link by default: + +.. code-block:: php + + $action = $this->Crud->action(); + + // For the PostsController, will generate + // /posts/translate/english/1 + $action->config('scaffold.actions', [ + 'translate' => [ + 'url' => ['action' => 'translate', 'english'] + ] + ]); + +We can specify the token ``:primaryKey:``. Rather than appending the +``primaryKey``, we will replace this token in the url as many times as +specified. + +.. code-block:: php + + $action = $this->Crud->action(); + + // For the PostsController, will generate + // /posts/translate/1/english + $action->config('scaffold.actions', [ + 'translate' => [ + 'url' => ['action' => 'translate', ':primaryKey:', 'english'] + ] + ]); + +Blacklisting Index Buttons +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you wish to blacklist certain action buttons from showing up, you can use the +``scaffold.actions_blacklist`` configuration key. This can be useful when many +Crud action classes are mapped but should not all be shown on the main UI. + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.actions_blacklist', ['add', 'delete']); + +Action Groups +~~~~~~~~~~~~~ + +You can group actions together using Action Groups. This will generate a +dropdown for the group, and can be controlled by the ``scaffold.action_groups`` +configuration key. + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.action_groups', [ + 'Actions' => [ + 'view', + 'edit', + 'delete', + ], + ]); + +All actions specified in an action group *must* be included in the +``scaffold.actions`` key. + +You can specify multiple action groups: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.action_groups', [ + 'Actions' => [ + 'view', + 'edit', + 'delete', + ], + 'Destructive Actions' => [ + 'disable', + 'delete', + ] + ]); + +Finally, you can also set configuration for each entry in an action group: + +.. code-block:: php + + $action = $this->Crud->action(); + $action->config('scaffold.action_groups', [ + 'Actions' => [ + 'view', + 'edit', + 'delete', + ], + 'Translate' => [ + 'english' => [ + 'url' => ['action' => 'translate', 'english'] + ], + 'spanish' => [ + 'url' => ['action' => 'translate', 'spanish'] + ], + ] + ]); diff --git a/docs/_partials/pages/index/elements.rst b/docs/_partials/pages/index/elements.rst new file mode 100644 index 00000000..f84524a7 --- /dev/null +++ b/docs/_partials/pages/index/elements.rst @@ -0,0 +1,2 @@ +Available Elements +------------------ diff --git a/docs/_partials/pages/index/filters.rst b/docs/_partials/pages/index/filters.rst new file mode 100644 index 00000000..c6657422 --- /dev/null +++ b/docs/_partials/pages/index/filters.rst @@ -0,0 +1,2 @@ +Index Filters +------------- diff --git a/docs/_partials/pages/index/finder-scopes.rst b/docs/_partials/pages/index/finder-scopes.rst new file mode 100644 index 00000000..450f9d8f --- /dev/null +++ b/docs/_partials/pages/index/finder-scopes.rst @@ -0,0 +1,102 @@ +Index Finder Scopes +------------------- + +In some cases, it is helpful to show quick links to pre-filtered datasets. +Rather than force users to select all the filters, *CrudView* enables the ability +to display "Finder Scope" links via the ``scaffold.index_finder_scopes`` +configuration key. These are output below the action header, above the data that +is being paginated. + +The ``scaffold.index_finder_scopes`` option takes an array of finder scope data. +Each sub-array should contain ``title`` and ``finder`` parameters. + +.. code-block:: php + + $this->Crud->action()->config('scaffold.index_finder_scopes', [ + [ + 'title' => __('All'), + 'finder' => 'all', + ], + [ + 'title' => __('Active'), + 'finder' => 'active', + ], + [ + 'title' => __('Inactive'), + 'finder' => 'inactive', + ], + ]); + +The ``all`` finder scope is special. This scope will be displayed by default, +and should always be included in the scope list. It is not automatically +injected. + +Selecting a finder scope will reset any other querystring arguments. Selecting +the ``all`` finder scope will result in being redirected to a page without +querystring arguments. + +Selecting a finder scope *will not* automatically apply the find to your +paginated result-set. This must be done manually. + +Example: Applying Finder Scopes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + This example assumes a simple blog application is being modified, with a + ``posts`` database table containing the fields ``id``, ``active``, + ``title``, ``body``, and ``created``. + +Once a finder scope is selected, it must still be applied to the paginated +result-set. This can be done in the mapped action as follows: + +.. code-block:: php + + public function index() + { + $this->Crud->action()->config('scaffold.index_finder_scopes', [ + [ + 'title' => __('All'), + 'finder' => 'all', + ], + [ + 'title' => __('Active'), + 'finder' => 'active', + ], + [ + 'title' => __('Inactive'), + 'finder' => 'inactive', + ], + ]); + + // We don't need to check for `all` as it is the default findMethod + if (in_array($this->request->query('finder'), ['active', 'inactive'])) { + $this->Crud->action()->config('findMethod', $this->request->query('finder')); + } + return $this->Crud->execute(); + } + +Now that the ``findMethod`` can be mapped, the respective custom find methods +must be created in the ``PostsTable`` class. + +.. code-block:: php + + use Cake\ORM\Query; + use Cake\ORM\Table; + + class PostsTable extends Table + { + public function findActive(Query $query, array $options) + { + $query->where([$this->aliasField('active') => true]); + + return $query; + } + + public function findInactive(Query $query, array $options) + { + $query->where([$this->aliasField('active') => false]); + + return $query; + } + } diff --git a/docs/_partials/pages/index/multiple-pages.rst b/docs/_partials/pages/index/multiple-pages.rst new file mode 100644 index 00000000..853a134a --- /dev/null +++ b/docs/_partials/pages/index/multiple-pages.rst @@ -0,0 +1,12 @@ +Multiple Index Pages +-------------------- + +Sometime you may want more than one index page for a resource to represent +different views to the user. If multiple index pages exist, *CrudView* will +automatically build links at the top of the ``index`` page. Including multiple +views is simple and requires setting the ``index`` view in your action. + +.. code-block:: php + + $action = $this->Crud->action(); + $action->view('index'); diff --git a/docs/_partials/pages/index/viewblocks.rst b/docs/_partials/pages/index/viewblocks.rst new file mode 100644 index 00000000..1a8e34e1 --- /dev/null +++ b/docs/_partials/pages/index/viewblocks.rst @@ -0,0 +1,2 @@ +Available Viewblocks +-------------------- diff --git a/docs/basic-usage.rst b/docs/basic-usage.rst index bf45de3e..edb5f112 100644 --- a/docs/basic-usage.rst +++ b/docs/basic-usage.rst @@ -161,7 +161,7 @@ table: return $this->Crud->execute(); } -Likewise, you can instruct the ``CrudView`` plugin on which actions should be +Likewise, you can instruct the *CrudView* plugin on which actions should be specifically displayed in the index view: .. code-block:: php @@ -177,7 +177,7 @@ Implementing an Add Action -------------------------- If you have read this far, you know almost everything there is to know about -configuring any type of action using ``CrudView``, but being explicit about what +configuring any type of action using *CrudView*, but being explicit about what is available in all of them will not hurt. Implementing the ``Add`` action is done by adding the ``Crud.View`` action to @@ -321,7 +321,7 @@ Pre-Selecting Association Options In order to pre-select the right association options in an ``edit`` action, for example pre-selecting the ``category_id`` in the categories select box, -``CrudView`` will automatically fetch all associations for the entity to be +*CrudView* will automatically fetch all associations for the entity to be modified. This can be wasteful at times, especially if you only allow a few associations diff --git a/docs/customizing-templates.rst b/docs/customizing-templates.rst index 8bf5505a..c7130b92 100644 --- a/docs/customizing-templates.rst +++ b/docs/customizing-templates.rst @@ -1,140 +1,21 @@ Customizing Templates ===================== -Despite ``CrudView`` being quite smart at guessing how to display your data and +Despite *CrudView* being quite smart at guessing how to display your data and having great defaults, it is very often that you need to customize the look and feel of your Admin application. -Formatting fields ------------------ - -The easiest way to modify your fields is to pass options in the ``scaffold.fields`` -configuration key. ``CrudView`` makes use of the ``FormHelper::inputs()`` method -and will pass your array values as options when generating the fields. You can -pass any properties that ``FormHelper::inputs()`` supports. - -.. code-block:: php - - - $action = $this->Crud->action(); - $action->config('scaffold.fields', [ - 'title', - 'thread_id' => [ - 'type' => 'text' - ], - 'featured' => [ - 'checked' => 'checked' - ] - ]); - -Formatting using a Formatter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The most immediate changes you can do in the way data is displayed is by -applying formatters to any of your fields. Whenever you use the -``scaffold.fields`` configuration key, you can specify a formatter to be used. - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.fields', [ - 'title', - 'published_time' => [ - 'formatter' => function ($name, Time $value) { - return $value->nice(); - } - ], - ]); - -You may also specify formatters using the ``scaffold.field_settings`` -configuration key. This is useful if you want to display all fields but wish -to only configure the settings for one or two. - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.field_settings', [ - 'published_time' => [ - 'formatter' => function ($name, Time $value) { - return $value->nice(); - } - ], - ]); - -Formatting with a Callable -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The most immediate way of formatting a field is by passing a callable function -or object. Callable functions or objects will receive 3 arguments: - -* ``$name`` The name of the field to be displayed -* ``$value`` The value of the field that should be outputted -* ``$entity`` The entity object from which the field was extracted - -For example, imagine that when displaying the ``published_time`` property, we -wanted to also display who approved the article: - -.. code-block:: php - - $action->config('scaffold.fields', [ - 'published_time' => [ - 'formatter' => function ($name, $value, $entity) { - return $value->nice() . sprintf(' (Approved by %s)', $entity->approver->name); - } - ] - ]); - -Formatting with an Element -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sometimes you want to execute more complex formatting logic, that may involve -the use of view helpers or outputting HTML. Since building HTML outside of the -view layer is not ideal, you can use the ``element`` formatter for any of your -fields. - -For example, consider this example where we want to link the ``published_time`` -to the same index action by passing some search arguments: - -.. code-block:: php - - $action->config('scaffold.fields', [ - // ... - 'published_time' => [ - 'formatter' => 'element', - 'element' => 'search/published_time', - 'action' => 'index' - ] - ]); - -We have instructed the formatter to use ``search/published_time`` element. Then, -it is just a matter of creating the element file with the right content: - -.. code-block:: php - - // src/Template/Element/search/published_time.ctp - - echo $this->Html->link($value->timeAgoInWords(), [ - 'action' => $options['action'], - 'published_time' => $value->format('Y-m-d') - ]); - -After this, when displaying the ``published_time`` field, there will the will be -a link similar to this one:: - - 4 days ago - -Element files will have available at least the following variables: - -* ``$value``: The value of the field -* ``$field``: The name of the field it is intended to be rendered -* ``$context``: The entity from which the value came from -* ``$options``: The array of options associated to the field as passed in ``scaffold.fields`` +.. include:: /_partials/fields/index.rst +.. include:: /_partials/fields/field-settings.rst +.. include:: /_partials/fields/field-blacklist.rst +.. include:: /_partials/fields/formatter-callable.rst +.. include:: /_partials/fields/formatter-element.rst Changing Field Header or Label Names ------------------------------------ -``CrudView`` infers the name of the field by splitting the field so that it can +*CrudView* infers the name of the field by splitting the field so that it can be read by a human. Sometimes this is just not enough, or you may wish to show an entirely different header in a table or label in a form. @@ -152,10 +33,10 @@ title for any of the fields by using the ``scaffold.fields`` configuration // The rest of the fields to display here ]); -Overriding Template Parts -------------------------- +Overriding Template Elements +---------------------------- -All the ``CrudView`` templates are built from several elements that can be +All the *CrudView* templates are built from several elements that can be overridden by creating them in your own ``src/Template/Element`` folder. The following sections will list all the elements that can be overridden for each type of action. diff --git a/docs/form-pages/customizing-the-form-page.rst b/docs/form-pages/customizing-the-form-page.rst index 492c7fcb..16d7d627 100644 --- a/docs/form-pages/customizing-the-form-page.rst +++ b/docs/form-pages/customizing-the-form-page.rst @@ -1,166 +1,11 @@ Customizing the Form Page ========================= -Customizing Form Fields ------------------------ - -Form fields may be specified via the ``scaffold.fields`` configuration key. -By default, this will contain a list of all columns associated with the primary -entity being edited. The value of this will be sent to ``FormHelper::inputs()``. - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.fields', ['title', 'description']); - -You may also use the ``scaffold.fields_blacklist`` configuration key to remove -fields from the output if you are using the default automatic field population -functionality: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.fields_blacklist', ['created', 'modified']); - -Finally, if you wish to use the default automatic field population functionality -but want to specify settings for a few of the fields, you can use the -``scaffold.field_settings`` configuration key: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.field_settings', [ - 'title' => [ - 'placeholder' => 'the title of the blog post' - ] - ]); - -Form Submission ---------------- - -Form Submission Redirect -~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, the Crud plugin will redirect all form submissions to the -controller's ``index`` action. This can be changed by setting the -``_redirect_url`` view variable: - -.. code-block:: php - - $this->set('_redirect_url', ['action' => 'home']); - -Form Submission Check -~~~~~~~~~~~~~~~~~~~~~ - -By default, closing the a form page in your browser will result in lost data. -However, you may force a user prompt by enabling dirty form checks using the -``scaffold.form_enable_dirty_check`` configuration key: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.form_enable_dirty_check', true); - -Submit Buttons --------------- - -Changing the Submit Button Text -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can change the submit button text from it's default using the -``scaffold.form_submit_button_text`` configuration key. - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.form_submit_button_text', _('Submit')); - -Modifying the Default Extra Buttons -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, we should the following extra buttons for forms: - -- Save & continue editing: Results in a form submission -- Save & create new: Results in a form submission -- Back: A link to the index page - -To use the defaults, you may either omit the configuration key **or** set it -to true: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.form_submit_extra_buttons', true); - -You can also customize this by using the ``scaffold.form_submit_extra_buttons`` -configuration key as follows: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.form_submit_extra_buttons', [ - [ - 'title' => __d('crud', 'Save & continue editing'), - 'options' => ['class' => 'btn btn-success btn-save-continue', 'name' => '_edit', 'value' => true], - 'type' => 'button', - ], - [ - 'title' => __d('crud', 'Save & create new'), - 'options' => ['class' => 'btn btn-success', 'name' => '_add', 'value' => true], - 'type' => 'button', - ], - [ - 'title' => __d('crud', 'Back'), - 'url' => ['action' => 'index'], - 'options' => ['class' => 'btn btn-default', 'role' => 'button', 'value' => true], - 'type' => 'link', - ], - ]); - -Specified values will override the defaults, and will be output in the order -specified. - -Disabling the Default Extra Buttons -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Rather than modifying the default extra buttons, you can also disable them -completely: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.form_submit_extra_buttons', false); - -Custom Blocks -------------- - -The following custom view blocks are available for use within forms: - -- ``form.sidebar``: Rendered on the side of a form. Will also change the form - width -- ``form.before_create``: Rendered before ``FormHelper::create()`` is called -- ``form.after_create``: Rendered after ``FormHelper::create()`` is called -- ``form.before_end``: Rendered before ``FormHelper::end()`` is called -- ``form.after_end``: Rendered after ``FormHelper::end()`` is called - -Form Action Elements ---------------------- - -All the ``CrudView`` templates are built from several elements that can be -overridden by creating them in your own ``src/Template/Element`` folder. The -following sections will list all the elements that can be overridden for each -type of action. - -In general, if you want to override a template, it is a good idea to copy the -original implementation from -``vendor/friendsofcake/crud-view/src/Template/Element`` - -action-header - Create ``src/Template/Element/action-header.ctp`` to have full control over - what is displayed at the top of the page. This is shared across all page - types. - -form/buttons - Create ``src/Template/Element/form/buttons.ctp`` to change what is displayed - for form submission. You can expect the ``$formSubmitButtonText`` and - ``$formSubmitExtraButtons`` variables to be available +.. include:: /_partials/fields/index.rst +.. include:: /_partials/fields/field-settings.rst +.. include:: /_partials/fields/field-blacklist.rst + +.. include:: /_partials/pages/form/submission.rst +.. include:: /_partials/pages/form/submit-buttons.rst +.. include:: /_partials/pages/form/viewblocks.rst +.. include:: /_partials/pages/form/elements.rst diff --git a/docs/general-configuration/breadcrumbs.rst b/docs/general-configuration/breadcrumbs.rst index 89bb6785..ab22e125 100644 --- a/docs/general-configuration/breadcrumbs.rst +++ b/docs/general-configuration/breadcrumbs.rst @@ -6,7 +6,7 @@ Breadcrumbs This functionality is only available for CakePHP 3.3.6 and up. You can indicate the current page's location within a navigational hierarchy -called a breadcrumb. CrudView does not output breadcrumbs by default, but they +called a breadcrumb. *CrudView* does not output breadcrumbs by default, but they may be enabled via the ``scaffold.breadcrumbs`` configuration key. .. warning:: diff --git a/docs/general-configuration/site-title-options.rst b/docs/general-configuration/site-title-options.rst index eda0d13c..ad5a99fd 100644 --- a/docs/general-configuration/site-title-options.rst +++ b/docs/general-configuration/site-title-options.rst @@ -1,12 +1,14 @@ Site Title Options ================== -Every page has what's called the site title on the left side of the menu bar. If you want, you can customize it. +Every page has what's called the site title on the left side of the menu bar. If +you want, you can customize it. Site Title ---------- -You can use the ``scaffold.site_title`` config variable to modify the title. If not set, it will fallback to the following deprecated alternatives: +You can use the ``scaffold.site_title`` config variable to modify the title. If +not set, it will fallback to the following alternatives: - ``Configure::read('CrudView.siteTitle')`` - ``$action->config('scaffold.brand')``: Deprecated @@ -20,7 +22,9 @@ You can use the ``scaffold.site_title`` config variable to modify the title. If Site Title Link --------------- -You can use the ``scaffold.site_title_link`` config variable to modify the title link. If not set, the title will not be made into a link. Both urls and cakephp route arrays are supported. +You can use the ``scaffold.site_title_link`` config variable to modify the title +link. If not set, the title will not be made into a link. Both urls and cakephp +route arrays are supported. .. code-block:: php @@ -29,7 +33,8 @@ You can use the ``scaffold.site_title_link`` config variable to modify the title Site Title Image ---------------- -You can use the ``scaffold.site_title_image`` config variable to modify the title link. If set, it replaces ``scaffold.site_title``. +You can use the ``scaffold.site_title_image`` config variable to modify the +title link. If set, it replaces ``scaffold.site_title``. .. code-block:: php diff --git a/docs/index-pages/components/gallery.rst b/docs/index-pages/components/gallery.rst index 932b2907..3f051a10 100644 --- a/docs/index-pages/components/gallery.rst +++ b/docs/index-pages/components/gallery.rst @@ -50,7 +50,7 @@ configuration key for formatting each field: Default Image ------------- -If no image is retrieved, CrudView will default to the following transparent +If no image is retrieved, *CrudView* will default to the following transparent gif: .. code-block:: html diff --git a/docs/index-pages/components/table.rst b/docs/index-pages/components/table.rst index 118f49a5..43f9db3a 100644 --- a/docs/index-pages/components/table.rst +++ b/docs/index-pages/components/table.rst @@ -30,7 +30,7 @@ To specify the title used in the pagination header, you need to set Index Action Elements --------------------- -All the ``CrudView`` templates are built from several elements that can be +All the *CrudView* templates are built from several elements that can be overridden by creating them in your own ``src/Template/Element`` folder. The following sections will list all the elements that can be overridden for each type of action. diff --git a/docs/index-pages/customizing-the-index-page.rst b/docs/index-pages/customizing-the-index-page.rst index 8e209236..c9e095ae 100644 --- a/docs/index-pages/customizing-the-index-page.rst +++ b/docs/index-pages/customizing-the-index-page.rst @@ -1,387 +1,30 @@ Customizing the Index Page ========================== -Multiple Index Pages --------------------- +Customizing Fields +------------------ -Sometime you may want more than one index page for a resource to represent -different views to the user. If multiple index pages exist, CrudView will -automatically build links at the top of the `index` page. Including multiple -views is simple and requires setting the `index` view in your action. +Fields may be specified via the ``scaffold.fields`` configuration key. By +default, this will contain a list of all columns associated with the Table being +in scope. To limit the fields used, simply specify an array of fields: .. code-block:: php $action = $this->Crud->action(); - $action->view('index'); + $action->config('scaffold.fields', ['title', 'description']); -Formatting fields ------------------ +.. include:: /_partials/fields/field-settings.rst +.. include:: /_partials/fields/field-blacklist.rst +.. include:: /_partials/fields/formatter-callable.rst +.. include:: /_partials/fields/formatter-element.rst -The most immediate changes you can do in the way data is displayed is by -applying formatters to any of your fields. Whenever you use the -``scaffold.fields`` configuration key, you can specify a ``formatter`` to be -used. - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.fields', [ - 'title', - 'published_time' => [ - 'formatter' => function ($name, Time $value) { - return $value->nice(); - } - ], - ]); - -You may also specify formatters using the ``scaffold.field_settings`` -configuration key. This is useful if you want to display all fields but wish to -only configure the settings for one or two. - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.field_settings', [ - 'published_time' => [ - 'formatter' => function ($name, Time $value) { - return $value->nice(); - } - ], - ]); - -Formatting with a Callable -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The most immediate way of formatting a field is by passing a callable function -or object. Callable functions or objects will receive 3 arguments: - -* ``$name`` The name of the field to be displayed -* ``$value`` The value of the field that should be outputted -* ``$entity`` The entity object from which the field was extracted - -For example, imagine that when displaying the ``published_time`` property, we -wanted to also display who approved the article: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.fields', [ - 'published_time' => [ - 'formatter' => function ($name, $value, $entity) { - return $value->nice() . sprintf(' (Approved by %s)', $entity->approver->name); - } - ] - ]); - -Formatting with an Element -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sometimes you want to execute more complex formatting logic, that may involve -the use of view helpers or outputting HTML. Since building HTML outside of the -view layer is not ideal, you can use the ``element`` formatter for any of your -fields. - -For example, consider this example where we want to link the ``published_time`` -to the same index action by passing some search arguments: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.fields', [ - 'published_time' => [ - 'formatter' => 'element', - 'element' => 'search/published_time', - 'action' => 'index' - ] - ]); - -We have instructed the formatter to use ``search/published_time`` element. Then, -it is just a matter of creating the element file with the right content: - -.. code-block:: php - - // src/Template/Element/search/published_time.ctp - - echo $this->Html->link($value->timeAgoInWords(), [ - 'action' => $options['action'], - 'published_time' => $value->format('Y-m-d') - ]); - -After this, when displaying the ``published_time`` field, there will the will be -a link similar to this one:: - - 4 days ago - -Element files will have available at least the following variables: - -* ``$value``: The value of the field -* ``$field``: The name of the field it is intended to be rendered -* ``$context``: The entity from which the value came from -* ``$options``: The array of options associated to the field as passed in ``scaffold.fields`` - -Index Buttons -------------- - -By default, the included index buttons are generated based on the mapped Crud -actions. You can customize available buttons by using the ``scaffold.actions`` -key: - -.. code-block:: php - - $action = $this->Crud->action(); - - // restrict to just the add button, which will show up globally - $action->config('scaffold.actions', [ - 'add' - ]); - - // restrict to just the delete/edit/view actions, which are scoped to entities - $action->config('scaffold.actions', [ - 'delete', - 'edit', - 'view', - ]); - -You can also specify configuration for actions, which will be used when -generating action buttons. - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.actions', [ - 'duplicate' => [ - // An alternative title for the action - 'link_title' => 'Duplicate this record', - - // A url that this action should point to - 'url' => ['action' => 'jk-actually-this-action'], - - // The HTTP method to use. Defaults to GET. All others result in - // a ``FormHelper::postLink`` - 'method' => 'POST', - - // Whether to scope the action to a single entity or the entire table - // Options: ``entity``, ``table`` - 'scope' => 'entity', - - // All other options are passed in as normal to the options array - 'other' => 'options', - ] - ]); - -Customizing primaryKey position in the url -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For entity-scoped actions, we will append the ``primaryKey`` of the record to -the link by default: - -.. code-block:: php - - $action = $this->Crud->action(); - - // For the PostsController, will generate - // /posts/translate/english/1 - $action->config('scaffold.actions', [ - 'translate' => [ - 'url' => ['action' => 'translate', 'english'] - ] - ]); - -We can specify the token ``:primaryKey:``. Rather than appending the -``primaryKey``, we will replace this token in the url as many times as -specified. - -.. code-block:: php - - $action = $this->Crud->action(); - - // For the PostsController, will generate - // /posts/translate/1/english - $action->config('scaffold.actions', [ - 'translate' => [ - 'url' => ['action' => 'translate', ':primaryKey:', 'english'] - ] - ]); - -Blacklisting Index Buttons -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you wish to blacklist certain action buttons from showing up, you can use the -``scaffold.actions_blacklist`` configuration key. This can be useful when many -Crud action classes are mapped but should not all be shown on the main UI. - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.actions_blacklist', ['add', 'delete']); - -Action Groups -~~~~~~~~~~~~~ - -You can group actions together using Action Groups. This will generate a -dropdown for the group, and can be controlled by the ``scaffold.action_groups`` -configuration key. - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.action_groups', [ - 'Actions' => [ - 'view', - 'edit', - 'delete', - ], - ]); - -All actions specified in an action group *must* be included in the -``scaffold.actions`` key. - -You can specify multiple action groups: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.action_groups', [ - 'Actions' => [ - 'view', - 'edit', - 'delete', - ], - 'Destructive Actions' => [ - 'disable', - 'delete', - ] - ]); - -Finally, you can also set configuration for each entry in an action group: - -.. code-block:: php - - $action = $this->Crud->action(); - $action->config('scaffold.action_groups', [ - 'Actions' => [ - 'view', - 'edit', - 'delete', - ], - 'Translate' => [ - 'english' => [ - 'url' => ['action' => 'translate', 'english'] - ], - 'spanish' => [ - 'url' => ['action' => 'translate', 'spanish'] - ], - ] - ]); - -Index Filters -------------- - -Index Finder Scopes -------------------- - -In some cases, it is helpful to show quick links to pre-filtered datasets. -Rather than force users to select all the filters, CrudView enables the ability -to display "Finder Scope" links via the ``scaffold.index_finder_scopes`` -configuration key. These are output below the action header, above the data that -is being paginated. - -The ``scaffold.index_finder_scopes`` option takes an array of finder scope data. -Each sub-array should contain ``title`` and ``finder`` parameters. - -.. code-block:: php - - $this->Crud->action()->config('scaffold.index_finder_scopes', [ - [ - 'title' => __('All'), - 'finder' => 'all', - ], - [ - 'title' => __('Active'), - 'finder' => 'active', - ], - [ - 'title' => __('Inactive'), - 'finder' => 'inactive', - ], - ]); - -The ``all`` finder scope is special. This scope will be displayed by default, -and should always be included in the scope list. It is not automatically -injected. - -Selecting a finder scope will reset any other querystring arguments. Selecting -the ``all`` finder scope will result in being redirected to a page without -querystring arguments. - -Selecting a finder scope *will not* automatically apply the find to your -paginated result-set. This must be done manually. - -Example: Applying Finder Scopes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - This example assumes a simple blog application is being modified, with a - ``posts`` database table containing the fields ``id``, ``active``, - ``title``, ``body``, and ``created``. - -Once a finder scope is selected, it must still be applied to the paginated -result-set. This can be done in the mapped action as follows: - -.. code-block:: php - - public function index() - { - $this->Crud->action()->config('scaffold.index_finder_scopes', [ - [ - 'title' => __('All'), - 'finder' => 'all', - ], - [ - 'title' => __('Active'), - 'finder' => 'active', - ], - [ - 'title' => __('Inactive'), - 'finder' => 'inactive', - ], - ]); - - // We don't need to check for `all` as it is the default findMethod - if (in_array($this->request->query('finder'), ['active', 'inactive'])) { - $this->Crud->action()->config('findMethod', $this->request->query('finder')); - } - return $this->Crud->execute(); - } - -Now that the ``findMethod`` can be mapped, the respective custom find methods -must be created in the ``PostsTable`` class. - -.. code-block:: php - - use Cake\ORM\Query; - use Cake\ORM\Table; - - class PostsTable extends Table - { - public function findActive(Query $query, array $options) - { - $query->where([$this->aliasField('active') => true]); - - return $query; - } - - public function findInactive(Query $query, array $options) - { - $query->where([$this->aliasField('active') => false]); - - return $query; - } - } +.. include:: /_partials/pages/index/buttons.rst +.. include:: /_partials/pages/index/finder-scopes.rst +.. include:: /_partials/pages/index/filters.rst +.. include:: /_partials/pages/index/multiple-pages.rst Custom Download Links --------------------- -Custom Blocks -------------- +.. include:: /_partials/pages/form/viewblocks.rst +.. include:: /_partials/pages/form/elements.rst