# Elements Language

The Elements Language is a lightweight yet powerful templating system built into RapidWeaver Elements. It uses `{{…}}` syntax for property insertion and provides expressive directives like `@if`, `@each`, and `@include` for dynamic content generation. The language is designed to keep your templates clean, intuitive, and focused on HTML structure.

## Property Insertion

Use double curly braces to insert component properties, page data, or collection values directly into your markup:

```html
<h2>{{title}}</h2>
<p>{{description}}</p>
<a href="{{link.href}}">{{link.title}}</a>
```

Access nested properties using dot notation:

```html
<span>{{author.name}}</span>
<img src="{{image.resource.src}}" alt="{{image.alt}}" />
```

## Directives Reference

### Content Areas

| Directive   | Description                          | Documentation                                                                                             |
| ----------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `@dropzone` | Container for child elements         | [Dropzones](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/dropzone) |
| `@text`     | Editable plain text area             | [Text](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/text)          |
| `@richtext` | Editable styled text with Typography | [Rich Text](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/richtext) |
| `@markdown` | Editable Markdown text area          | [Markdown](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/markdown)  |

### Control Flow

| Directive                   | Description              | Documentation                                                                                          |
| --------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `@if` / `@elseif` / `@else` | Conditional rendering    | [Conditionals](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/if) |
| `@each`                     | Iterate over collections | [Looping](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/each)    |

### Code Organization

| Directive    | Description                     | Documentation                                                                                                       |
| ------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `@include`   | Include external template file  | [Includes](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/include)             |
| `@includeIf` | Conditional template include    | [Includes](https://docs.realmacsoftware.com/elements-docs/elements-language/component/include#conditional-includes) |
| `@template`  | Define inline reusable template | [Inline Templates](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/template)    |

### Page Integration

| Directive | Description                         | Documentation                                                                                         |
| --------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `@portal` | Transport content to page locations | [Portals](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/portal) |
| `@anchor` | Create linkable anchor points       | [Anchors](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/anchor) |
| `@raw`    | Disable template processing         | [Raw Output](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/raw) |

## Quick Examples

### Editable Text Areas

```html
@text("heading", default: "Welcome")
```

```html
@richtext("content", title: "Body Content")
```

```html
@markdown("article", title: "Article", default: "Write your content here...")
```

### Dropzones for Child Elements

```html
@dropzone("content", title: "Container")
```

```html
@dropzone(name: "items", title: "Grid Items", horizontal: true)
```

### Conditional Rendering

```html
@if(showHeader)
    <header>{{headerText}}</header>
@endif
```

```html
@if(edit)
    <!-- Edit mode content -->
@elseif(preview)
    <!-- Preview mode content -->
@else
    <!-- Published content -->
@endif
```

### Looping Over Collections

```html
@each(item in items)
    <li>{{item.title}}</li>
@endeach
```

```html
@each(page in pages)
    @if(page::isFirst)
        <li class="first">{{page.title}}</li>
    @else
        <li>{{page.title}}</li>
    @endif
@endeach
```

### Including Templates

```html
@include("button", label: "Click Me", style: "primary")
```

```html
@includeIf(wantsLightbox, template: "lightbox")
```

### Portals for Script Injection

```html
@portal(bodyEnd, id: "my-script", includeOnce: true)
    <script src="library.js"></script>
@endportal
```

### Inline Templates

```html
@template("card")
    <div class="card">
        <h3>{{title}}</h3>
        <p>{{description}}</p>
    </div>
@endtemplate

@each(item in cards)
    @include("card", title: item.title, description: item.desc)
@endeach
```

### Anchor Points

```html
<section id="@anchor("features")">
    <h2>Features</h2>
</section>
```

### Raw Output for CMS Integration

```html
@raw()
    <div>{{cms.field}}</div>
@endraw
```

## Best Practices

1. **Keep templates focused on HTML** - Use the [hooks file](https://docs.realmacsoftware.com/elements-docs/elements-language/component/hooks.js) for complex logic, string manipulation, and data processing.
2. **Use meaningful property names** - Choose descriptive names that indicate purpose: `showHeader`, `buttonLabel`, `heroImage`.
3. **Extract repeated patterns** - Use `@include` or `@template` for reusable markup.
4. **Leverage conditionals for modes** - Use `edit` and `preview` variables to show appropriate content in each mode.
5. **Organize portal content** - Use `includeOnce` and consistent `id` values to prevent duplicate script/style injection.