# 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" %} ![](https://1598982152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4ENvvb4b3Cmrr1qKj7y4%2Fuploads%2Fh12mzQMVEy2qMhHJk7OW%2Fimage.png?alt=media\&token=4da968aa-24cd-4a14-86a9-32aa4c71ea20) Please note that we have a [dedicated runtime for Spring Boot 3.x](https://boxlang.ortusbooks.com/getting-started/running-boxlang/spring-boot) 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](https://boxlang.ortusbooks.com/boxlang-framework/components). {% 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](https://boxlang.ortusbooks.com/boxlang-language/reference/components) * [Output Component](https://boxlang.ortusbooks.com/boxlang-language/reference/components/system/output) * [Loop Component](https://boxlang.ortusbooks.com/boxlang-language/reference/components/system/loop) * [Query Component](https://boxlang.ortusbooks.com/boxlang-language/reference/components/jdbc/query) * [Include Component](https://boxlang.ortusbooks.com/boxlang-language/reference/components/system/include) ## 🎓 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](https://boxlang.ortusbooks.com/boxlang-language/program-structure) * [Syntax & Semantics](https://boxlang.ortusbooks.com/boxlang-language/syntax) * [Components](https://boxlang.ortusbooks.com/boxlang-language/reference/components) * [Built-in Functions](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions) * [Variables and Scopes](https://boxlang.ortusbooks.com/boxlang-language/syntax/variable-scopes)