Initial commit

.editorconfig

@@ -0,0 +1,20 @@
+# This file is for unifying the coding style for different editors and IDEs
+# editorconfig.org
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.php]
+indent_size = 4
+
+[*.md,*.txt]
+trim_trailing_whitespace = false
+insert_final_newline = false
+
+[composer.json]
+indent_size = 4

.gitignore

@@ -0,0 +1,2 @@
+# OS files
+.DS_Store

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 hana+nils · Büro für Gestaltung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,108 @@
+# Kirby List Methods
+
+Kirby 3 plugin providing `toList()` methods for users, pages and files collections. It creates a comma-separated list of all collection items with an optional conjunction for the last item.
+
+## Installation
+
+### Download
+
+Download and copy this repository to `/site/plugins/list-methods`.
+
+### Git submodule
+
+```
+git submodule add https://github.com/hananils/kirby-list-methods.git site/plugins/list-methods
+```
+
+### Composer
+
+```
+composer require hananils/kirby-list-methods
+```
+
+## Usage
+
+There are different options to create lists from users, pages or files collections:
+
+### Comma-separated list using the primary field
+
+Creates a list separated all items with a comma:
+
+```php
+// using the username
+$users->toList();
+
+// using the page title
+$pages->toList();
+
+// using the filename
+$files->toList();
+```
+
+### Comma-separated list using a custom field or method
+
+Creates a list separated all items with a comma:
+
+```php
+// using the custom method `nickname`
+$users->toList('nickname');
+
+// using the field category
+$pages->toList('category');
+```
+
+### Comma-separated list using a conjunction
+
+Creates a list separated all items with a comma but the last which is connected with a cunjunction:
+
+```php
+// creates, a, list, with, commas and conjunction
+$pages->toList('title', true)
+
+// creates, a, list, with, commas & conjunction
+$pages->toList('title', '&')
+```
+
+The default conjunction `and` is provided in English or German depending on your language settings.
+
+### Comma-separated list with dynamic links
+
+Creates a list linking to a custom destination:
+
+```php
+// link everything to the same URL
+$pages->toList('title', true, 'https://example.com');
+
+// link all pages to their own URL
+$pages->toList('title', true, '{{page.url}}');
+
+// link all pages to a custom URL
+$pages->toList('title', true, 'my-custom-path/{{page.category}}')
+```
+
+You can use Kirby's template syntax with [query language](https://getkirby.com/docs/guide/blueprints/query-language) to fetch any information from the current context, e. g. the current `$user`, `$page` or `$file` object. The `$kirby` and `$site` objects are also available.
+
+### Helper
+
+If you'd like to create a list outside of the Kirby objects, from an array for instance, you can use the `naturalList()` helper. It accepts a flat array and a conjunction, there is no custom key selection or template syntax support:
+
+```php
+$data = ['this', 'that'];
+
+// this, that
+naturalList($data);
+
+// this and that
+naturalList($data, true);
+
+// this & that
+naturalList($data, '&');
+```
+
+## License
+
+MIT
+
+## Credits
+
+- hana+nils · Büro für Gestaltung

composer.json

@@ -0,0 +1,15 @@
+{
+    "name": "hananils/kirby-link-methods",
+    "description": "Methods to convert Kirby objects to natural comma-speparated lists",
+    "type": "kirby-plugin",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "hana+nils · Büro für Gestaltung",
+            "email": "buero@hananils.de"
+        }
+    ],
+    "require": {
+        "getkirby/composer-installer": "^1.1"
+    }
+}

index.php

@@ -0,0 +1,95 @@
+<?php
+
+@include_once __DIR__ . '/vendor/autoload.php';
+
+use Kirby\Toolkit\Template;
+
+Kirby::plugin('hananils/list-methods', [
+    'translations' => [
+        'en' => [
+            'hananils.list-methods.conjunction' => 'and'
+        ],
+        'de' => [
+            'hananils.list-methods.conjunction' => 'und'
+        ]
+    ],
+    'usersMethods' => [
+        'toList' => function ($field = 'username', $conjunction = false, $link = null) {
+            $data = [];
+            foreach ($this as $user) {
+                if ($link !== null) {
+                    $href = Str::template($link, [
+                        'kirby' => kirby(),
+                        'site' => site(),
+                        'user' => $user
+                    ]);
+
+                    $data[] = Html::a($href, $user->$field());
+                } else {
+                    $data[] = $user->$field();
+                }
+            }
+
+            return naturalList($data, $conjunction);
+        }
+    ],
+    'pagesMethods' => [
+        'toList' => function ($field = 'title', $conjunction = false, $link = null) {
+            $data = [];
+            foreach ($this as $page) {
+                if ($link !== null) {
+                    $href = Str::template($link, [
+                        'kirby' => kirby(),
+                        'site' => site(),
+                        'page' => $page
+                    ]);
+
+                    $data[] = Html::a($href, $page->$field());
+                } else {
+                    $data[] = $page->$field();
+                }
+            }
+
+            return naturalList($data, $conjunction);
+        }
+    ],
+    'filesMethods' => [
+        'toList' => function ($field = 'filename', $conjunction = false, $link = null) {
+            $data = [];
+            foreach ($this as $file) {
+                if ($link !== null) {
+                    $href = Str::template($link, [
+                        'kirby' => kirby(),
+                        'site' => site(),
+                        'file' => $file
+                    ]);
+
+                    $data[] = Html::a($href, $file->$field());
+                } else {
+                    $data[] = $file->$field();
+                }
+            }
+
+            return naturalList($data, $conjunction);
+        }
+    ]
+]);
+
+function naturalList($data, $conjunction = false)
+{
+    if ($conjunction === false) {
+        return implode(', ', $data);
+    }
+
+    $last = array_pop($data);
+
+    if ($data) {
+        if ($conjunction === true) {
+            $conjunction = ' ' . t('hananils.list-methods.conjunction') . ' ';
+        }
+
+        return implode(', ', $data) . $conjunction . $last;
+    }
+
+    return $last;
+}