Skip to content

Commit d6b703e

Browse files
committed
docs: add more info
1 parent 32af0cc commit d6b703e

2 files changed

Lines changed: 470 additions & 838 deletions

File tree

docs/versions/v3/language-elements/directives.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ Textwire directives provide control over your templates through commands that be
1515
- [@each](#each) `@each(name in names)`
1616
- [@component](#component) `@component("components/post-card")`
1717
- [@slot](#slot) `@slot('footer')`
18+
- [@slotif](#slotif) `@slotif(true, 'ooter')`
1819
- [@dump](#dump) `@dump(users, page)`
1920

2021
## @if
@@ -116,6 +117,7 @@ When you use the `@use` directive, only the content inside [`@insert`](#insert)
116117

117118
### Important Notes
118119

120+
- **Name is a constant.** The first argument (name) is the constant, it cannot be dynamic, only literal strings are allowed.
119121
- **Only one `@use` allowed.** Only one `@use` directive is allowed per template file. Defining multiple layouts will cause an error.
120122
```textwire
121123
@use('~main')
@@ -151,6 +153,7 @@ Below is an example demonstrating two scenarios for the `@insert` directive with
151153

152154
### Important Notes
153155

156+
- **Name is a constant.** The first argument (name) is the constant, it cannot be dynamic, only literal strings are allowed.
154157
- **Takes two arguments.** `@insert` is optional and accepts two arguments: the name of the reserved placeholder and the optional content to be injected into that placeholder.
155158
- **Evaluated in template context.** All inserts are evaluated within the template file first, and next, they are matched to placeholders defined by the [`@reserve`](#reserve) directives in the layout file. It means they have the context of the file where they are defined.
156159
- **Requires matching reserve.** If you define an insert without having a matching reserve, it will result in error. Such inserts are considered unused.
@@ -195,6 +198,7 @@ As a second argument, `@reserve` can also take a fallback value that will be use
195198

196199
### Important Notes
197200

201+
- **Name is a constant.** The first argument (name) is the constant, it cannot be dynamic, only literal strings are allowed.
198202
- **Only in layout files.** `@reserve` can only be used inside layout file. Using it in templates and components will result in error.
199203
- **`@insert` is optional.** `@reserve` does not force you to have a matching `@insert`. If you don't insert any value into `@reseve`, it will fallback to an empty string.
200204
- **One `@reserve` per file.** You cannot define multiple `@reserve` directives with the same name in a single layout file. It will result in an error starting from version [v3.1.0](https://github.com/textwire/textwire/pull/68).
@@ -246,6 +250,7 @@ The second optional argument is an [object](/v3/language-elements/literals#objec
246250

247251
### Imporant Notes
248252

253+
- **Name is a constant.** The first argument (name) is the constant, it cannot be dynamic, only literal strings are allowed.
249254
- You can include layout file into components using [`@use`](/v3/language-elements/directives#use) directive, but it can make your templates more complex and harder to maintain. We recommend to avoid using layouts in components and keep them simple.
250255
- Component cannot have empty body and be like `@component("post", { post })@end`. In this situations it's important to remove `@end` token to avoid parsing errors.
251256
- You can use [slots](/v3/language-elements/directives#slot) in components to pass content to the component file.
@@ -304,6 +309,41 @@ In this example, both default and named slots are used within a single component
304309
- **Empty string is default slot.** If you provide an empty string as a slot name, it will act as default slot. `@slot` and `@slot('')` act the same.
305310
- **Slots have current context.** Slots have the context of the same file where they are defined. It means you can dinamically modify the content of a slot before it get rendered in the component file.
306311
- **Slots are optional.** If you don't provide content for a slot, it will be rendered as an empty string.
312+
- **Name is a constant.** The first argument (name) is the constant, it cannot be dynamic, only literal strings are allowed.
313+
314+
## @slotif
315+
316+
`@sloif` directive combines `@slot` and `@if` directives making it possible to conditionally render a slot. It takes a condition as the first argument and a slot name as the second argument. If the condition is truthy, the content of the slot will be rendered; otherwise, it will be ignored.
317+
318+
There are 2 types of conditional slots in Textwire: default slots and named slots.
319+
320+
1. **Default Slots**: Use the `@slotif(true)` directive to define and pass content to a default slot.
321+
2. **Named Slots**: Use the `@slotif(true, "name")` directive to define and pass content to a named slot.
322+
323+
Here’s an example of how to use conditional slots in a component. Example:
324+
325+
```textwire :line-numbers
326+
@each(book in books)
327+
@component("~book", { book })
328+
{{-- default slotif --}}
329+
@slotif(hasImage)
330+
<img src="{{ book.image }}" alt="{{ book.title }}">
331+
@end
332+
333+
{{-- named slotif --}}
334+
@slotif(hasFooter, 'footer')
335+
<small>published by {{ book.author }}</small>
336+
<button>Read more</button>
337+
@end
338+
@end
339+
@end
340+
```
341+
342+
### Important Notes
343+
344+
- **Same rules.** All the rules from [@slot](/v3/language-elements/directives#slot) apply to `@slotif`.
345+
- **Only inside components** Conditional slots can only be local (used inside component directive).
346+
307347

308348
## @dump
309349

0 commit comments

Comments
 (0)