Merge pull request #181 from FriendsOfCake/download-format-links

feat: Add the ability to specify "format as" buttons

docs/_partials/pages/index/download-format-links.rst

@@ -0,0 +1,93 @@
+Download Format Links
+---------------------
+
+The ``scaffold.index_formats`` configuration key can be used to customize
+"Download Links". These are alternative methods of displaying the current index
+page, and can be used to expose the paginated data in JSON, XML, or other
+formats. The output of each format can be customized to your specifications.
+
+The ``scaffold.index_formats`` option takes an array of download format data.
+Each sub-array should contain ``title`` and ``url`` parameters.
+
+.. code-block:: php
+
+    use Cake\Routing\Router;
+
+    // link to the current page, except with extensions `json` or `xml`
+    // include the querystring argument as specified or you will lose any
+    // currently applied filters
+    $action = $this->Crud->action();
+    $action->config('scaffold.index_formats', [
+        [
+            'title' => 'JSON',
+            'url' => ['_ext' => 'json', '?' => $this->request->query]
+        ],
+        [
+            'title' => 'XML',
+            'url' => Router::url(['_ext' => 'xml', '?' => $this->request->query])
+        ],
+    ]);
+
+Download links are displayed near the bottom-left of the index page and will
+open in a new window.
+
+Example: CSV Download Link
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. 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``.
+
+To implement a simple csv download link, the ``friendsofcake/cakephp-csvview``
+plugin should be installed. This plugin will handle the actual rendering of
+csv files at the CakePHP view layer.
+
+.. code-block:: bash
+
+  composer require friendsofcake/cakephp-csvview:~3.0
+
+Next, the ``csv`` extension must be connected so that it can be properly parsed.
+This can be done by modifying the ``config/routes.php`` file. Below is a
+semi-complete example:
+
+.. code-block:: php
+
+    Router::scope('/', function (RouteBuilder $routes) {
+        $routes->extensions(['csv']);
+        // other routes go here
+    });
+
+To complete the initial setup, the RequestHandler should be notified to use the
+``CsvView.View`` class whenever an extension of ``csv`` is detected. The
+following can be added to the ``AppController::initialize()`` to do
+application-wide:
+
+.. code-block:: php
+
+    $this->loadComponent('RequestHandler', [
+        'viewClassMap' => ['csv' => 'CsvView.Csv']
+    ]);
+
+Once the initial setup of the CsvView plugin is complete, the ``index()`` action
+can be modified to add a CSV Download Link.
+
+.. code-block:: php
+
+    public function index()
+    {
+        // only show the id, title, and created fields for csv output
+        if ($this->request->getParam('_ext') === 'csv') {
+            $this->set('_serialize', ['posts']);
+            $this->set('_extract', ['id', 'active', 'title', 'created']);
+        }
+
+        $this->Crud->action()->config('scaffold.index_formats', [
+            [
+                'title' => 'CSV',
+                'url' => ['_ext' => 'csv', '?' => $this->request->query]
+            ],
+        ]);
+        return $this->Crud->execute();
+    }

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

@@ -22,9 +22,6 @@ in scope. To limit the fields used, simply specify an array of fields:
 .. include:: /_partials/pages/index/finder-scopes.rst
 .. include:: /_partials/pages/index/filters.rst
 .. include:: /_partials/pages/index/multiple-pages.rst
-
-Custom Download Links
----------------------
-
+.. include:: /_partials/pages/index/download-format-links.rst
 .. include:: /_partials/pages/form/viewblocks.rst
 .. include:: /_partials/pages/form/elements.rst

src/Listener/Traits/IndexTypeTrait.php

@@ -18,6 +18,7 @@ public function beforeRenderIndexType(Event $event)
 
         $controller = $this->_controller();
         $controller->set('indexFinderScopes', $this->_getIndexFinderScopes());
+        $controller->set('indexFormats', $this->_getIndexFormats());
         $controller->set('indexType', $this->_getIndexType());
         $controller->set('indexTitleField', $indexTitleField);
         $controller->set('indexBodyField', $indexBodyField);
@@ -41,6 +42,19 @@ protected function _getIndexFinderScopes()
         return $action->config('scaffold.index_finder_scopes') ?: [];
     }
 
+    /**
+     * Returns a list of index formats, where the key is the link title
+     * and the value is the url to route to
+     *
+     * @return string
+     */
+    protected function _getIndexFormats()
+    {
+        $action = $this->_action();
+
+        return $action->config('scaffold.index_formats') ?: [];
+    }
+
     /**
      * Returns the index type to show on scaffolded view
      *

src/Template/Element/index/download_formats.ctp

@@ -0,0 +1,13 @@
+<?php
+if (empty($indexFormats)) {
+    return;
+}
+?>
+<div class="download-links">
+<?= __d('crud', 'Download') ?>:
+<?php foreach ($indexFormats as $indexFormat) : ?>
+    <?= $this->Html->link($indexFormat['title'], $indexFormat['url'], [
+        'target' => '_blank'
+    ]); ?>
+<?php endforeach; ?>
+</div>

src/Template/Element/index/pagination.ctp

@@ -1,17 +1,18 @@
 <div class="row">
-    <div class="col-md-12">
+    <div class="col-md-12 pagination-wrapper">
+        <?= $this->element('index/download_formats', compact('indexFormats')); ?>
 
-        <?php
-        if ($this->Paginator->hasPage(2)) {
-            echo $this->Paginator->numbers([
-                'prev' => true,
-                'next' => true,
-            ]);
-        }
-        ?>
+        <div class="pagination-container">
+            <?php
+            if ($this->Paginator->hasPage(2)) {
+                echo $this->Paginator->numbers([
+                    'prev' => true,
+                    'next' => true,
+                ]);
+            }
+            ?>
 
-        <br />
-
-        <?= $this->Paginator->counter('Page {{page}} of {{pages}}, showing {{current}} records out of {{count}} total.'); ?>
+            <p><?= $this->Paginator->counter('Page {{page}} of {{pages}}, showing {{current}} records out of {{count}} total.'); ?></p>
+        </div>
     </div>
 </div>

webroot/css/local.css

@@ -87,3 +87,17 @@ div.actions-wrapper {
 .gallery-content {
     text-align: center;
 }
+.pagination-wrapper {
+    clear: both;
+    margin: 20px 0;
+    text-align: center;
+}
+.download-links {
+    float: left;
+}
+.pagination-container {
+    float: right
+}
+.pagination-container .pagination {
+    margin: 0;
+}