@use
@use directives allow you to specify a layout file that will be used to render the current template. This feature is useful for creating reusable layouts that can be applied to multiple templates.
Example:
@use("layouts/main")The @use directive accepts a string literal as its argument. This string literal should specify the path to the layout file relative to the TemplateDir parameter defined in the configuration. For example, if TemplateDir is set to "src/templates" and you have layouts directory in there, you can use the layout directive like @use("layouts/main"), and it will look for the layout file at "src/templates/layouts/main.tw".
Understanding the @use Directive
When you use the @use directive, only the content inside @insert directives will be rendered; the rest of the file's content will be ignored. This is because the @use takes the layout file as a base instead of rendering the current file directly. During this process, all placeholders reserved in the layout file are populated with the content specified within your inserts.
Important Notes
- Name is a constant. The first argument (name) is the constant, it cannot be dynamic, only literal strings are allowed.
- Use path alias. If your layouts are located in the
layoutsdirectory, you can use the~alias to reference them. Read about Path Aliases. - Only one
@useallowed. Only one@usedirective is allowed per template file. Defining multiple layouts will cause an error. - Recommended at the beginning. You can place
@useanywhere in the template, but it’s recommended to put it on the first line for clarity. - Not allowed in layouts. Defining
@useinside a layout file will always result in an error. This is intentional to keep layouts simple.
- Don't use the same file as a component and a layout. A component is rendered with slots and passes, while a layout is rendered with inserts and reserves. The same file can't correctly serve both roles, so keep component files and layout files separate.
