diff --git a/docs/1-essentials/02-views.md b/docs/1-essentials/02-views.md
index 036c505fa..2e0fdd2ef 100644
--- a/docs/1-essentials/02-views.md
+++ b/docs/1-essentials/02-views.md
@@ -215,9 +215,9 @@ Since `:isset` is a shorthand for `:if="isset()"`, it can be combined with `:els
Title
```
-#### `:foreach` and `:{:hl-keyword:forelse:}`
+#### `{:hl-property::foreach:}` and `:{:hl-property:forelse:}`
-The `:foreach` directive may be used to render the associated element multiple times based on the result of its expression. Combined with `:{:hl-keyword:forelse:}`, an empty state can be displayed when the data is empty.
+The `{:hl-property::foreach:}` directive may be used to render the associated element multiple times based on the result of its expression. Combined with `:{:hl-property:forelse:}`, an empty state can be displayed when the data is empty.
```html
@@ -249,26 +249,35 @@ The example above will only render the child `div` elements:
### Tag override with the `as` prop
The `as` attribute allows you to transform the rendered tag of one element into another. This takes place on an instance of `GenericElement`, so for example this code:
+
```html
My Link
```
+
Would render
+
```html
```
+
The power behind this is when you use an `Expression` to determine the element.
Say for example, you wish to have a `` component which renders as an `` when the `$href` attribute is provided. In your view, use the component like so:
+
```html
Click to go to an awesome websiteThis is just a button
```
+
In your `` component, define:
+
```html
```
-Your page will render two links, as follows
+
+Your page will render two links, as follows:
+
```html
Click to go to an awesome website
@@ -348,16 +357,21 @@ In previous releases (3.8.0 and prior), Tempest would attempt to *merge* these v
:::
Assume you have a `button`, like so, with a default set of classes present:
+
```html x-button.view.php
```
+
Now, in your page, you may utilise the element:
+
```html index.view.php
```
+
As these attributes automatically apply, your button will be converted to this:
+
```html
```
@@ -365,27 +379,35 @@ As these attributes automatically apply, your button will be converted to this:
#### Disabling automatic fallthrough
Tempest will attempt to apply `{html}class`, `{html}style`, and `{html}id` automatically, when they are passed to a view component. For example:
+
```html index.view.php
```
+
With the above, Tempest will attempt to apply `{html}style`, and `{html}id` automatically. As `{html}class` isn't configured, it isn't applied.
In the view component itself, you can configure `{html}class`, `{html}style`, and `{html}id` to anything you want, and Tempest will not overwrite them. You can of course, also then use these classes however you want to use them:
+
```html x-button.view.php
```
+
When you use this version of ``:
+
- `{html}id` will now default to `mybtn_(sequence generated by uniqid)`,
- `{html}style` will not appear automatically, as it was not supplied,
- `{html}class` will have a default, you can of course instead concatenate these strings, or use a CVA utility for smart class merging, or anything you want.
For example, pass one or more classes:
+
```html
```
+
And you'll get
+
```html
```
@@ -403,19 +425,25 @@ You cannot mix `ApplyAttribute` with automatic fallthrough attributes. Opting to
#### Excluding specific fallthrough attributes
To exclude specific attributes from falling through, configure your `button` view component like this:
+
```html x-button.view.php
```
+
:::info
The `removeKeys` method returns all key=>value pairs, except for those specified. You can also use the `filter` method if you need to use a closure to filter.
:::
+
Now, when utilising it in your page:
+
```html index.view.php
```
+
Will result in:
+
```html
```
@@ -423,19 +451,25 @@ Will result in:
#### Including only specific fallthrough attributes
To include only specific attributes, configure your `button` view component like this:
+
```html x-button.view.php
```
+
:::info
The `removeKeysExcept` method returns only the specified key=>value pairs. You can also use the `filter` method if you need to use a closure to filter.
:::
+
Now, when utilising it in your page:
+
```html index.view.php
```
+
Tempest will apply only the specified attributes:
+
```html
```
@@ -445,7 +479,8 @@ Tempest will apply only the specified attributes:
As the `ApplyAttribute` simply stringifies string and boolean values from the provided array, you can build the array however you like.
Consider this example `button`:
-```php x-button.view.php
+
+```html x-button.view.php
$class ?? null,
@@ -453,13 +488,18 @@ $apply = [
'target' => (isset($href) && str_contains($href, 'http')) ? '_blank' : null,
];
?>
+
```
+
Now, when utilising it in your page:
+
```html index.view.php
```
+
Tempest will spread the supplied attributes, and as we also used the `AsAttribute` to convert it to a `{html}a` when `$href` is populated, you will get a hyperlink:
+
```html
Tempest, the framework that gets out of your way
```
@@ -586,10 +626,12 @@ To override this behaviour and manually control in which view component your slo
#### Extendable view component example using `define`
Let us assume you have an `x-container` view component, which is a `
` with formatting to act as a flex container for responsive sizing. You use this component repeatedly across your project, and it's effectively a macro to open and close the `
`; it doesn't have any slots or do anything special itself otherwise, with only a default `` to render whatever it is given.
+
```html x-container.view.php
```
Now, assume we have an `x-header` in which we wish to use the `x-container`. Our `x-header` wishes to place slots `left` and `right` inside it; `x-header` owns these slots and wishes to expose these slots at the callsite in case they need custom content. Using the `define` keyword tells Tempest to treat these slots as *defined* by `x-header` instead of as a *slot to fill* inside `x-container`. Using `name` here instead of `define` would mean that Tempest falls back to the AST, and treats them as if they are slots of ``.
+
```html x-header.view.php
@@ -607,17 +649,21 @@ Now, assume we have an `x-header` in which we wish to use the `x-container`. Our
```
+
At the callsite, you still use the `name` attribute to define which slot you're placing content into:
+
```html callsite.view.php
Some content I want to insert
```
+
This example would replace the default content `` instead with the literal string `Some content I want to insert` - or whatever you provide.
#### Populating a child's name slot using `define`
You can also push content into a child's named slot, not just the default slot, by creating a `define`d slot as follows:
+
```html x-outer.view.php
@@ -627,12 +673,15 @@ You can also push content into a child's named slot, not just the default slot,
```
+
Again, the `define` keyword registers a `left` slot against the view component `` irrespective of it's position in the AST, and means that at the callsite:
+
```html outercallsite.view.php
My override
```
+
And so, this places the literal string `My override` into ``'s `left` slot.
### Dynamic view components
@@ -757,7 +806,9 @@ This component provides the ability to inject any icon from the [Iconify](https:
```html
```
+
will render
+
```html