169 lines
5.6 KiB
Markdown
169 lines
5.6 KiB
Markdown
|
||
|
||
# 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!
|