Getting Started Guide
The ColdBox HMVC Platform is the de-facto enterprise-level HMVC framework for CFML developers.
Need Help
IDE Tools
ColdBox has the following supported IDE Tools:
Install CommandBox and ColdBox CLI
You should now be seeing a prompt that looks like this:
Now let's install the ColdBox CLI
Now you will have the coldbox
namespace of commands. Run coldbox help
and discover it.
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 where we want our new app to live. If necessary, you can create a new folder.
Now let's ask CommandBox to create a new ColdBox app for us.
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.
Here's a rundown of the important bits (Even though they might be more generated files/folders)
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
tests - Your test harness for unit and integration testing
views - Your HTML views will go here
Start It Up
Now that our shiny new MVC app is ready 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!
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, and 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.
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.
Now let's take a look in the main/index
view. It's located int he views
folder.
This line of code near the top of the view outputs the prc.welcomeMessage
variable we set in the controller.
Try changing the value being set in the handler and refresh your browser to see the change.
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.
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.
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:
We can see the full list of packages by using the list
command.
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 of your application. They can be services, entities, or DAOs. We'll use CommandBox to create a GreeterService
in our new app with a sayHello
method.
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.
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.
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 manually create objects or even know where they exist.
This will put the instance of our services in the variables
scope where we can access it in our action methods.
And now, in our index
method, we'll set the output of our service into an info
message.
One final piece. Open up the default layout located in layouts/Main.cfm
and find the #view()#
. Add this line right before it to render out the message box that we set in our handler.
Here we leverage the cbMessagebox()
helper function which the MessageBox module collaborates to all layouts, views, handlers and interceptors.
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.
Last updated