Merge pull request #155 from FriendsOfCake/custom-index-pages

Custom index pages

docs/contents.rst

@@ -12,9 +12,14 @@ Contents
     Installation <installation>
     Quick Start <quick-start>
 
+    Basic Usage <basic-usage>
+    Customizing Templates <customizing-templates>
+
     Site Title Options <general-configuration/site-title-options>
     Sidebar Navigation <general-configuration/sidebar-navigation>
     Utility Navigation <general-configuration/utility-navigation>
 
-    Basic Usage <basic-usage>
-    Customizing Templates <customizing-templates>
+    Customizing the Index Page <index-pages/customizing-the-index-page>
+    Custom Index <index-pages/components/custom>
+    Index as a Blog <index-pages/components/blog>
+    Index as a Table <index-pages/components/table>

docs/customizing-templates.rst

@@ -21,7 +21,7 @@ pass any properties that ``FormHelper::inputs()`` supports.
 
     class ArticlesController extends AppController
     {
-        public function index()
+        public function add()
         {
             $action = $this->Crud->action();
             $action->config('scaffold.fields', [
@@ -37,7 +37,7 @@ pass any properties that ``FormHelper::inputs()`` supports.
         }
     }
 
-Formating using a Formatter
+Formatting using a Formatter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The most immediate changes you can do in the way data is displayed is by
@@ -250,35 +250,3 @@ 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``
-
-Index Action Elements
-~~~~~~~~~~~~~~~~~~~~~
-
-search
-  Create ``src/Template/Element/search.ctp`` for having full control over how
-  the search filters are displayed in your pagination table. You can expect the
-  ``$searchInputs`` and ``$searchOptions`` variables to be available
-
-index/pagination
-  Create ``src/Template/Element/index/pagination.ctp`` To implement your own
-  pagination links and counter.
-
-index/bulk_actions/table
-  Create ``src/Template/Element/index/bulk_actions/table.ctp`` for changing how
-  the bulk action inputs for the whole table. You can expect the
-  ``$bulkActions``, ``$primaryKey`` and ``$singularVar`` variables to be
-  available.
-
-index/bulk_actions/record
-  Create ``src/Template/Element/index/bulk_actions/record.ctp`` for changing how
-  the bulk action inputs for each row are displayed. You can expect the
-  ``$bulkActions``, ``$primaryKey`` and ``$singularVar`` variables to be
-  available.
-
-index/bulk_actions/form_start
-  Create ``src/Template/Element/index/bulk_actions/form_start.ctp`` To customize
-  the Form create call for bulk actions
-
-index/bulk_actions/form_end
-  Create ``src/Template/Element/index/bulk_actions/form_end.ctp`` To customize
-  the Form end call for bulk actions

docs/index-pages/components/blog.rst

@@ -0,0 +1,23 @@
+Index as a Blog
+===============
+
+Render your index page as a set of posts.
+
+.. code-block:: php
+
+    $action = $this->Crud->action();
+    $action->config('scaffold.index_type', 'blog');
+
+Customizing the Blog fields
+---------------------------
+
+The post has two main options:
+
+- ``index_blog_title_field``: (default: ``title``) Controls the field used for the blog title.
+- ``index_blog_body_field``: (default: ``body``) Controls the field used for the blog body.
+
+.. code-block:: php
+
+    $action = $this->Crud->action();
+    $action->config('scaffold.index_blog_title_field', 'name');
+    $action->config('scaffold.index_blog_body_field', 'content');

docs/index-pages/components/custom.rst

@@ -0,0 +1,22 @@
+Custom Index
+============
+
+To use a custom index element, you can set the ``scaffold.index_type`` config option.
+
+.. code-block:: php
+
+    $action = $this->Crud->action();
+    $action->config('scaffold.index_type', 'an_element');
+
+Available Variables
+-------------------
+
+The following variables are available for use within the element:
+
+- `fields`: List of fields to show and their options
+- `actions`: A list of actions that can be displayed for the index page.
+- `bulkActions`: A list of bulk actions associated with this resource
+- `primaryKey`: The name of the record's primary key field.
+- `singularVar`: The singular version of the resource name.
+- `viewVar`: Reference to the name of the variable holding all records.
+- plural of `viewVar`: The set of records.

docs/index-pages/components/table.rst

@@ -0,0 +1,76 @@
+Index as a Table
+================
+
+By default, the index page is a table with each of the models content columns
+and links to show, edit and delete the object. There are many ways to
+customize what gets displayed.
+
+Defining Columns
+----------------
+
+By default, all fields are displayed on the ``index`` page. To display an
+attribute or a method on a record, you can use the ``scaffold.fields``
+config option.
+
+.. code-block:: php
+
+    $action = $this->Crud->action();
+    $action->config('scaffold.fields', ['id', 'title']);
+
+To specify the title used in the pagination header, you need to set
+``scaffold.fields`` to an associative array and use the ``title`` parameter:
+
+.. code-block:: php
+
+    $action = $this->Crud->action();
+    $action->config('scaffold.fields', [
+      'id',
+      'title' => [
+        'title' => __('Blog Post')
+      ]
+    ]);
+
+Index 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``
+
+search
+  Create ``src/Template/Element/search.ctp`` for having full control over how
+  the search filters are displayed in your pagination table. You can expect the
+  ``$searchInputs`` and ``$searchOptions`` variables to be available
+
+index/table
+  Create ``src/Template/Element/index/table.ctp`` To implement your own
+  table.
+
+index/pagination
+  Create ``src/Template/Element/index/pagination.ctp`` To implement your own
+  pagination links and counter.
+
+index/bulk_actions/table
+  Create ``src/Template/Element/index/bulk_actions/table.ctp`` for changing how
+  the bulk action inputs for the whole table. You can expect the
+  ``$bulkActions``, ``$primaryKey`` and ``$singularVar`` variables to be
+  available.
+
+index/bulk_actions/record
+  Create ``src/Template/Element/index/bulk_actions/record.ctp`` for changing how
+  the bulk action inputs for each row are displayed. You can expect the
+  ``$bulkActions``, ``$primaryKey`` and ``$singularVar`` variables to be
+  available.
+
+index/bulk_actions/form_start
+  Create ``src/Template/Element/index/bulk_actions/form_start.ctp`` To customize
+  the Form create call for bulk actions
+
+index/bulk_actions/form_end
+  Create ``src/Template/Element/index/bulk_actions/form_end.ctp`` To customize
+  the Form end call for bulk actions

docs/index-pages/customizing-the-index-page.rst

@@ -0,0 +1,132 @@
+Customizing the Index Page
+==========================
+
+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');
+
+Formatting fields
+-----------------
+
+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::
+
+  <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``
+
+
+Index Buttons
+-------------
+
+Index Filters
+-------------
+
+Index Pagination
+----------------
+
+Custom Download Links
+---------------------
+
+Custom Blocks
+-------------