Getting Started

CBWIRE brings reactive UI capabilities to your BoxLang and CFML applications, making it easy to build dynamic interfaces without complex JavaScript frameworks. This guide will help you set up CBWIRE and create your first reactive component.

System Requirements

Before installing CBWIRE, ensure your system meets these requirements:

BoxLang Requirements

BoxLang 1.0+
CBWIRE 4.1+ (BoxLang support was introduced in version 4.1)
OpenJDK 21 (required for BoxLang)
ColdBox 6+
Required modules:
- bx-compat-cfml - CFML compatibility layer
- bx-esapi - Security encoding functions

CFML Requirements

Adobe ColdFusion 2021+ or Lucee 5+
ColdBox 6+

Installation

CBWIRE is distributed through ForgeBox and can be installed using CommandBox.

Install CommandBox

If you don't have CommandBox installed, download it from ortussolutions.com/products/commandbox.

Install CBWIRE

Navigate to your ColdBox application root and run:

box install cbwire@4

For the latest development version:

box install cbwire@be

BoxLang Setup

BoxLang applications require additional configuration to work with CBWIRE. The easiest way to set this up is by creating a server.json file in your project root:

{
    "app": {
        "cfengine": "boxlang",
        "serverHomeDirectory": ".engine/boxlang"
    },
    "web": {
        "rewrites": {
            "enable": "true"
        }
    },
    "JVM": {
        "javaVersion": "openjdk21_jdk"
    },
    "scripts": {
        "onServerInitialInstall": "install bx-compat-cfml,bx-esapi"
    }
}

This configuration automatically:

Sets BoxLang as the CFML engine
Enables URL rewrites (recommended for ColdBox applications)
Uses OpenJDK 21 (required for BoxLang)
Installs required compatibility modules on first server start

Start your server with:

box start

The compatibility modules are only required for BoxLang applications. CFML applications using Adobe ColdFusion or Lucee don't need these additional modules.

Asset Integration

CBWIRE requires CSS and JavaScript assets to function properly. By default, CBWIRE 4 automatically injects these assets into your application's layout, so no manual configuration is needed.

Automatic Asset Injection (Default)

When automatic asset injection is enabled (default), CBWIRE will automatically include the necessary CSS in your page's <head> and JavaScript before the closing </body> tag. Your layout will automatically include content similar to this:

<!doctype html>
<html>
<head>
    <!-- CBWIRE CSS (automatically injected) -->
    <style>[wire\:loading] { display: none; } /* ... more styles ... */</style>
</head>
<body>
    <!-- Your content -->
    
    <!-- CBWIRE JavaScript (automatically injected) -->
    <script src="/modules/cbwire/includes/js/livewire.js" data-csrf="..." data-update-uri="/cbwire/update"></script>
</body>
</html>

Manual Asset Management

If you prefer to control when and how assets are loaded, you can disable automatic injection:

// config/ColdBox.bx (BoxLang) or config/ColdBox.cfc (CFML)
moduleSettings = {
    "cbwire": {
        "autoInjectAssets": false
    }
};

Then manually include the assets in your layout:

<!-- layouts/Main.bxm -->
<bx:output>
<!DOCTYPE html>
<html>
    <head>
        <!-- CBWIRE CSS -->
        #wireStyles()#
    </head>
    <body>
        <!-- Your application content -->
        
        <!-- CBWIRE JavaScript -->
        #wireScripts()#
    </body>
</html>
</bx:output>

<!-- layouts/Main.cfm -->
<cfoutput>
<!DOCTYPE html>
<html>
    <head>
        <!-- CBWIRE CSS -->
        #wireStyles()#
    </head>
    <body>
        <!-- Your application content -->
        
        <!-- CBWIRE JavaScript -->
        #wireScripts()#
    </body>
</html>
</cfoutput>

Next Steps

Congratulations! You've successfully set up CBWIRE. Here are some recommended next steps:

Learn the Essentials: Explore Components, Templates, and Data Binding
Explore Actions: Understand how Actions work and handle user interactions
Master Template Directives: Learn about wire:click, wire:model, and other directives
Advanced Features: Discover Events, File Uploads, and Alpine.js Integration

Troubleshooting

If you encounter issues:

Verify assets are loaded: Check your browser's developer tools to ensure CBWIRE CSS and JavaScript are present
Check server logs: Look for any CBWIRE-related errors in your application logs
Validate requirements: Ensure all system requirements are met, especially for BoxLang applications
Review configuration: Double-check your ColdBox configuration if using custom settings

CBWIRE requires its CSS and JavaScript assets to function. If components aren't responding to interactions, verify that assets are properly loaded in your browser's developer tools.

Previous versions of CBWIRE required manual asset inclusion. CBWIRE 4 automatically handles this by default, making setup much simpler.

PreviousHow It Works NextConfiguration

Last updated 6 days ago

Was this helpful?