Initial commit

Author: jensscherbl

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 kenshō digital
+
+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,43 @@
+# Snippet for Kirby
+
+Adds controllers to [Kirby][1] snippets.
+
+## General
+
+Brings Kirby’s mechanism for [template controllers][2] to [snippets][3] and [blocks][4]. This provides a unified and consistent way to offload logic and prepare data for cleaner templates and snippets.
+
+### How it works
+
+The plugin uses Kirby’s [native features][5] and [extension points][6]. It looks for a controller whenever a snippet is called, and passes the resulting controller data to the snippet.
+
+Since blocks are also just rendered as snippets under the hood, this works for blocks as well. 
+
+## Installation
+
+```shell
+composer require kenshodigital/kirby-snippet ^1.0
+```
+
+## Usage
+
+Snippet controllers are loaded from a `snippets` folder under the [configured root for controllers][7]. 
+
+Just as [template controllers and templates][8], snippet controllers are identified by the same filename as their corresponding snippets.
+
+| Snippet                           | Snippet Controller                            |
+|-----------------------------------|-----------------------------------------------|
+| `/site/snippets/article.php`      | `/site/controllers/snippets/article.php`      |
+| `/site/snippets/blocks/video.php` | `/site/controllers/snippets/blocks/video.php` |
+
+As usual, snippet controllers are [anonymous functions][9] that receive the [snippet data][10] as arguments and return variables as an associative array. The resulting controller data is then merged with the original snippet data, before everything is passed to the snippet.
+
+ [1]: https://getkirby.com
+ [2]: https://getkirby.com/docs/guide/templates/controllers
+ [3]: https://getkirby.com/docs/guide/templates/snippets
+ [4]: https://getkirby.com/docs/guide/page-builder/block-basics#custom-block-types__custom-block-type-snippet
+ [5]: https://getkirby.com/docs/reference/objects/toolkit/controller
+ [6]: https://getkirby.com/docs/reference/plugins/components/snippet
+ [7]: https://getkirby.com/docs/reference/system/roots/controllers
+ [8]: https://getkirby.com/docs/guide/templates/controllers#the-controllers-directory
+ [9]: https://getkirby.com/docs/guide/templates/controllers#creating-a-controller
+[10]: https://getkirby.com/docs/guide/templates/snippets#passing-variables-to-snippets

components/snippet.php

@@ -0,0 +1,23 @@
+<?php declare(strict_types=1);
+
+use Kirby\Cms\App;
+use Kirby\Template\Snippet;
+use Kirby\Toolkit\Controller;
+
+return function (
+    App               $kirby,
+    string|array|null $name,
+    array             $data  = [],
+    bool              $slots = false,
+): Snippet|string {
+    if (\is_string($name)) {
+        $root           = $kirby->root('controllers');
+        $controller     = Controller::load($root . '/snippets/' . $name . '.php');
+        $controllerData = $controller?->call($kirby, $data);
+
+        if (\is_array($controllerData)) {
+            $data = \array_merge($data, $controllerData);
+        }
+    }
+    return $kirby->nativeComponent('snippet')($kirby, $name, $data, $slots);
+};

composer.json

@@ -0,0 +1,17 @@
+{
+    "name":        "kenshodigital/kirby-snippet",
+    "description": "Adds controllers to Kirby snippets.",
+    "type":        "kirby-plugin",
+    "version":     "1.0.0",
+    "license":     "MIT",
+    "support":
+    {
+        "source": "https://github.com/kenshodigital/kirby-snippet"
+    },
+    "require":
+    {
+        "php":                         "^8.3",
+        "getkirby/cms":                "^4.1",
+        "getkirby/composer-installer": "^1.2"
+    }
+}

index.php

@@ -0,0 +1,9 @@
+<?php declare(strict_types=1);
+
+use Kirby\Cms\App;
+
+App::plugin('kensho/snippet', [
+    'components' => [
+        'snippet' => require __DIR__ . '/components/snippet.php',
+    ],
+]);