Merge pull request #8 from johannschopplich/chore/readme-update

chore: raise Kirby's composer installer version
refactor: remove unused namespaces
refactor: re-use more pages logic from parent
feat: add flip option
chore: improve readme and fix some typos

Thx @johannschopplich

composer.json

@@ -9,7 +9,7 @@
     }
   ],
   "require": {
-    "getkirby/composer-installer": "^1.1"
+    "getkirby/composer-installer": "^1.2"
   },
   "license": "ISC"
 }

index.js

@@ -1,7 +1,7 @@
-panel.plugin('rasteiner/k3-pagesdisplay-section', {
+panel.plugin("rasteiner/k3-pagesdisplay-section", {
   components: {
-    'k-pagesdisplay-section': {
-      extends: 'k-pages-section'
-    }
-  }
+    "k-pagesdisplay-section": {
+      extends: "k-pages-section",
+    },
+  },
 });

index.php

@@ -1,12 +1,7 @@
 <?php
 
-use Kirby\Cms\App;
-use Kirby\Cms\Blueprint;
-use Kirby\Toolkit\F;
-use Kirby\Toolkit\Str;
-
-Kirby::plugin('rasteiner/k3-pagesdisplay-section', [
+\Kirby\Cms\App::plugin('rasteiner/k3-pagesdisplay-section', [
     'sections' => [
-        'pagesdisplay' => require __DIR__ . DIRECTORY_SEPARATOR . 'src' . DIRECTORY_SEPARATOR . 'PagesDisplaySection.php'
+        'pagesdisplay' => require __DIR__ . '/src/PagesDisplaySection.php'
     ]
 ]);

readme.md

@@ -1,20 +1,41 @@
-Display any page list in a Section. Any parent, many parents, filtered, don't care.   
-On the other hand, you won't be able to sort the list or add new pages to it.
+# Pages Display Section
 
-# Install
-## Download Zip file
+Display any page list in a section using [Kirby's query language](https://getkirby.com/docs/guide/blueprints/query-language). Any parent, many parents, filtered, don't care.
 
-Copy plugin folder into `site/plugins`
+> ℹ️ Note: While this functionality gives you a lot of freedom, you won't be able to sort the list or add new pages to the query.
 
-## Composer
-Run `composer require rasteiner/k3-pagesdisplay-section`.
+## Installation
 
-# Usage
-You select and filter the pages with the query language, with a `query` property in the section yaml. 
-You can start the query with `site`, `page` (refers to the current page), `pages` (which is equal to `site.pages`), or `kirby` (mainly to use `kirby.collection`).
+### Download
+
+Download and copy this repository to `/site/plugins/k3-pagesdisplay-section`.
+
+### Git submodule
+
+```bash
+git submodule add https://github.com/rasteiner/k3-pagesdisplay-section.git site/plugins/rasteiner/k3-pagesdisplay-section
+```
+
+### Composer
+
+```bash
+composer require rasteiner/k3-pagesdisplay-section
+```
+
+## Usage
+
+Create a section of your liking and add a `query` property. Within the query you may select and filter any pages by making use of [Kirby's query language](https://getkirby.com/docs/guide/blueprints/query-language).
+
+You can start the query with one of the following variables:
+
+- `site`
+- `page` (refers to the current page)
+- `pages` (which equals `site.pages`)
+- `kirby` (mainly to use with `kirby.collection`)
 
 ## Example
-Show all pages that have "Foo" in their title:
+
+### All pages with `Foo` in their title
 
 ```yaml
 sections:
@@ -24,8 +45,7 @@ sections:
     query: site.index.filterBy('title', '*=', 'Foo')
 ```
 
-
-Show sibling pages (exclude current page):
+## Sibling pages (exclude the current page)
 
 ```yaml
 sections:

src/PagesDisplaySection.php

@@ -1,61 +1,78 @@
 <?php
 
 use Kirby\Exception\InvalidArgumentException;
-use Kirby\Toolkit\Str;
-use Kirby\Toolkit\Query;
 use Kirby\Cms\Section;
+use Kirby\Toolkit\Query;
 
 $base = Section::$types['pages'];
-
-return array_replace_recursive($base, [
+$extension = [
     'props' => [
         'sortable' => function (bool $sortable = true) {
             return false;
         },
-        'query' => function(string $query = 'page.children') {
+        'query' => function (string $query = 'page.children') {
             return $query;
         }
     ],
     'computed' => [
-       'pages' => function () {
+        'pages' => function () {
+            $kirby = kirby();
             $q = new Query($this->query, [
-                'site' => site(),
-                'page' => $this->model(),
-                'pages' => site()->pages(),
-                'kirby' => kirby()
+                'kirby' => $kirby,
+                'site' => $kirby->site(),
+                'pages' => $kirby->site()->pages(),
+                'page' => $this->model()
             ]);
 
             $pages = $q->result();
 
-            if(is_a($pages, 'Kirby\\Cms\\Pages')) {
-                // show only readable
-                $pages = $pages->filterBy("isReadable", true);
-
-                // sort
-                if ($this->sortBy) {
-                    $pages = $pages->sortBy(...Str::split($this->sortBy, ' '));
-                }
-
-                // pagination
-                $pages = $pages->paginate([
-                    'page' => $this->page,
-                    'limit' => $this->limit
-                ]);
-
-                return $pages;
-            } else {
+            if (!is_a($pages, \Kirby\Cms\Pages::class)) {
+                $result = $pages === null ? 'null' : get_class($pages);
                 throw new InvalidArgumentException(
-                    'Invalid query result - Result must be of type Kirby\\Cms\\Pages, ' 
-                    . ($pages === NULL ? 'NULL' : get_class($pages))
-                    . ' given.'
+                    "Query result must be of type \"Kirby\\Cms\\Pages\", \"{$result}\" given"
                 );
             }
+
+            // Loop for the best performance
+            foreach ($pages->data as $id => $page) {
+                // Remove all protected pages
+                if (!$page->isReadable()) {
+                    unset($pages->data[$id]);
+                    continue;
+                }
+
+                // Filter by all set templates
+                if ($this->templates && !in_array($page->intendedTemplate()->name(), $this->templates)) {
+                    unset($pages->data[$id]);
+                    continue;
+                }
+            }
+
+            // Sort pages
+            if ($this->sortBy) {
+                $pages = $pages->sort(...$pages::sortArgs($this->sortBy));
+            }
+
+            // Flip pages
+            if ($this->flip) {
+                $pages = $pages->flip();
+            }
+
+            // Add pagination
+            $pages = $pages->paginate([
+                'page' => $this->page,
+                'limit' => $this->limit
+            ]);
+
+            return $pages;
         },
         'add' => function () {
             return false;
         },
         'sortable' => function () {
             return false;
         }
-    ],
-]);
+    ]
+];
+
+return array_replace_recursive($base, $extension);