refactor: cleanup documentation

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']);

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
+        ]
+    ]);

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);
+            }
+        ],
+    ]);

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::
+
+  <a href="/articles?published_time=2015-06-23">4 days ago</a>
+
+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``

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'
+        ]
+    ]);

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

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

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

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