# Templates

Template files in RapidWeaver Elements house all the HTML, CSS, JavaScript, and other assets your component needs to work seamlessly. All template files are dynamically processed by Elements, allowing for property replacements, conditional rendering, iterations, and more using the [Elements Language](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language). This enables you to build highly flexible and reusable components.

## Overview

The templates directory is the heart of your component's output. Files placed here are processed using the Elements templating language, which supports:

* **Property insertion** using `{{propertyName}}` syntax
* **Conditional rendering** with `@if`, `@elseif`, `@else`
* **Loops** using `@each` for collections
* **Content areas** with `@dropzone`, `@text`, `@richtext`, and `@markdown`
* **Template includes** with `@include` for reusable partials
* **Portal injection** using `@portal` to place content in specific page locations

{% hint style="info" %}
Any files that don't require Elements template language processing should be stored in the [assets](https://docs.realmacsoftware.com/elements-docs/elements-language/component/assets) directory instead.
{% endhint %}

## Templates Directory Structure

```
com.yourcompany.component/
├── templates/
│   ├── index.html              # Main component template
│   ├── alpine.html             # Additional template file
│   ├── styles.css              # CSS with template directives
│   ├── include/                # Reusable template partials
│   │   ├── header.html
│   │   ├── footer.html
│   │   └── icon.html
│   └── backend/                # Server-side files
│       └── submit.php
```

### Root-Level Templates

Files placed directly in the `templates/` directory are processed and included for **each instance** of the component on the page. This is where you'll place your component's primary HTML, CSS, and JavaScript.

**Common root-level files:**

* `index.html` - The main component markup (see [index.html documentation](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/index.html))
* Additional HTML files for specific features
* CSS files with template directives (see [CSS Templates](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/css-templates))
* JavaScript files (see [JavaScript Templates](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/js-templates))
* PHP files (see [PHP Templates](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/php-templates))

### Subdirectories

The templates directory supports special subdirectories for organizing your code:

| Directory  | Purpose                                              | Documentation                                                                                                     |
| ---------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `include/` | Reusable template partials accessed via `@include()` | [Include Directory](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/include) |
| `backend/` | Server-side files deployed to the backend directory  | [Backend](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/backend)           |

## Supported File Types

The templates directory supports multiple file types, all processed through the Elements template engine:

| Extension | Description | Use Case                                          |
| --------- | ----------- | ------------------------------------------------- |
| `.html`   | HTML markup | Component structure, content areas                |
| `.css`    | Stylesheets | Component-specific styles with property insertion |
| `.js`     | JavaScript  | Interactive behavior with property values         |
| `.php`    | PHP code    | Server-side processing (typically in backend/)    |

All these file types can use the full [Elements Language](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language) syntax, including property insertion, conditionals, and directives.

## Processing Behavior

### Per-Instance Processing

Root-level template files are processed **once per component instance**. If you have three button components on a page, each button's templates are processed independently with its own properties.

### Template Order

Template files are processed in alphabetical order by filename. If order matters for your templates, you can:

* Use the `@portal` directive to inject content into specific page locations
* Combine multiple templates into a single file
* Use naming conventions (e.g., `01-setup.html`, `02-main.html`)

### Property Scope

Templates have access to:

* Component properties defined in `properties.json`
* Data passed from `hooks.js` using `rw.setProps()`
* Built-in properties like `id`, `edit`, `preview`
* Collection data when using `@each`

## Common Patterns

### Portal-Based Templates

Use the `@portal` directive to inject scripts or styles into specific page locations, even though the template is processed per-instance:

```html
@portal(bodyEnd, includeOnce: true, id: "my-component-script")
<script>
    // This script is included only once per page
    Alpine.data("myComponent", () => ({
        // Component logic
    }));
</script>
@endportal
```

See the [`@portal` documentation](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/portal) for more details.

### Conditional Templates

Wrap template content in conditionals for different modes or property values:

```html
@if(edit)
    <div class="edit-mode-placeholder">
        Click to configure this component
    </div>
@else
    <div class="{{classes.container}}">
        @dropzone("content", title: "Content")
    </div>
@endif
```

See the [`@if` documentation](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/if) for more details.

### Template Includes

Break complex components into smaller, reusable pieces:

```html
<!-- templates/index.html -->
<nav class="{{classes.navbar}}">
    @include("logo")
    @include("menu")
</nav>

<!-- templates/include/logo.html -->
<div class="logo">
    {{siteName}}
</div>

<!-- templates/include/menu.html -->
<ul class="menu">
    @each(item in menuItems)
        <li>{{item.title}}</li>
    @endeach
</ul>
```

See the [Include Directory documentation](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/include) and [`@include` directive](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language/include) for more details.

## Templates vs Assets

Choose the right location for your files:

**Use `templates/` when:**

* Files need property replacement (e.g., `{{propertyName}}`)
* You need conditional rendering or loops
* Files should be processed per-component instance
* You're using Elements Language directives

**Use `assets/` when:**

* Files are static and don't need processing
* Files are large libraries (Alpine.js, GSAP, etc.)
* Files should be included once per page regardless of instances
* You want optimal caching and performance

## Examples from Core Components

### Simple Component (Typography)

```html
@richtext("content", title: "Typography", default: "Start editing this text...")
```

### Component with Conditionals (Button)

```html
@if(showText)
@text("text", title: "Button Text", default: "Click Me")
@endif
@if(wantsDropzone)
<div class="{{dropzoneSide}}">
  @dropzone("dropzone", title: "Icon")
</div>
@endif
```

### Component with Includes (Gallery)

```html
@if(!hasResources)
    <!-- Placeholder UI -->
@else
<div class="{{classes.wrapper}}" x-data>
    @each(image in resources)
        @include("thumbnail")
    @endeach
</div>
@endif
@includeIf(includeLightbox, template: "lightbox")
```

## Next Steps

Explore the detailed documentation for each template type:

* [index.html](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/index.html) - Learn about the main template file
* [Include Directory](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/include) - Organize reusable template partials
* [CSS Templates](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/css-templates) - Add styles with template directives
* [JavaScript Templates](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/js-templates) - Create interactive behavior
* [PHP Templates](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/php-templates) - Add server-side processing
* [Backend](https://docs.realmacsoftware.com/elements-docs/elements-language/component/templates/backend) - Deploy files to the server

For template language syntax, see the [Elements Language](https://docs.realmacsoftware.com/elements-docs/elements-language/component/language) documentation.