# Templating Language BoxLang includes a powerful templating language designed for creating dynamic HTML, views, and content rendering. Template files use the `.bxm` extension and provide a natural way to mix static content with dynamic BoxLang code. {% hint style="success" %} Please note that we have a [dedicated runtime for Spring Boot 3.x](/getting-started/running-boxlang/spring-boot.md) that allows you to build your entire view layer in Boxlang. {% endhint %} ## 📄 Template File Structure Template files (`.bxm`) are designed for content generation and HTML output. Unlike script files (`.bxs`) or class files (`.bx`), templates default to outputting content directly, making them ideal for views, email templates, and dynamic HTML generation. ```xml Welcome to BoxLang

Hello, #name#!

Today is #dateFormat( now(), "full" )#

 ``` ## 🔤 Output Interpolation BoxLang templates use the `#` (hash/pound) character for output interpolation. Any expression wrapped in `#` symbols will be evaluated and output to the page. {% hint style="info" %} **Important**: For interpolation to work in templates, expressions must be surrounded by a `` component or within an outputting component context (like ``). Component attribute values are automatically evaluated and support interpolation without requiring ``. {% endhint %} ### Basic Interpolation ```xml

#greeting#

Current time: #now()#

Random number: #randRange( 1, 100 )#

 ``` ### Escaping Hash Symbols To output a literal `#` character without evaluation, use double hashes `##`: ```xml

Use ## for hash symbols in CSS: ##header { color: blue; }

This outputs: # for hash symbols in CSS: #header { color: blue; }

 ``` ### Complex Expressions You can use any BoxLang expression within interpolation: ```xml

We have #products.len()# products

First product: #products[1]#

Total price: #calculateTotal( products )#

 ``` ## 🏷️ Template Components BoxLang provides a rich set of template components using the `bx:` prefix. All template components follow XML-like syntax with opening and closing tags or self-closing syntax. ### Common Template Components #### bx:output The `bx:output` component enables output of dynamic content and expressions. Within `bx:output`, the `#` interpolation is automatically enabled. **Basic Usage:** ```xml

Welcome, #user.name#!

Your account was created on #dateFormat( user.created, "long" )#

 ``` **Attributes:** * `query` - Loop over a query object and output each row * `group` - Group query output by a column name * `groupCaseSensitive` - Whether group matching is case-sensitive (default: false) * `startRow` - Start outputting from this row number * `maxRows` - Maximum number of rows to output * `encodefor` - Automatically encode output ("html", "javascript", "url", "xml") **Query Loop Example:** ```xml

#products.name#

Price: #dollarFormat( products.price )#

 ``` **Automatic Encoding Example:** ```xml

#users.name# - #users.email#

 ``` **Grouped Output Example:** ```xml

#products.category#

#products.name# - #dollarFormat( products.price )#

 ``` #### bx:set Define variables in templates using `bx:set`: ```xml ``` #### bx:script Execute BoxLang script code within a template: ```xml users = queryExecute( "SELECT * FROM users" ) totalUsers = users.recordCount activeUsers = users.filter( ( row ) => row.active == true ).len()

Total Users: #totalUsers#

Active Users: #activeUsers#

 ``` #### bx:if, bx:elseif, bx:else Conditional rendering in templates: ```xml
Admin Dashboard
Editor Dashboard
User Dashboard
 ``` #### bx:loop Iterate over arrays, queries, structures, and ranges: ```xml
  • #fruit#
    •
#users.id# #users.name#

Item #i#

 ``` #### bx:include Include other template files: ```xml

Page Content

``` ### Additional Template Components BoxLang provides many more template components for various purposes: #### bx:param Validate and set default values for variables: ```xml ``` #### bx:try / bx:catch / bx:finally Exception handling in templates: ```xml Result: #result#

Error occurred: #cfcatch.message#

Cleanup completed

 ``` #### bx:throw Throw custom exceptions: ```xml ``` #### bx:abort Stop template execution: ```xml

Access denied

 ``` #### bx:dump Debug output for variables: ```xml ``` #### bx:exit Exit from a specific execution context: ```xml ``` #### bx:savecontent Capture output into a variable: ```xml

Welcome!

Thank you for registering, #user.name#

 ``` #### bx:silent Suppress output: ```xml Some text that won't be rendered ``` ## 🔄 Mixing Scripts and Templates BoxLang allows seamless mixing of script and template syntax within the same file. ### Scripts in Templates Use `` to embed BoxLang script code within a template: ```xml

User Report

// Fetch data using script syntax users = queryExecute( "SELECT * FROM users WHERE active = ?", [ true ] ) // Process data stats = { total: users.recordCount, admins: 0, users: 0 } users.each( ( row ) => { if( row.role == "admin" ) { stats.admins++ } else { stats.users++ } } )

Total: #stats.total#

Admins: #stats.admins#

Users: #stats.users#

 ``` ### Templates in Scripts In script files (`.bxs`), you can embed template code using template island notation with triple backticks (` ``` `): ````javascript // This is a .bxs script file users = [ { name: "John", age: 30 }, { name: "Jane", age: 25 } ] // Now switch to template syntax ```

Users List

  • #user.name# - #user.age# years old
    •
``` // Back to script syntax println( "Template rendered successfully" ) ```` ## 🎯 Component Execution BoxLang templates can execute any BoxLang component using the `bx:` prefix followed by the component name. The runtime automatically resolves and executes the component. ### Built-in Components BoxLang includes many built-in components for common tasks: ```xml SELECT id, name, email FROM users WHERE active = 1 // Long running task here ``` ### Custom Components You can create your own custom components to extend the templating language with reusable functionality. Custom components are BoxLang templates or scripts that can be invoked like built-in components. #### Creating a Custom Component Create a component file (e.g., `greeting.bxm`): ```xml

Hello, #attributes.name#!

Welcome to our application.

 ``` #### Using Custom Components Call your custom component using the `bx:_` prefix: ```xml ``` Or using the `bx:component` tag: ```xml ``` #### Component Discovery BoxLang searches for custom components in several locations: 1. Relative to the current template 2. Application-defined component paths (via `Application.bx`) 3. Global component directories #### Configuring Component Paths In your `Application.bx`, you can specify custom component directories: ```js class { this.name = "MyApp" // Define custom component paths this.customComponentPaths = [ expandPath( "/components" ), expandPath( "/shared/components" ) ] // For class-based components this.classPaths = [ expandPath( "/classes" ) ] } ``` {% hint style="info" %} For comprehensive documentation on creating and using custom components, including advanced patterns, component scopes, and best practices, see the [Components Framework Documentation](/boxlang-framework/components.md). {% endhint %} ## 💡 Practical Examples ### Dynamic HTML Page ```xml #pageTitle#

Welcome, #userName#!

Today is #dateFormat( currentDate, "full" )#

© #year( currentDate )# My Company. All rights reserved.

 ``` ### Data Table with Query ```xml // Fetch products from database products = queryExecute( "SELECT id, name, price, category FROM products WHERE active = :active ORDER BY name", { active: true } )

Product Catalog

ID Name Category Price
#products.id# #products.name# #products.category# #dollarFormat( products.price )#

Showing #products.recordCount# products

No products found.

 ``` ### Email Template ```xml

Welcome to Our Platform, #userName#!

Thank you for registering with email: #userEmail#

Please activate your account by clicking the button below:

Activate Account

Or copy this link: #activationLink#

Best regards,
The Team

``` ### Form Processing ```xml

Contact Form

// Process form submission result = { success: false, message: "" } // Validate inputs if( len( trim( form.name ) ) == 0 || len( trim( form.email ) ) == 0 ) { result.message = "Name and email are required" } else if( !isValid( "email", form.email ) ) { result.message = "Please enter a valid email address" } else { // Save to database or send email queryExecute( "INSERT INTO contacts (name, email, message) VALUES (?, ?, ?)", [ form.name, form.email, form.message ] ) result.success = true result.message = "Thank you for contacting us!" }
#result.message#
#result.message#
``` ## 🔒 Security Considerations When outputting user-generated content or data from external sources, always encode the output to prevent XSS attacks: ```xml

#user.name#

#encodeForHTML( user.name )#

Profile

#users.name#

#users.bio#

 ``` ## 📚 Component Reference For a complete list of available template components, see: * [Components Reference](/boxlang-language/reference/components.md) * [Output Component](/boxlang-language/reference/components/system/output.md) * [Loop Component](/boxlang-language/reference/components/system/loop.md) * [Query Component](/boxlang-language/reference/components/jdbc/query.md) * [Include Component](/boxlang-language/reference/components/system/include.md) ## 🎓 Best Practices 1. **Use templates for views**: Template files (`.bxm`) are ideal for HTML generation and views 2. **Keep logic in scripts**: Use `` or separate script files for complex business logic 3. **Encode output**: Always encode user-generated content using `encodeForHTML()` and related functions 4. **Organize includes**: Store reusable template fragments in a common directory structure 5. **Comment your templates**: Use `` for documentation 6. **Use meaningful variable names**: Make your templates readable and maintainable ## 🔗 Related Documentation * [Program Structure](/boxlang-language/program-structure.md) * [Syntax & Semantics](/boxlang-language/syntax.md) * [Components](/boxlang-language/reference/components.md) * [Built-in Functions](/boxlang-language/reference/built-in-functions.md) * [Variables and Scopes](/boxlang-language/syntax/variable-scopes.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://boxlang.ortusbooks.com/boxlang-language/templating-language.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.