BoxLang ๐Ÿš€ A New JVM Dynamic Language Learn More...

ColdBox Modern APP Template

v8.1.0+6 MVC


ColdBox Snapshots Total Downloads Latest Stable Version Apache2 License

Copyright Since 2005 ColdBox Platform by Luis Majano and Ortus Solutions, Corp
www.coldbox.org | www.ortussolutions.com


๐Ÿ—๏ธ ColdBox Modern Application Template

Welcome to the Modern ColdBox application template! ๐ŸŽ‰ This template provides a secure, production-ready foundation for building enterprise-grade HMVC (Hierarchical Model-View-Controller) web applications using Adobe ColdFusion or BoxLang.

๐ŸŒŸ What Makes This Template "Modern"?

Unlike traditional ColdBox templates where all files live in the web root, this template implements a security-first architecture by separating your application code from publicly accessible files:

  • ๐Ÿ“ /public - Only public assets (CSS, JS, images, index.cfm) are web-accessible
  • ๐Ÿ”’ /app - Application code (handlers, models, views, config) sits outside the web root
  • ๐Ÿ›ก๏ธ Enhanced Security - Prevents direct web access to application logic and configuration
  • ๐Ÿข Production Ready - Industry best practice for secure deployments

๐Ÿ’ก Perfect for: Production applications, enterprise environments, security-conscious projects, and teams following modern web development practices.

โš™๏ธ Requirements

Before getting started, ensure you have the following installed on your operating system:

  1. CommandBox - CLI toolchain, package manager, and server runtime

  2. CFML Engine - Adobe ColdFusion 2021+ OR BoxLang 1.0+

  3. Maven - Java dependency manager (Optional)

Verification

Verify your installation:

# Check CommandBox is installed
box version

# Check your CFML engine (BoxLang example)
box boxlang version

# Verify project setup
box install

โšก Quick Installation

# Create a new ColdBox application using this Modern template
box coldbox create app name=myApp skeleton=modern

# Navigate into your app directory
cd myApp

# Install dependencies
box install

# Start the web server
box server start

Your application will be available at http://localhost:8080 ๐ŸŒ

Code to your liking and enjoy! ๐ŸŽŠ

๐Ÿ“ Modern Template Structure

This template follows a security-first architecture where application code lives outside the web root:

๐Ÿ—๏ธ ColdBox Application (/app/)

This folder contains the main ColdBox application code via conventions. It is NOT web-accessible for security.

app/
โ”œโ”€โ”€ ๐Ÿ”ง Application.cfc        # Security barrier (contains only "abort")
โ”œโ”€โ”€ config/                   # Configuration files
โ”‚   โ”œโ”€โ”€ ColdBox.cfc          # Main framework settings
โ”‚   โ”œโ”€โ”€ Router.cfc           # URL routing definitions
โ”‚   โ”œโ”€โ”€ WireBox.cfc          # Dependency injection (optional)
โ”‚   โ””โ”€โ”€ CacheBox.cfc         # Caching configuration (optional)
โ”œโ”€โ”€ ๐ŸŽฎ handlers/             # Event handlers (controllers)
โ”œโ”€โ”€ ๐Ÿ› ๏ธ helpers/              # Application helpers (optional)
โ”œโ”€โ”€ ๐Ÿ”Œ interceptors/         # Event interceptors/listeners
โ”œโ”€โ”€ ๐ŸŽจ layouts/              # View layouts
โ”œโ”€โ”€ ๐Ÿ“ logs/                 # Application logs
โ”œโ”€โ”€ ๐Ÿ—๏ธ models/               # Business logic models
โ”œโ”€โ”€ ๐Ÿ“ฆ modules/              # Application-specific modules (optional)
โ””โ”€โ”€ ๐Ÿ‘๏ธ views/                # View templates

๐ŸŒ Public Web Root (/public/)

This folder contains ONLY publicly accessible files - the CommandBox server points here.

public/
โ”œโ”€โ”€ ๐Ÿ“ฑ Application.cfc       # Bootstrap that maps to /app
โ”œโ”€โ”€ ๐ŸŽฏ index.cfm             # Main entry point
โ”œโ”€โ”€ ๐Ÿ–ผ๏ธ favicon.ico           # Site icon
โ”œโ”€โ”€ ๐Ÿค– robots.txt            # Search engine directives
โ””โ”€โ”€ ๐Ÿ“ฆ includes/             # Static assets (CSS, JS, images)

๐Ÿ“š Libraries (/lib/)

Framework and dependency storage managed by CommandBox:

lib/
โ”œโ”€โ”€ coldbox/                 # ColdBox framework files
โ”œโ”€โ”€ testbox/                 # TestBox testing framework
โ”œโ”€โ”€ java/                    # Java JAR dependencies (optional)
โ””โ”€โ”€ modules/                 # CommandBox-installed modules

๐Ÿงช Tests (/tests/)

Test suites for your application:

tests/
โ”œโ”€โ”€ Application.cfc          # Test application setup
โ”œโ”€โ”€ runner.cfm               # TestBox test runner
โ”œโ”€โ”€ index.cfm                # Test entry point
โ””โ”€โ”€ specs/                   # BDD test specifications
    โ””โ”€โ”€ integration/         # Integration tests

๐Ÿ”ง Configuration & Build

โ”œโ”€โ”€ ๐Ÿ“‹ box.json              # CommandBox dependencies and project descriptor
โ”œโ”€โ”€ ๐Ÿ—๏ธ pom.xml               # Maven dependencies (optional)
โ”œโ”€โ”€ ๐Ÿ–ฅ๏ธ server.json           # CommandBox server configuration (CRITICAL for aliases)
โ”œโ”€โ”€ ๐Ÿณ docker/               # Docker configuration
โ”œโ”€โ”€ ๐Ÿ“š resources/            # Non-web resources
โ”‚   โ”œโ”€โ”€ database/            # Database migrations/seeders
โ”‚   โ””โ”€โ”€ apidocs/             # API documentation
โ”œโ”€โ”€ .env.example             # Environment variable template
โ”œโ”€โ”€ .cfconfig.json           # CFML engine configuration
โ”œโ”€โ”€ .cfformat.json           # Code formatting rules
โ””โ”€โ”€ .editorconfig            # Editor configuration

๐Ÿ”— CommandBox Web Aliases (CRITICAL)

Because application code lives outside /public, you must configure CommandBox aliases in server.json to expose internal paths for modules with UI assets:

"web": {
    "webroot": "public",
    "rewrites": {
        "enable": true
    },
    "aliases": {
        "/coldbox/system/exceptions": "./lib/coldbox/system/exceptions/",
        "/tests": "./tests/"
    }
}

๐Ÿ“ฆ Adding Module Aliases

When you install ColdBox modules that have web-accessible assets (like cbdebugger, cbswagger, relax), you MUST add aliases:

# Install a module with UI
box install cbdebugger

# Add the alias to server.json
"aliases": {
    "/cbdebugger": "./modules/cbdebugger",
    "/coldbox/system/exceptions": "./lib/coldbox/system/exceptions/",
    "/tests": "./tests/"
}

# Restart the server
box server restart

โš ๏ธ Important: Without proper aliases, module UI assets will return 404 errors. This is the most common issue when using the Modern template.

๐ŸŽฏ How Application Bootstrap Works

Understanding the bootstrap flow is critical for working with this template:

  1. Request arrives at /public/index.cfm
  2. /public/Application.cfc sets critical mappings:
    COLDBOX_APP_ROOT_PATH = this.mappings["/app"]
    COLDBOX_APP_MAPPING = "/app"
    COLDBOX_WEB_MAPPING = "/"
    
  3. ColdBox loads config from /app/config/ColdBox.cfc
  4. Routes defined in /app/config/Router.cfc
  5. Handlers process requests from /app/handlers/

Security Note: /app/Application.cfc contains only abort; to prevent direct web access to application code.

๐Ÿ’ป Development Workflows

Installing Dependencies

# Install all dependencies
box install

# Install a specific module
box install cbsecurity

# Install development dependencies
box install testbox --saveDev

Running the Server

# Start server (uses server.json config)
box server start

# Start with specific engine
box server start cfengine=boxlang@be

# Stop server
box server stop

# Restart server
box server restart

# Open server in browser
box server open

Code Formatting

# Format all code
box run-script format

# Check formatting without changes
box run-script format:check

# Watch mode - auto-format on save
box run-script format:watch

Running Tests

# Run all tests
box testbox run

# Run tests in browser
box server start
# Navigate to: http://localhost:8080/tests

๐Ÿงช Testing Patterns

Tests extend coldbox.system.testing.BaseTestCase with appMapping="/app":

component extends="coldbox.system.testing.BaseTestCase" appMapping="/app" {

    function beforeAll(){
        super.beforeAll();
        // Global test setup
    }

    function run(){
        describe("User Handler", function(){
            beforeEach(function(currentSpec){
                // CRITICAL: Call setup() to create fresh request context
                setup();
            });

            it("can list users", function(){
                var event = this.get("users.index");
                expect(event.getValue(name="users", private=true))
                    .toBeArray();
            });

            it("can show a user", function(){
                var event = this.get("users.show?id=1");
                expect(event.getValue(name="user", private=true))
                    .toBeStruct();
            });
        });
    }
}

Key Testing Methods:

  • this.get(event) / this.post(event) - Simulate HTTP requests
  • execute(event) - Execute event without HTTP simulation
  • event.getValue(name, default, private) - Get from rc/prc
  • event.getHandlerResults() - Get return value from handler

๐Ÿณ Docker Support

Building Docker Images

# Build Docker container
box run-script build:docker

# Run Docker container
box run-script run:docker

Using Docker Compose

We include a docker/docker-compose.yml stack with database support:

# Start the stack
cd docker
docker-compose up -d

# Stop the stack
docker-compose down

# View logs
docker-compose logs -f

โ˜• Java Dependencies

If your project relies on Java third-party dependencies, use the included Maven pom.xml:

<!-- Add to pom.xml -->
<dependencies>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.10.1</version>
    </dependency>
</dependencies>

Then download dependencies:

mvn install

JARs are copied to /lib/java/ and automatically class-loaded by Application.cfc via this.javaSettings.loadPaths.

You can find Java dependencies at: https://central.sonatype.com/

๐Ÿ” Environment Configuration

Using Environment Variables

  1. Copy .env.example to .env:

    cp .env.example .env
    
  2. Use getSystemSetting() in your config:

    // In /app/config/ColdBox.cfc
    variables.coldbox = {
        appName: getSystemSetting("APPNAME", "My App")
    };
    
    // In your handlers/models
    variables.apiKey = getSystemSetting("API_KEY");
    
  3. Set environment variables:

    # In .env file
    APPNAME=My Awesome App
    API_KEY=your-secret-key
    

๐Ÿ’‰ Dependency Injection

Use WireBox annotations for dependency injection:

component {
    property name="userService" inject="UserService";
    property name="wirebox" inject="wirebox";
    property name="cachebox" inject="cachebox";
    property name="logbox" inject="logbox";

    function list(){
        return userService.getAll();
    }
}

Common Injection Patterns:

  • inject="coldbox" - ColdBox controller
  • inject="wirebox" - WireBox injector
  • inject="cachebox:default" - Default cache
  • inject="logbox:root" - Root logger
  • inject="coldbox:setting: settingName" - Application setting

๐ŸŽฎ Handler Patterns

Standard Handler Structure

component extends="coldbox.system.EventHandler" {

    // All actions receive three arguments:
    function index(event, rc, prc){
        // rc = Request collection (FORM/URL variables)
        // prc = Private request collection (handler-to-view data)
        prc.users = userService.list();
        event.setView("users/index");
    }

    // RESTful responses
    function data(event, rc, prc){
        return [
            { "id": 1, "name": "Luis" },
            { "id": 2, "name": "Joe" }
        ];
    }

    // Relocations
    function save(event, rc, prc){
        userService.save(rc);
        relocate("users.index");
    }
}

๐Ÿ—บ๏ธ Routing Patterns

In /app/config/Router.cfc:

component {
    function configure(){
        // Named routes
        route("/healthcheck", function(event, rc, prc){
            return "Ok!";
        });

        // RESTful resources
        resources("users");

        // API routes
        route("/api/v1/users", function(event, rc, prc){
            return { "data": userService.list() };
        });

        // Conventions-based routing (keep at end)
        route(":handler/:action?").end();
    }
}

๐Ÿ’ป VSCode Helpers

We include VSCode configuration to enhance your development experience:

  • .vscode/settings.json - Introspection helpers for ColdBox and TestBox ๐Ÿ”
  • .vscode/tasks.json - Tasks to run CommandBox tasks and TestBox bundles โšก

Custom Tasks

  • Run CommandBox Task - Open a CommandBox task and run it ๐Ÿƒโ€โ™‚๏ธ
  • Run TestBox Bundle - Open the bundle you want to test and run it ๐Ÿงช

To run tasks: Open command palette (โ‡งโŒ˜B on Mac) and choose Tasks: Run Build Task

๐ŸŽ‰ Welcome to ColdBox

ColdBox Hierarchical MVC is the de-facto enterprise-level HMVC framework for CFML developers. It's professionally backed, conventions-based, modular, highly extensible, and productive.

Key Features

๐Ÿ“š Learning ColdBox

ColdBox has the most extensive documentation of all modern CFML frameworks. ๐Ÿ“–

If you don't like reading, try our video learning platform: CFCasts ๐ŸŽฅ

๐Ÿ’ฐ ColdBox Sponsors

ColdBox is a professional open-source project funded by the community and Ortus Solutions, Corp.

Become a sponsor: https://patreon.com/ortussolutions โค๏ธ

๐Ÿ“„ License

Apache License, Version 2.0.

๐Ÿšจ Common Issues & Solutions

Module UI Assets Not Loading (404 errors)

Problem: Installed a module with web UI (like cbdebugger) but getting 404 errors.

Solution: Add a CommandBox alias in server.json:

"aliases": {
    "/cbdebugger": "./modules/cbdebugger"
}

Then restart: box server restart

Tests Can't Find Handlers/Models

Problem: Tests fail with "Handler not found" or "Model not found".

Solution: Ensure your test component has appMapping="/app":

component extends="coldbox.system.testing.BaseTestCase" appMapping="/app" {

Direct Access to /app/ Returns 404

Problem: Trying to access /app/handlers/Main.cfc directly.

Solution: This is by design! Application code in /app is NOT web-accessible for security. All requests must go through /public/index.cfm.

โš™๏ธ Engine Compatibility

This template is designed for:

  • โœ… Adobe ColdFusion 2021+ - Fully supported
  • โœ… BoxLang 1.0+ - Fully supported
  • โŒ Lucee - Not supported on this template

To specify your engine in server.json:

"app": {
    "cfengine": "boxlang@be"     // For BoxLang
    // OR
    "cfengine": "adobe@2023"     // For Adobe ColdFusion
}

๐Ÿ”„ Migrating from Default Template

If you're migrating from the default ColdBox template to Modern:

  1. Move application code: Copy /handlers, /models, /views, etc. to /app/
  2. Update Application.cfc: Use the Modern template's /public/Application.cfc as reference
  3. Configure aliases: Add necessary aliases to server.json for modules
  4. Update tests: Ensure appMapping="/app" in test components
  5. Move public assets: Only CSS, JS, images go in /public/includes/

๐Ÿค Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.


THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


Unreleased

8.1.0 - 2025-10-11

8.0.0 - 2025-10-10

  •   Ortus Solutions
  • Published
  • 8.1.0+6 is the latest of 14 release(s)
    Published
  • Published on {{ getFullDate("2025-10-11T15:21:48Z") }}

$ box install cbtemplate-modern

No collaborators yet.
  • {{ getFullDate("2022-03-22T21:38:37Z") }}
  • {{ getFullDate("2025-10-11T15:21:48Z") }}
  • 2,818
  • 184