> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# html Operation
> Render HTML templates with data (used in ensembles with http trigger)
The `html` operation renders HTML templates using template engines. It's typically used in ensemble flows when an HTTP trigger needs to return server-rendered HTML.
**Note**: The `html` operation is for rendering only. HTTP routing, authentication, CORS, and middleware are configured in the `trigger:` section using `type: http`.
## HTTP Middleware
When using the `html` operation with HTTP triggers, you can add Hono middleware for cross-cutting concerns like logging, compression, and security headers:
```yaml theme={null}
name: blog-post
trigger:
- type: http
path: /blog/:slug
methods: [GET]
public: true
# Add middleware for performance and security
middleware:
- logger # Log requests
- compress # Gzip compression
- secure-headers # Security headers
- etag # Cache validation
responses:
html: {enabled: true}
agents:
- name: render-page
operation: html
config:
template: |
{{ title }}
{{ content }}
```
Middleware executes before the HTML rendering, allowing you to add:
* Request/response logging (`logger`)
* Response compression for faster page loads (`compress`)
* Security headers (`secure-headers`)
* Cache validation with ETags (`etag`)
* Custom authentication and rate limiting
See the [HTTP Middleware Guide](/conductor/building/http-middleware) for complete documentation on using middleware with HTML responses.
## Usage in Ensembles with HTTP Trigger
```yaml theme={null}
name: blog-post
trigger:
- type: http
path: /blog/:slug
methods: [GET]
public: true
responses:
html: {enabled: true}
templateEngine: liquid
flow:
# Fetch data
- agent: fetch-post
input: {slug: ${input.params.slug}}
# Render HTML
- operation: html
config:
template: |
{{ fetch-post.title }}
{{ fetch-post.content }}
data: ${fetch-post}
```
## Configuration
```yaml theme={null}
operation: html
config:
template: string # HTML template with variables
data: object # Data to render in template
engine: string # Template engine (liquid, handlebars, simple)
```
## Template Engines
### Liquid (Default)
```yaml theme={null}
operation: html
config:
template: |
{{ title }}
{% for item in items %}
{{ item.name }}
{% endfor %}
data: ${previous-step.output}
```
### Handlebars
```yaml theme={null}
operation: html
config:
template: |
{{title}}
{{#each items}}
{{name}}
{{/each}}
data: ${previous-step.output}
engine: handlebars
```
### Simple (String Interpolation)
```yaml theme={null}
operation: html
config:
template: |
{{title}}
{{description}}
data: ${previous-step.output}
engine: simple
```
## Complete Example
```yaml theme={null}
name: user-dashboard
trigger:
- type: http
path: /dashboard/:userId
methods: [GET]
auth:
type: bearer
secret: ${env.API_KEY}
responses:
html: {enabled: true}
templateEngine: liquid
flow:
# Step 1: Fetch user data
- agent: get-user
input: {userId: ${input.params.userId}}
# Step 2: Fetch user stats
- agent: get-user-stats
input: {userId: ${input.params.userId}}
# Step 3: Render HTML dashboard
- operation: html
config:
template: |
Dashboard - {{ get-user.name }}
Welcome, {{ get-user.name }}
Total Orders: {{ get-user-stats.orders }}
Revenue: ${{ get-user-stats.revenue }}
data:
get-user: ${get-user}
get-user-stats: ${get-user-stats}
```
## Personalization with Cookies
Use [cookies](/conductor/operations/cookies) to personalize HTML content based on user preferences or session data:
```yaml theme={null}
name: personalized-page
trigger:
- type: http
path: /home
methods: [GET]
public: true
responses:
html: {enabled: true}
agents:
# Check for preference cookie
- name: get-theme
operation: cookies
config:
action: get
name: theme_preference
# Load user session if logged in
- name: get-session
condition: ${input.cookies.session_id}
operation: storage
config:
type: kv
action: get
key: session-${input.cookies.session_id}
# Render personalized page
- name: render
operation: html
config:
template: |
{% if user %}Welcome back, {{ user.name }}{% else %}Welcome{% endif %}
{% if user %}
Last visit: {{ user.lastVisit }}
{% else %}
Create an account for a personalized experience
{% endif %}
data:
theme: ${get-theme.output.value || 'light'}
user: ${get-session.output.value}
```
Set preference cookies when users change settings:
```yaml theme={null}
agents:
- name: save-theme
operation: cookies
config:
action: set
name: theme_preference
value: ${input.body.theme}
maxAge: 31536000 # 1 year
purpose: personalization
```
## Next Steps
Generate PDFs
HTTP trigger for web routing