Initial commit

kirby-baukasten-main/.github/README.md

@@ -0,0 +1,168 @@
+![Kirby 4 Baukasten Banner by Johann Schopplich](/.github/banner.png)
+
+# Kirby Baukasten
+
+An opinionated, supercharged version of the Kirby Plainkit used internally at Love & Kindness for our clients' sites, with preconfigured tooling and plugins.
+
+> [!NOTE]
+> While Kirby Baukasten is open source & used in production as base for my own projects, it's not properly versioned, and I'm not offering support for it. Instead, it should serve as a reference or guide for implementing certain best practices in your own starterkit.
+
+## Requirements
+
+- PHP 8.2+ with composer
+- Node.js 20+ with pnpm
+
+## Usage
+
+##### Install Composer & Node dependencies with `composer install` and `pnpm install`.
+
+```
+composer install && pnpm install
+```
+
+##### Running the scaffold command with Kirby CLI
+
+```
+kirby baukasten:scaffold
+```
+
+> NOTE: If you don't have the Kirby CLI installed, you will need to run `composer global require getkirby/cli` first.
+
+##### Start the dev server.
+
+```
+pnpm run dev
+```
+
+## Best Practices/Features
+
+### Styling ([Tailwind CSS](https://tailwindcss.com/))
+
+Styling is done with [Tailwind CSS](https://tailwindcss.com/) directly in Kirby templates or snippets.
+
+The only pre-made change to the default theme involves switching from the Mobile-first approach to a Desktop-first approach. I do think that this is still the go-to approach for most projects.
+
+#### What does this mean?
+
+- Don’t use `sm:` to target all non-mobile devices
+- Use unprefixed utilities to target desktop, and override them at smaller breakpoints
+
+### TypeScript / interactivity ([Stimulus](https://stimulus.hotwired.dev/))
+
+I try to avoid using TypeScript as much as possible, but some things are impossible to solve with just HTML + CSS, which is why I'm following a strict Progressive Enhancement policy when needed.
+
+Since Kirby v4, I switched to [Stimulus](https://stimulus.hotwired.dev/) as framework supporting this approach. It's integrated with server-side templates exactly how I need it to be and very similiar to my own, previously used, "micro framework".
+
+More information can be found in [src ▸ controllers ▸ README.md](src/controllers/README.md).
+
+### Block system & the `$block->attr()` helper
+
+Most of our pages are build in a page-builder-like fashion utilizing the Kirby Blocks field. To make it easier to work with, I've implemented a helper that allows you to deploy a block with a set of base attributes.
+
+```php
+<section <?= $block->attr(['class' => 'container']) ?>>
+// <section
+//    class="container"
+//    id="id-from-fields"
+//    data-next-block="footer"
+//    data-prev-block="navigation"
+// >
+```
+
+This function is part of the [`tobimori/kirby-spielzeug`](https://github.com/tobimori/kirby-spielzeug) plugin, which contains a encapsulated set of helpers & tools I use for my projects and serves as the independent foundation for Baukasten.
+
+### View Transitions ([Taxi.js](https://taxi.js.org/))
+
+When working on fancy sites that use a lot of animations, I use [Taxi.js](https://taxi.js.org/) to go the extra-mile & handle view transitions. It's a very lightweight library that has a nice API and is easy to use.
+
+If you don't want to use Taxi:
+
+- remove the `@unseenco/taxi` JS dependency
+- delete the `src/transitions` & `src/renderers` folder
+- remove the `data-taxi` & `data-taxi-view` attributes from `layout.php`
+- remove the related code from `src/index.ts`
+
+### Code Typing
+
+This template tries to make Kirby development more accessible by adding PHP code
+typing and auto completion. Sadly, this doesn't work straight out of the box.
+
+#### Controllers
+
+For controllers & other PHP files, we can add type declarations by importing the classes using
+PHP’s `use`:
+
+```php
+<?php // site/controllers/article.php
+
+use Kirby\Cms\App;
+use Kirby\Cms\Page;
+use Kirby\Cms\Site;
+
+return function (Site $site, App $kirby, Page $page) {
+  […]
+}
+```
+
+#### Templates
+
+Templates will receive variables defined by Kirby (like the `$page` and `$kirby`
+objects), and any other variable you return in a controller. Unfortunately, we can't
+declare them in PHP directly, so we need to
+[use the PHPDoc @var tag](https://github.com/php-fig/fig-standards/blob/2668020622d9d9eaf11d403bc1d26664dfc3ef8e/proposed/phpdoc-tags.md#517-var).
+
+```php
+<?php // site/templates/article.php
+
+/** @var Kirby\Cms\Page $page */
+
+<h1><?= $page->title() ?></h1>
+```
+
+As PHPDoc comments aren't a native PHP feature, this won't affect how our code
+runs, although all IDEs and most code editors (like VS Code) should support
+them.
+
+#### Page Models
+
+If we're using a
+[Page Model](https://getkirby.com/docs/guide/templates/page-models) to expand
+Kirby's default page object, we can use it in our templates in the same way.
+
+```php
+<?php // site/models/article.php
+
+class ArticlePage extends Kirby\Cms\Page {
+  public function getArticleBody(): string {
+    if ($this->content()->body()->isNotEmpty()) {
+      return $this->content()->body()->markdown();
+    }
+    return '';
+  }
+}
+```
+
+```php
+<?php // site/templates/article.php
+
+/** @var ArticlePage $page */
+
+<h1><?= $page->title() ?></h1>
+<?= $page->getArticleBody() ?>
+```
+
+For classes reference, check out the
+[Kirby reference](https://getkirby.com/docs/reference/objects).
+
+#### Auto completion in VS Code
+
+For excellent PHP support in VS Code, we use
+[PHP Intelephense](https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client).
+Follow the Quick Start instructions. Other IDEs like PhpStorm may support this
+out-of-the-box.
+
+## License
+
+[MIT License](.github/LICENSE) © 2021-2024 [Tobias Möritz](https://github.com/tobimori)
+
+Thanks to [Johann](https://github.com/johannschopplich) for the cute banner gecko!