From 5912594c0acdd9a43c9932e6b68a793404e36594 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 27 Jun 2017 00:24:54 -0600 Subject: [PATCH 1/8] feat: Add the ability to specify "format as" buttons Closes #174 --- .../pages/index/download-format-links.rst | 81 +++++++++++++++++++ .../customizing-the-index-page.rst | 5 +- src/Listener/Traits/IndexTypeTrait.php | 14 ++++ src/Template/Element/index/pagination.ctp | 34 +++++--- webroot/css/local.css | 14 ++++ 5 files changed, 132 insertions(+), 16 deletions(-) create mode 100644 docs/_partials/pages/index/download-format-links.rst diff --git a/docs/_partials/pages/index/download-format-links.rst b/docs/_partials/pages/index/download-format-links.rst new file mode 100644 index 00000000..b0c6336f --- /dev/null +++ b/docs/_partials/pages/index/download-format-links.rst @@ -0,0 +1,81 @@ +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 data, where the "key" is +the title to use for the link, and the value is the url. + +.. code-block:: php + + use Cake\Routing\Router; + + // link to the current page, except with extensions `json` or `xml` + $action = $this->Crud->action(); + $action->config('scaffold.index_formats', [ + 'JSON' => Router::url(['_ext' => 'json']), + 'XML' => Router::url(['_ext' => 'xml']), + ]); + +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``, ``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', 'title', 'created']); + } + + $this->Crud->action()->config('scaffold.index_formats', [ + 'CSV' => Router::url(['_ext' => 'csv']), + ]); + return $this->Crud->execute(); + } diff --git a/docs/index-pages/customizing-the-index-page.rst b/docs/index-pages/customizing-the-index-page.rst index c9e095ae..e6830848 100644 --- a/docs/index-pages/customizing-the-index-page.rst +++ b/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 diff --git a/src/Listener/Traits/IndexTypeTrait.php b/src/Listener/Traits/IndexTypeTrait.php index 9baa2d57..10231527 100644 --- a/src/Listener/Traits/IndexTypeTrait.php +++ b/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 * diff --git a/src/Template/Element/index/pagination.ctp b/src/Template/Element/index/pagination.ctp index bdd9bb45..82d47770 100644 --- a/src/Template/Element/index/pagination.ctp +++ b/src/Template/Element/index/pagination.ctp @@ -1,17 +1,27 @@
-
+
+ +
+ Download: + $formatRoute) : ?> + Html->link($formatTitle, $formatRoute, [ + 'target' => '_blank' + ]); ?> + +
+ - Paginator->hasPage(2)) { - echo $this->Paginator->numbers([ - 'prev' => true, - 'next' => true, - ]); - } - ?> +
+ Paginator->hasPage(2)) { + echo $this->Paginator->numbers([ + 'prev' => true, + 'next' => true, + ]); + } + ?> -
- - Paginator->counter('Page {{page}} of {{pages}}, showing {{current}} records out of {{count}} total.'); ?> +

Paginator->counter('Page {{page}} of {{pages}}, showing {{current}} records out of {{count}} total.'); ?>

+
diff --git a/webroot/css/local.css b/webroot/css/local.css index 69ca946a..61ab5220 100644 --- a/webroot/css/local.css +++ b/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; +} From a6882dfd56ea3f5051577d437bb51559b04b8ace Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 27 Jun 2017 01:53:56 -0600 Subject: [PATCH 2/8] docs: cleanup example to add an extra field, active --- docs/_partials/pages/index/download-format-links.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/_partials/pages/index/download-format-links.rst b/docs/_partials/pages/index/download-format-links.rst index b0c6336f..65ec30ca 100644 --- a/docs/_partials/pages/index/download-format-links.rst +++ b/docs/_partials/pages/index/download-format-links.rst @@ -1,5 +1,6 @@ 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 @@ -28,8 +29,8 @@ Example: CSV Download Link .. note:: This example assumes a simple blog application is being modified, with a - ``posts`` database table containing the fields ``id``, ``title``, ``body``, - and ``created``. + ``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 @@ -71,7 +72,7 @@ can be modified to add a CSV Download Link. // 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', 'title', 'created']); + $this->set('_extract', ['id', 'active', 'title', 'created']); } $this->Crud->action()->config('scaffold.index_formats', [ From 3a931adac4632d998951480923de65ce7174e37b Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 27 Jun 2017 01:54:14 -0600 Subject: [PATCH 3/8] refactor: move download format links to element --- src/Template/Element/index/download_formats.ctp | 13 +++++++++++++ src/Template/Element/index/pagination.ctp | 11 +---------- 2 files changed, 14 insertions(+), 10 deletions(-) create mode 100644 src/Template/Element/index/download_formats.ctp diff --git a/src/Template/Element/index/download_formats.ctp b/src/Template/Element/index/download_formats.ctp new file mode 100644 index 00000000..ea8d99c5 --- /dev/null +++ b/src/Template/Element/index/download_formats.ctp @@ -0,0 +1,13 @@ + +
+Download: + $formatRoute) : ?> + Html->link($formatTitle, $formatRoute, [ + 'target' => '_blank' + ]); ?> + +
diff --git a/src/Template/Element/index/pagination.ctp b/src/Template/Element/index/pagination.ctp index 82d47770..501d77d3 100644 --- a/src/Template/Element/index/pagination.ctp +++ b/src/Template/Element/index/pagination.ctp @@ -1,15 +1,6 @@
- -
- Download: - $formatRoute) : ?> - Html->link($formatTitle, $formatRoute, [ - 'target' => '_blank' - ]); ?> - -
- + element('index/download_formats', compact('indexFormats')); ?>
Date: Tue, 27 Jun 2017 01:54:59 -0600 Subject: [PATCH 4/8] docs: document that the querystring should be persisted or any filters will be lost --- docs/_partials/pages/index/download-format-links.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/_partials/pages/index/download-format-links.rst b/docs/_partials/pages/index/download-format-links.rst index 65ec30ca..df05d6b5 100644 --- a/docs/_partials/pages/index/download-format-links.rst +++ b/docs/_partials/pages/index/download-format-links.rst @@ -14,10 +14,12 @@ the title to use for the link, and the value is the url. 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', [ - 'JSON' => Router::url(['_ext' => 'json']), - 'XML' => Router::url(['_ext' => 'xml']), + 'JSON' => Router::url(['_ext' => 'json', '?' => $this->request->query]), + 'XML' => Router::url(['_ext' => 'xml', '?' => $this->request->query]), ]); Download links are displayed near the bottom-left of the index page and will @@ -76,7 +78,7 @@ can be modified to add a CSV Download Link. } $this->Crud->action()->config('scaffold.index_formats', [ - 'CSV' => Router::url(['_ext' => 'csv']), + 'CSV' => Router::url(['_ext' => 'csv', '?' => $this->request->query]), ]); return $this->Crud->execute(); } From fa5036bd3546d0fb77f88edc26382b663d3ce685 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 27 Jun 2017 09:47:41 -0600 Subject: [PATCH 5/8] chore: switch to domain translation --- src/Template/Element/index/download_formats.ctp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Template/Element/index/download_formats.ctp b/src/Template/Element/index/download_formats.ctp index ea8d99c5..9d727d84 100644 --- a/src/Template/Element/index/download_formats.ctp +++ b/src/Template/Element/index/download_formats.ctp @@ -4,7 +4,7 @@ if (empty($indexFormats)) { } ?>
-Download: +: $formatRoute) : ?> Html->link($formatTitle, $formatRoute, [ 'target' => '_blank' From 97655a95a7d8042c0f1d4fcf9f45b9c927321190 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 27 Jun 2017 10:15:30 -0600 Subject: [PATCH 6/8] refactor: swap url with title to match how we do bulk actions --- docs/_partials/pages/index/download-format-links.rst | 6 +++--- src/Template/Element/index/download_formats.ctp | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/_partials/pages/index/download-format-links.rst b/docs/_partials/pages/index/download-format-links.rst index df05d6b5..4f66baf5 100644 --- a/docs/_partials/pages/index/download-format-links.rst +++ b/docs/_partials/pages/index/download-format-links.rst @@ -18,8 +18,8 @@ the title to use for the link, and the value is the url. // currently applied filters $action = $this->Crud->action(); $action->config('scaffold.index_formats', [ - 'JSON' => Router::url(['_ext' => 'json', '?' => $this->request->query]), - 'XML' => Router::url(['_ext' => 'xml', '?' => $this->request->query]), + Router::url(['_ext' => 'json', '?' => $this->request->query]) => 'JSON', + Router::url(['_ext' => 'xml', '?' => $this->request->query]) => 'XML', ]); Download links are displayed near the bottom-left of the index page and will @@ -78,7 +78,7 @@ can be modified to add a CSV Download Link. } $this->Crud->action()->config('scaffold.index_formats', [ - 'CSV' => Router::url(['_ext' => 'csv', '?' => $this->request->query]), + Router::url(['_ext' => 'csv', '?' => $this->request->query]) => 'CSV', ]); return $this->Crud->execute(); } diff --git a/src/Template/Element/index/download_formats.ctp b/src/Template/Element/index/download_formats.ctp index 9d727d84..d1bc1081 100644 --- a/src/Template/Element/index/download_formats.ctp +++ b/src/Template/Element/index/download_formats.ctp @@ -5,7 +5,7 @@ if (empty($indexFormats)) { ?>
: - $formatRoute) : ?> + $formatTitle) : ?> Html->link($formatTitle, $formatRoute, [ 'target' => '_blank' ]); ?> From bccaeb6a1fe05a3aaf734783afb32aaf5f0eb105 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 27 Jun 2017 10:16:24 -0600 Subject: [PATCH 7/8] docs: ensure docs match implementation --- docs/_partials/pages/index/download-format-links.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_partials/pages/index/download-format-links.rst b/docs/_partials/pages/index/download-format-links.rst index 4f66baf5..3b43de27 100644 --- a/docs/_partials/pages/index/download-format-links.rst +++ b/docs/_partials/pages/index/download-format-links.rst @@ -7,7 +7,7 @@ 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 data, where the "key" is -the title to use for the link, and the value is the url. +the url and the value is the title to use for the link. .. code-block:: php From 2c1602e839db9da2368285064c7493dc30ecb6f4 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 27 Jun 2017 10:20:43 -0600 Subject: [PATCH 8/8] refactor: use a sub-array with actual data versus a weird key/value setup. --- .../pages/index/download-format-links.rst | 19 ++++++++++++++----- .../Element/index/download_formats.ctp | 4 ++-- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/_partials/pages/index/download-format-links.rst b/docs/_partials/pages/index/download-format-links.rst index 3b43de27..4325b435 100644 --- a/docs/_partials/pages/index/download-format-links.rst +++ b/docs/_partials/pages/index/download-format-links.rst @@ -6,8 +6,8 @@ The ``scaffold.index_formats`` configuration key can be used to customize 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 data, where the "key" is -the url and the value is the title to use for the link. +The ``scaffold.index_formats`` option takes an array of download format data. +Each sub-array should contain ``title`` and ``url`` parameters. .. code-block:: php @@ -18,8 +18,14 @@ the url and the value is the title to use for the link. // currently applied filters $action = $this->Crud->action(); $action->config('scaffold.index_formats', [ - Router::url(['_ext' => 'json', '?' => $this->request->query]) => 'JSON', - Router::url(['_ext' => 'xml', '?' => $this->request->query]) => 'XML', + [ + '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 @@ -78,7 +84,10 @@ can be modified to add a CSV Download Link. } $this->Crud->action()->config('scaffold.index_formats', [ - Router::url(['_ext' => 'csv', '?' => $this->request->query]) => 'CSV', + [ + 'title' => 'CSV', + 'url' => ['_ext' => 'csv', '?' => $this->request->query] + ], ]); return $this->Crud->execute(); } diff --git a/src/Template/Element/index/download_formats.ctp b/src/Template/Element/index/download_formats.ctp index d1bc1081..4be547f2 100644 --- a/src/Template/Element/index/download_formats.ctp +++ b/src/Template/Element/index/download_formats.ctp @@ -5,8 +5,8 @@ if (empty($indexFormats)) { ?>
: - $formatTitle) : ?> - Html->link($formatTitle, $formatRoute, [ + + Html->link($indexFormat['title'], $indexFormat['url'], [ 'target' => '_blank' ]); ?>