Kirby Template Sugar

A lightweight template compiler that adds some [syntactic sugar](https://en.wikipedia.org/wiki/Syntactic_sugar) to Kirby's php templates. Kirby's new [snippets with slots](https://getkirby.com/docs/guide/templates/snippets#passing-slots-to-snippets) allow you to adapt a component-based workflow, similar to Laravel blade templates or javascript frameworks like Vue. However, the plain php syntax can be verbose. So with some template sugar you can write this: instead of this: ## How Does It Work Your template files need to be compiled into regular php, similar to how other template languages work. But the goal of this project is not to create a new full-fledged template language for Kirby. Instead it embraces the existing php templates and just adds a little sugar where they tend to get too messy. You still write php/html (with syntax highlighting, intellisense, ...) and add a special ``, `` or `` tag here and there to keep things tidy. ## Getting Started The easiest way to get started is to check out one of the examples: - Use the [CLI example](https://github.com/arnoson/kirby-template-sugar/tree/main/examples/cli) if you want a minimal starter kit that doesn't rely on any other build tools. - Use the [Vite example](https://github.com/arnoson/kirby-template-sugar/tree/main/examples/vite) to compile your templates alongside your other frontend assets. To start manually (or convert an existing project), have a look at the [CLI](https://github.com/arnoson/kirby-template-sugar/tree/main/packages/npm-package#cli-usage) or the [Vite plugin](https://github.com/arnoson/kirby-template-sugar/tree/main/packages/vite-plugin). And make sure you also install the [Kirby plugin](https://github.com/arnoson/kirby-template-sugar/tree/main/packages/kirby-plugin). ## Syntax ### Snippets Snippets can have slots or be self-closing:

With Sugar	Compiled

### Props and attributes Snippets can have `props`, which are passed directly to the snippet, and attributes, which are grouped into an `$attr` variable passed to the snippet along with the props. Props start with `$` (like `$open` and `$items`) and attributes are just specified like regular html attributes (`class`, `aria-label`). If you want to pass a php expression to a snippet, e.g.: `items => $site->children()->listed()`, you just have to wrap it in php tags (see the code below):

With Sugar	Compiled

Well... actually the compiled code looks like this. To make debugging easier, the line numbers will stay the same:

With Sugar	Compiled

This makes it super easy to implement a snippet like this: Or even better with @fabianmichael's fantastic [kirby-template-attributes](https://github.com/fabianmichael/kirby-template-attributes) ### Prop shorthand syntax If your prop names and php variable names are the same you can use the shorthand syntax: Would be the same as: ### CSS Variables You can assign CSS variables with an attribute-like syntax. This works on any tag, not just `` and ``. Note: you can omit the `var()` if you are referencing another variable name (like `--some-variable`).

With Sugar	Compiled

### Layouts If you also use Kirby's [layouts](https://github.com/getkirby/layouts) you can define them with the `` tag:

With Sugar	Compiled

Or with slots and even props and attributes

With Sugar	Compiled

## Debugging If you are using [xdebug](https://xdebug.org/), you won't be able to set breakpoints through your IDE, but you can use `xdebug_break()` in your source file. To remove the breakpoint, simply remove `xdebug_break()` and save the source file again. ## Credits - [magic-string](https://github.com/rich-harris/magic-string) - [glob](https://github.com/isaacs/node-glob) - [CAC](https://github.com/cacjs/cac) - [chokidar](https://github.com/paulmillr/chokidar)