Skip to content

Commit

Permalink
GITBOOK-2: Describe autoprefixing feature
Browse files Browse the repository at this point in the history
  • Loading branch information
jakubtobiasz authored and gitbook-bot committed Apr 30, 2024
1 parent b3143e0 commit b68af8c
Show file tree
Hide file tree
Showing 13 changed files with 395 additions and 0 deletions.
Binary file added docs/.gitbook/assets/image.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 2 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# About Sylius Stack

16 changes: 16 additions & 0 deletions docs/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Table of contents

* [About Sylius Stack](README.md)

## 🌱 Twig Hooks

* [Getting started](twig-hooks/getting-started.md)
* [Passing data to your hookables](twig-hooks/passing-data-to-your-hookables.md)
* [Making your hookables configurable](twig-hooks/making-your-hookables-configurable.md)
* [Composable Layouts with a predictable structure](twig-hooks/composable-layouts-with-a-predictable-structure.md)
* [Advanced](twig-hooks/advanced/README.md)
* [Autoprefixing feature](twig-hooks/advanced/autoprefixing-feature.md)
* [Ergonomic work with hooks](twig-hooks/advanced/ergonomic-work-with-hooks.md)
* [Metadata objects](twig-hooks/advanced/metadata-objects.md)
* [Multiple hooks inside a single template](twig-hooks/advanced/multiple-hooks-inside-a-single-template.md)
* [Overriding hookables](twig-hooks/advanced/overriding-hookables.md)
2 changes: 2 additions & 0 deletions docs/twig-hooks/advanced/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Advanced

109 changes: 109 additions & 0 deletions docs/twig-hooks/advanced/autoprefixing-feature.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# Autoprefixing feature

{% hint style="warning" %}
`Autoprefixing` is turned off by default. If you want to use this feature you need to set the `enable_autoprefixing` setting to `true` in your `config/packages/twig_hooks.yaml` file:

```
twig_hooks:
# ...
enable_autoprefixing: true
# ...
```
{% endhint %}

When you are creating a bundle, or a bigger project like [Sylius](https://sylius.com), you might want to rely fully on Twig Hooks to provide easy and flexible way of modifying and extending your views.

Enabling the autoprefixing feature might improve your developer experience. This feature is crucial for creating [composable-layouts-with-a-predictable-structure.md](../composable-layouts-with-a-predictable-structure.md "mention").

{% hint style="info" %}
If you did not read the [composable-layouts-with-a-predictable-structure.md](../composable-layouts-with-a-predictable-structure.md "mention")section we encourage you to do it before you read more about the autoprefixing feature. 
{% endhint %}

The mechanism of autoprefixing is pretty simple. We check if there are any prefixes, then we iterate over them and prepend the hook name with a given prefix.

### Defining prefixes

Prefixes by default are injected automatically, and they are the name of the hook where the hookable is rendered.

> As a developer I define the **index.form** hook in my template
>
> And I define the **some\_field** hookable in it
>
> So when I check prefixes **inside** the **some\_field** hookable I should get `index.form`
In case we deal with a complex hook:

> As a developer I define the **index.form, common.form** hook in my template
>
> And I define the **some\_field** hookable in **index.form**
>
> So when I check prefixes **inside** the **some\_field** hookable I should get `index.form` and `common.form`
If for some reason you want to take the control over the passed prefixes, you can override existing prefixes using the `_prefixes` magic variable when you are creating a hook inside a Twig template:

{% code title="index.html.twig" lineNumbers="true" %}
```twig
{% hook 'index.form with {
_prefixes: ['my_custom_prefix']
} %}
```
{% endcode %}

From now, only the value of `_prefixes` will be taken into account.

### Example

{% code title="index.html.twig" lineNumbers="true" %}
```twig
{% raw %}
{% hook 'app.index' %}
{% endraw %}
{#
# index.html.twig is an entry template, so it is not an hookable
#}
```
{% endcode %}

{% code title="index/content.html.twig" lineNumbers="true" %}
```twig
{% raw %}
{% hook 'content' %}
{#
# this template is an hookable, and is hooked into app.index
#}
{#
# so {% hook 'content' %} this is a shorter form of {% hook 'app.index.content' %}
{% endraw %}
# when autoprefixing is turned on
#}
```
{% endcode %}

{% code title="index/content/button.html.twig" lineNumbers="true" %}
```twig
<button>Click me!</button>
```
{% endcode %}

The configuration for the hooks and hookables above is:

{% code title="config/packages/twig_hooks.yaml" lineNumbers="true" %}
```yaml
twig_hooks:
hooks:
'app.index':
content:
template: 'index/content.html.twig'

'app.index.content':
button:
template: 'index/content/button.html.twig
```
{% endcode %}
{% hint style="info" %}
The structure of directories above does not matter, all templates can be on the same level of nesting. However, in this example we are following creating [composable-layouts-with-a-predictable-structure.md](../composable-layouts-with-a-predictable-structure.md "mention") guide.
{% endhint %}
2 changes: 2 additions & 0 deletions docs/twig-hooks/advanced/ergonomic-work-with-hooks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Ergonomic work with hooks

2 changes: 2 additions & 0 deletions docs/twig-hooks/advanced/metadata-objects.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Metadata objects

Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Multiple hooks inside a single template

2 changes: 2 additions & 0 deletions docs/twig-hooks/advanced/overriding-hookables.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Overriding hookables

Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Composable Layouts with a predictable structure

128 changes: 128 additions & 0 deletions docs/twig-hooks/getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
description: >-
Twig Hooks are a robust and powerful alternative to the Sonata Block Events
and the old Sylius Template Events systems.
---

# Getting started

### Main features

* built-in support for _Twig templates_, _Twig Components_ and _Symfony Live Components_
* adjustability
* autoprefixing hooks
* configurable hookables
* priority mechanism
* easy enable/disable mechanism per each hook

### Installation

Install the package using Composer and Symfony Flex:

```bash
composer require sylius/twig-hooks
```

### Your first hook & hookable

Once Twig Hooks installed, you can open **any** twig file and define your first hook.

{% code title="some.html.twig" %}
```twig
{# ... #}
{% raw %}
{% hook 'my_first_hook' %}
{% endraw %}
{# ... #}
```
{% endcode %}

From now the `my_first_hook` is a unique name we will use to hook into that place.

{% hint style="success" %}
The ideal hook name:

* is consisted of small case letters
* has logical parts separated with using dots (`.`)
* has each part separated with underscore (`_`) if it is consisted of multiple words



<mark style="color:green;">Recommended:</mark>

* `index`
* `index.sidebar`
* `index.top_menu`



<mark style="color:red;">Not recommended:</mark>

* index
* indextopmenu
{% endhint %}

#### Hooking into a hook

For the purpose of this example, let's consider we want to render the `some_block.html.twig` template inside the `my_first_hook` hook. First step is to create a `twig_hooks.yaml` file (or any other format you use) under the `config/packages/` directory (of course, if you do not have already one).

Now, we can define our first hookable with the following configuration:

{% code title="config/packages/twig_hooks.yaml" lineNumbers="true" %}
```yaml
twig_hooks:
hooks:
'my_first_hook':
some_block:
template: 'some_block.html.twig'
```
{% endcode %}
Decomposing the example above we can notice that:
1. `twig_hooks` is just a main key for the Twig Hooks configuration
2. `hooks` is a configuration key for defining hookables per hook
3. `my_first_hook` is our hook name, defined on the Twig file level
4. `some_block` is a name of our hookable, it can be any string, but it should be unique for a given hook unless you want to override the existing hookable (if you want to read more about overriding hookables check the [overriding-hookables.md](advanced/overriding-hookables.md "mention")section)
5. finally we have a `template` key that defines what template should be rendered inside the `my_first_hook` hook

#### Possible hookable configuration options

Depending on the hookable template, we can pass different configuration options while defining hookables:

{% tabs %}
{% tab title="Hookable Template" %}
{% code lineNumbers="true" %}
```yaml
twig_hooks:
hooks:
'my_first_hook':
some_block:
template: 'some_block.html.twig'
enabled: true # whether the hookable is enabled
context: [] # key-value pair that will be passed to the context bag
configuration: [] # key-value pair that will be passed to the configuration bag
priority: 0 # priority, the higher number, the earlier hookable will be hooked
```
{% endcode %}
{% endtab %}

{% tab title="Hookable Component" %}
{% code title="" %}
```yaml
twig_hooks:
hooks:
'my_first_hook':
some_block:
component: 'app:block' # component key
enabled: true # whether the hookable is enabled
context: [] # key-value pair that will be passed to the context bag
props: [] # key-value pair that will be passed to our component as props
configuration: [] # key-value pair that will be passed to the configuration bag
priority: 0 # priority, the higher number, the earlier hookable will be hooked
```
{% endcode %}
{% endtab %}
{% endtabs %}
51 changes: 51 additions & 0 deletions docs/twig-hooks/making-your-hookables-configurable.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Making your hookables configurable

Sometimes when you are creating a bundle or a reusable template for different hookables, you might want to provide a way to adjust it to a given context. Thanks to the configuration data bag, you are able to achieve it easily.

Configuration can be defined only while defining a hookable, and is accessibly with using `hookable_metadata.configuration.<key_name>` or `get_hookable_configuration().<key_name>`.

#### Example

{% code title="index.html.twig" lineNumbers="true" %}
```
{#
# we assume there is a `form` variable holding a `FormView` instance passed
# from the controller
#}
<div class="container">
{{ form_start(form) }}
{{ form_errors(form) }}
{{ form_widget(form._token) }}
{% raw %}
{% hook 'index.form' with { form } %}
{% endraw %}
{{ form_end(form, {render_rest: false}) }}
</div>
```
{% endcode %}

{% code title="generic_field.html.twig" lineNumbers="true" %}
```
<div class="{{ hookable_metadata.configuration.attr.class|default("field) }}">
{{ form_row(
hookable_metadata.context.form[hookable_metadata.configuration.field_name]
) }}
</div>
```
{% endcode %}

{% code title="twig_hooks.yaml" lineNumbers="true" %}
```
twig_hooks:
hooks:
'index.form':
name:
template: 'generic_field.html.twig'
configuration:
field_name: 'name'
attr:
class: 'field special-field'
```
{% endcode %}
Loading

0 comments on commit b68af8c

Please sign in to comment.