ColdBox HMVC Documentation
DocsSourceSupportTraining
5.x
5.x
  • Introduction
  • Intro
    • Introduction
      • What's New With 5.6.0
      • What's New With 5.5.0
      • What's New With 5.4.0
      • What's New With 5.3.0
      • What's New With 5.2.0
      • What's New With 5.1.4
      • What's New With 5.1.3
      • What's New With 5.1.2
      • What's New With 5.1.1
      • What's New With 5.1.0
      • What's New With 5.0.0
      • Upgrading to ColdBox 5
      • About This Book
      • Author
  • For Newbies
    • 60 Minute Quick Start
      • Installing ColdBox
      • My First ColdBox Application
      • My First Handler & View
      • Linking Events Together
      • Working With Event Handlers
      • Adding A Layout
      • Adding A Model
      • RESTFul Data
      • Next Steps
  • Getting Started
    • Getting Started Guide
    • Installation
    • Conventions
    • Configuration
      • ColdBox.cfc
        • Configuration Directives
          • CacheBox
          • ColdBox
          • Conventions
          • Environments
          • Flash
          • InterceptorSettings
          • Interceptors
          • Layouts
          • LayoutSettings
          • LogBox
          • Modules
          • ModuleSettings
          • Settings
          • WireBox
        • System Settings (Java Properties and Environment Variables)
      • Using Settings
      • Bootstrapper - Application.cfc
  • The Basics
    • Request Context
    • Routing
      • Requirements
        • Rewrite Rules
      • Application Router
      • Routing DSL
        • Routing By Convention
        • Pattern Placeholders
        • Routing Methods
        • Resourceful Routes
        • Named Routes
        • Routing Groups
        • Routing Namespaces
      • Building Routable Links
      • RESTFul Extension Detection
      • HTTP Method Spoofing
      • HTML Base Tag
      • Pathinfo Providers
    • Event Handlers
      • How are events called?
      • Getting & Setting Values
      • Setting Views
      • Relocating
      • Rendering Data
      • Sending Files
      • Interception Methods
        • Pre Advices
        • Post Advices
        • Around Advices
      • Model Integration
        • Model Data Binding
      • HTTP Method Security
      • Implicit Methods
      • Executing Events
      • Executing Routes
      • Viewlets - Reusable Events
      • Event Caching
      • Validation
    • Layouts & Views
      • Views
        • Rendering Views
        • Rendering External Views
        • Rendering With Local Variables
        • Rendering Collections
        • View Caching
        • View Helpers
        • View Events
      • Layouts
        • Basic Layouts
        • Default Layout
        • Nested Layouts
        • Overriding Layouts
        • Layouts From A Module
        • Layout Helpers
        • Layout Events
      • Implicit Layout-View Declarations
      • Helpers UDF's
      • ColdBox Elixir
    • Models
      • Domain Modeling
        • Service Layer
        • Data Layers
        • Book
      • Conventions Location
      • WireBox Binder
      • Super Type Usage Methods
      • Injection DSL
        • Model Object Namespace
        • ColdBox Namespace
        • CacheBox Namespace
        • LogBox Namespace
        • WireBox Namespace
        • EntityService Namespace
      • Object Scopes
      • Coding: Solo Style
        • Datasource
        • Contact.cfc
        • ContactDAO.cfc
        • ContactService.cfc
        • Contacts Handler
      • Coding: ActiveEntity Style
        • ORM
        • Contact.cfc
        • Contacts Handler
        • Views
      • Coding: Virtual Service Layer
        • ORM
        • Contacts.cfc
        • Contacts Handler
        • Views
      • Coding: ORM Scaffolding
        • ORM
        • Contacts.cfc
        • Scaffold
  • HMVC
    • Modules
      • Core Modules
      • Locations
      • Parent Configuration
      • Module Layout
        • Changing The Module Layout
      • Module Service
        • Module Lifecycle
        • Module Registration
        • Module Activation
        • Module Unloading
        • Common Methods
        • Loading New Modules
        • Loading A-la-carte Modules
        • Module Events
      • ModuleConfig
        • Public Module Properties\/Directives
        • The Decorated Variables
        • The configure() Method
        • Module Settings
        • Environment Control
        • Interceptor Events
      • Module Event Executions
      • URL Routing
        • Default Route Execution
        • Module Routes Files
      • Request Context Module Methods
      • Layout and View Renderings
        • Layout\/View Discovery
        • Overriding Views
        • Overriding Layouts
        • Default Module Layout
        • Explicit Module Renderings
      • Models
      • Module CF Mappings
      • Module Dependencies
      • Module Helpers
      • Module Bundles
      • Module Inception
  • Testing
    • Testing Quick Start
    • Testing ColdBox Applications
      • Test Harness
      • ColdBox Testing Classes
      • Integration Testing
        • Test Annotations
        • Common Methods
        • Life-Cycle Events
        • Test Setup
        • The execute() Method
        • The Handler To Test
        • The Integration Test
        • Handler Returning Results
        • Testing Without Virtual Application
        • Rendering Results
        • HTTP Method Mocking
      • Interceptor Testing
      • Model Object Testing
      • Tips & Tricks
  • Digging Deeper
    • Interceptors
      • How do they work?
        • Conventions
      • Interceptor Declaration
      • Interceptor Registration
      • Core Interception Points
        • Application Life Cycle Events
        • Object Creating Events
        • Layout-View Events
        • Module Events
        • CacheBox Events
      • Restricting Execution
      • Interceptor Output Buffer
      • Custom Events
        • Configuration Registration
        • Programmatic Registration
        • Listening
        • Announcing Interceptions
      • Unregistering Interceptors
      • Reporting Methods
      • Interceptor Asynchronicity
        • Async Announcements
        • Async Listeners With Join
        • Async Listeners No Join
        • Asynchronous Annotations
    • Flash RAM
      • Flash Storage
      • Using Flash RAM
      • Creating Your Own Flash Scope
    • HTML Helper
    • ColdBox Proxy
      • Getting Started
      • The Base Proxy Object
      • The Event Handlers
        • Distinguishing Request Types
        • RenderData()
      • Proxy Events
      • Standard Return Types
      • Caveats & Gotchas
    • Request Context Decorator
    • Controller Decorator
    • Recipes
      • Building REST APIs
      • Application Templates
      • ColdBox Exception Handling
      • Debugging ColdBox Apps
      • Clearing the View Cache
      • Building a simple Basic HTTP Authentication Interceptor
  • Architecture Concepts
    • What is MVC
    • What is ColdBox
    • How ColdBox Works
    • Testing Concepts
      • Functional Testing
      • Non-Functional Testing
      • Bugs Cost Money
      • Static Testing
      • Dynamic Testing
      • Developer Focus
      • Testing Vocabulary
Powered by GitBook
On this page
  • IDE Tools
  • Install CommandBox
  • Create A New Site
  • File/Folder Conventions
  • Start It Up
  • Take A Look Around
  • Building On
  • Install Packages
  • Creating A Model
  • Tie It All Together
  • What's Next?
  • Getting Help

Was this helpful?

Edit on Git
Export as PDF
  1. Getting Started

Getting Started Guide

Last updated 5 years ago

Was this helpful?

The ColdBox HMVC Platform is the de-facto enterprise-level HMVC framework for CFML developers. It's professionally backed, highly extensible, and productive. Getting started with ColdBox is quick and painless. The only thing you need to begin is , a command line tool for CFML developers.

This is a one-page introductory guide to ColdBox. If you are new to MVC or ColdBox, you can also leverage our as well.

IDE Tools

ColdBox has the following supported IDE Tools:

  • Sublime -

  • VSCode -

  • CFBuilder -

Install CommandBox

You can read through our one-page . Or simply grab the CommandBox executable from the and double click it to run.

You should now be seeing a prompt that looks like this:

Create A New Site

Now we're cooking with gas! Let's create a new ColdBox application. CommandBox comes with built-in commands for scaffolding out new sites as well as installing ColdBox and other libraries. We'll start by changing into an empty directory were we want our new app to live. If necessary, you can create a new folder.

CommandBox> mkdir playground --cd

Now let's ask CommandBox to create a new ColdBox app for us.

CommandBox> coldbox create app MyPlayground

You can also issue a coldbox create app help command and get help for the creation command.

File/Folder Conventions

This command will place several new folders and files in your working directory. Let's run the ls command to view them.

CommandBox> ls

Here's a rundown of the important bits.

  • coldbox - This is the ColdBox framework managed by CommandBox

  • config/Coldbox.cfc - Your application configuration object

  • config/Router.cfc - Your application URL Router

  • handlers - Your controller layer, which in ColdBox they are called event handlers

  • layouts - Your HTML layouts

  • models - This holds your model CFCs

  • modules - This holds the CommandBox tracked modules

  • modules_app - This holds your app's modules

  • views - Your HTML views will go here

Start It Up

Now that our shiny new MVC app is ready to go, let's fire it up using the embedded server built into CommandBox. You don't need any other software installed on your PC for this to work. CommandBox has it all!

CommandBox> start --rewritesEnable

In a few seconds, a browser window will appear with your running application. This is a full server with access to the web administrator where you can add data sources, mappings, or adjust the server settings. Notice the handy icon added to your system tray as well. The --rewritesEnable flag will turn on some basic URL rewriting so we have nice, pretty URLs.

Take A Look Around

ColdBox uses easy conventions to define the controllers and views in your app. Let's open up our main app controller in your default editor to have a looksie.

CommandBox> edit handlers/main.cfc

At the top, you'll see a function named "index". This represents the default action that runs for this controller, which in ColdBox land they are referred to as event handlers.

// Default Action
function index(event,rc,prc){
    prc.welcomeMessage = "Welcome to ColdBox!";
    event.setView("main/index");
}

Now let's take a look in the main/index view. It's located int he views folder.

CommandBox> edit views/main/index.cfm

This line of code near the top of the view is what outputs the prc.welcomeMessage variable we set in the controller.

<h1>#prc.welcomeMessage#</h1>

Try changing the value being set in the handler and refresh your browser to see the change.

prc.welcomeMessage = "This is my new welcome message";

Building On

Let's define a new event handler now. Your controllers act as event handlers to respond to requests, REST API, or remote proxies.

Pull up CommandBox again and run this command.

CommandBox> coldbox create handler helloWorld index,add,edit,list

That's it! You don't need to add any special configuration to declare your handler. Now we have a new handler called helloWorld with actions index, add, edit, and list. The command also created a test case for our handler as well as stubbed-out views for each of the actions.

Now, let's re-initialize the framework to pick up our new handler by typing ?fwreinit=1 at the end of the URL.

Let's hit this new controller we created with a URL like so. Your port number will probably be different.

127.0.0.1:43272/helloWorld

Normally the URL would have index.cfm before the /helloWorld bit, but our --rewritesEnable flag when we started the server makes this nicer URL possible.

Install Packages

Here's some useful examples:

  • BCrypt -- Industry-standard password hashing

  • cbdebugger -- For debugging Coldbox apps

  • cbjavaloader - For interacting with Java classes and libraries

  • cbMarkdown - For writing in markdown

  • cbMessagebox -- Display nice error/success messages

  • cborm -- Awesome ORM Services

  • cb18n -- For multilingual sites

  • cbt - ColdBox templating language

  • cbValidation - Back-end validation framework

  • qb - Fluent query builder and schema builder

  • route-visualizer - For visualizing your application routes

Install cbmessagebox from the CommandBox prompt like this:

CommandBox> install cbmessagebox

We can see the full list of packages by using the list command.

CommandBox> list
Dependency Hierarchy for myApp (0.0.0)
+-- cbmessagebox (1.0.0)
+-- coldbox (4.0.0)

Right now we can see that our app depends on coldbox and cbmessagebox to run. We'll use our new cbmessagebox module in a few minutes. But first, we'll create a simple Model CFC to round out our MVC app.

Creating A Model

Models encapsulate the business logic your application. They can be services, beans, or DAOs. We'll use CommandBox to create a GreeterService in our new app with a sayHello method.

CommandBox> coldbox create model GreeterService sayHello --open

Tip: The --open is a nice shortcut that opens our new model in our default editor after creating it.

Let's finish implementing the sayHello() method by adding this return statement and save the file.

We can also add the word singleton to the component declaration. This will tell WireBox to only create one instance of our service.

component singleton {

    function sayHello(){
        return 'Hey, you sexy thing!';
    }

}

What is WireBox?

WireBox is a dependency injection framework that is included with ColdBox. It will manage all object creations, persistence and assembling. You don't have to worry about using new or createobject() for CFCs anymore.

Tie It All Together

Ok, let's open up that helloWorld handler we created a while back. Remember, you can hit tab while typing to auto-complete your file names.

CommandBox> edit handlers/helloWorld.cfc

We'll inject our greeterService and the cbmessagebox service into the handler by adding these properties to the top of /handlers/helloWorld.cfc.

What is this magical injection? Injection is a way to get references of other objects placed in the variables scope of other objects. This makes your life easier as you don't have to be creating objects manually or even knowing where they exist.

This will put the instance of our services in the variables scope where we can access it in our action methods.

component {

    property name='greeterService' inject='greeterService';
    property name='messageBox' inject='@cbmessagebox';

    ...
}

And now in our index method, we'll set the output of our service into an info message.

function index( event, rc, prc ){
    messageBox.info( greeterService.sayHello() );
    event.setView( "helloWorld/index" );
}

One final piece. Open up the default layout located in layouts/Main.cfm and find the #renderView()#. Add this line right before it to render out the message box that we set in our handler.

#getInstance( 'messagebox@cbmessageBox').renderIt()#
<div class="container">#renderView()#</div>

Now hit your helloWorld handler one final time with ?fwreinit=1 in the URL to see it all in action! (Again, your port number will most likely be different.

127.0.0.1:43272/helloWorld?fwreinit=1

What's Next?

Congratulations! In a matter of minutes, you have created a full MVC application. You installed a community module from ForgeBox, created a new handler/view and tied in business logic from a service model.

As easy as that was, you're just scratching the surface of what ColdBox can do for you. Continue reading this book to learn more about:

  • Environment-specific configuration

  • Easy SES URL routing

  • Tons of 3rd party modules

  • Drop-in security system

  • Sweet REST web service support

Getting Help

ColdBox is Professional Open Source under the Apache 2.0 license. We'd love to have your help with the product.

Tip: You can find many scaffolding templates for ColdBox in our Github organization:

Tip: If you are creating an app to run on any other server than the commandbox server, you will need to manually set up URL rewriting. More info here:

ColdBox's MVC is simple, but it's true power comes from the wide selection of modules you can install into your app to get additional functionality. You can checkout the full list of modules available on the Forgebox directory: .

If you run into issues or just have questions, please jump on our and our and ask away.

github.com/coldbox-templates
/the-basics/routing/requirements
www.forgebox.io
forgebox.io/type/modules
ColdBox Google Group
Slack team
CommandBox
60 minute quick start guide
https://packagecontrol.io/packages/ColdBox Platform
https://marketplace.visualstudio.com/items?itemName=ortus-solutions.vscode-coldbox
https://www.forgebox.io/view/ColdBox-Platform-Utilities
CommandBox Getting Started Guide
download page
http://www.ortussolutions.com/products/commandbox
CommandBox Shell
Default App Template