Wiki Navigation

ColdBox FAQ

Here you can find some of the most common questions and answers. If you would like a question to be answered in this page, please submit it to info@coldboxframework.com.

Installation
Overview of ColdBox
Configuration File
ColdBox Dashboard
1. > How do I go to my ColdBox Dashboard?
2. > What is my default ColdBox Dashboard Password?
Contributing, Reporting, Bugs

Installation

> Do I need to place the ColdBox system folder in every application I develop?

You will have one installation of ColdBox per web server or you can refactor the framework for embedding it into your applications.

See cbInstallGuide

> Can I refactor the source code for my custom server or application?

You can refactor the code base in any way you like. Please look at both the Install Guide and the Refactoring Guide for an in depth tutorial.

> Does ColdBox work on ColdFusion 6.X?

As Adobe no longer supports ColdFusion 6.X, ColdBox will stop its support for it in future versions. (See Ticket #248)

> Does ColdBox work on Blue Dragon?

Yes, ColdBox is supported and tested for Blue Dragon 7.X and above as of version 1.1.0. However, some plugins will not work like the JavaLoader and the cfcViewer due to their java, adobe, coldfusion specific natures. Please see the System Requirements for more information.

> Does ColdBox work on Railo?

Yes, ColdBox is supported and tested for Railo 2.0 and above. However, some plugins will not work like the JavaLoader due to their java, adobe, ColdFusion specific natures. Please see the System Requirements for more information.

> I just downloaded the ColdBox bundle archive, how do I install it? How do I start?

- see cbInstallGuide

> I need to update my ColdBox installation, what do I do?

Just replace your old framework folder with the new one. Make a backup if needed and make sure you reinitialize the applications so the changes take effect. I recommend a server restart or a wipe of the application scope. See cbInstallGuide, cbUpgradeGuide

> What are the framework's System Requirements?

- see cbSystemRequirements

> What is ColdBox's License?

The ColdBox Framework is free and open source. However, if you use this product please know that it is bound to the Apache License, Version 2.0. If you use ColdBox, please try to make mention of it in your software or web site or add a Powered By ColdBox icon. You can also Fund This Project

See License Agreement

> What is the Dashboard's License?

The ColdBox dashboard is a separate application and entity from the ColdBox Framework. The ColdBox dashboard is free but not open source. Please read the entire section of the License Agreement on the ColdBox Dashboard.

Overview of ColdBox

> What is a Framework?

A framework is a solid software foundation on which you can build software applications on. A good framework, provides me with a set of reusable code and tools that I can use to increase my productivity, and it provides me with a standard that comes in very handy when working in a team environment. ColdBox is much more than a framework, it is also a development toolkit. It will provide you with a standard methodology and increase your development turnaround.

> Can ColdBox be used by a team of developers?

YES! ColdBox was designed for use in team environments. Due to its CF logic nature and XML-less dialects, the framework's methodology is easier to learn and implement. It follows the MVC pattern so your projects will have consistency, organization and de-coupling, which in turns favors software maintenance. As an added bonus, due to ColdBox's Object Oriented approach, your code will have to follow some OOP standards. This by no means expresses that you will code better!! This is not a Magic Framework, but it sure will help you

> What is this MVC Design Pattern?

The MVC stands for Model View Controller and you can read more on this design pattern here or in our own MVC guide.

Model-view-controller (MVC) is an architectural pattern used in software engineering. In complex computer applications that present a large amount of data to the user, a developer often wishes to separate data (model) and user interface (view) concerns, so that changes to the user interface will not affect data handling, and that the data can be reorganized without changing the user interface. The model-view-controller solves this problem by decoupling data access and business logic from data presentation and user interaction, by introducing an intermediate component: the controller.

> Is ColdBox only an MVC Framework?

No, ColdBox can morph into a remote driven framework without the need to render HTML or views. In summary, ColdBox is an MVC framework, a software toolkit and a remote framework. See Proxy Guide.

> Do I need to use ColdBox for every single application I build?

This is always a million dollar question and the answer is NO! You don't need to use a framework for everything you build. For some scenarios a framework would be more of a deterrent than a helping hand. It would be like killing a fly with a canon, you know that won't get you far. There are some cases where you only need two or three simple forms, some good organization and you are ready to roll. However, for projects where you can see them grow, where you will be working with a team of developers and you need flexibility, I will turn to ColdBox. ColdBox will organize your code into reusable components, it will make your code more object oriented and bottom line, IT WILL SAVE YOU TIME.

> Is ColdBox hard to learn?

It all depends on your ColdFusion background. The framework was designed to help developers code in a more organized way, create several aspects of a program and overall empowerment of the developer. You will find that you can dig right in to the framework and start coding. You do not have to learn an XML dialect or logic, you will learn how to configure an application and then it is just a matter of creating coldfusion code. This website has plenty of documentation and ColdBox comes with a samples gallery with over 13 different applications that you can learn from. You also have the !ColdBox Forums where you can post for help. ColdBox has a very basic core API that you interact with which makes it very unobtrusive to the developer. Here is a testimonial from Stephen Eller:

ColdBox is really easy, so far, to setup and maintain. Coming from a primarily fusebox background, !Coldbox is definitely much easier to get up and running.

> When was ColdBox born? Who built it?

A very minimal ColdBox was born in August of 2005 and was released as an open source project on June 16, 2006. The creator of ColdBox is Luis Majano. I am an accomplished Computer Engineer working for ESRI (Environmental Systems Research) in Redlands, California. I have been creating web applications since 1999, specializing in ColdFusion and Java applications. I have several Advanced ColdFusion Certifications and open source projects. My goal with providing ColdBox as an open source project, was to give back to the developer community and to help ColdFusion developers build their applications on a solid foundation.

> Is ColdBox a front controller framework?

Yes. ColdBox is a front controller framework. This means that all incoming requests come to one location, the index.cfm file.

> What is the main difference between ColdBox and other frameworks like fusebox, mach ii, and model glue?

Well, the main difference is that ColdBox is not based on a strict XML dialect but on ColdFusion logict itself and several conventions instead of configurations. So instead of writing your declarations in XML and be restricted by it, you write your events in coldfusion and use the framework's methods to set views to render/dispatch, call models (Business layer), call plugins for application specific tasks, etc.

Another main difference is that you can extend the framework by creating custom plugins. You can build any amount of plugins and create you own library of tasks and aspects for your applications. You can then easily instantiate them when needed by just declaring their main location in the framework's configuration file.

ColdBox is not only an MVC presentation tier framework, but also a development toolkit. It provides you with pre-built modules that will make your development easier and faster. Since ColdBox is an event-driven framework, you can integrate events created from other applications by simply placing them in your handlers. You do not need to alter any configuration files or XML. You have complete re-usability of your events, views and plugins.

ColdBox can also act as a remote driven framework to power your Flex/Air/Ajax applications.

> What are these ColdBox Conventions?

Since the very first version of ColdBox, conventions have been used over configuration. These conventions specify a layout of an application for the framework to find what it needs and it provides a convention on how implicit events are called. Until version 2.0.0 these conventions where static, they could not be changed. This changed with the release of 2.0.1, since now you can define the framework's conventions on the following locations:

config file location
event handlers location
layouts location
views location
plugins location
much more coming soon

So now you have the control of even modifying your own conventions as necessary for the entire framework or per-application. You also have conventions on methods for event handlers for implicit invocations such as preHandler, postHandler, onMissingAction. Please read the Event Handlers Guide for a more in depth look at implicit invocation conventions.

> What are events?

Events are what makes a ColdBox application actually do something. A user is able to call a specific 'event' normally by clicking a link, posting a form field, etc The framework will then parse and locate the correct event handler to instantiate and run.

http://mysite.com/index.cfm?event=ehGeneral.dspHome

The latter, will tell the framework to run the dspHome method on the ehGeneral handler cfc

<input type="hidden" name="event" value="ehGeneral.doLogin" />
or
<form action="index.cfm?event=ehGeneral.doLogin">

The latter, will tell the framework to run the doLogin method on the ehGeneral cfc when the form is submitted. All interaction with the framework is done via events.

> What are event handlers?

Event handlers are CFCs which contain public/remote functions that are triggered by events. They can also contain private/package functions that can be used by events but cannot be called externally by the framework. They are not defined in any XML dialect, they are registered by convention.

Event handlers are analogous to all the code we use to have at the top of our page which we used to call our models before or like many, did all the logic there. SO PLEASE DO NOT DO THAT. ADHERE TO BEST PRACTICES.

Every remote/public method is automatically exposed as a runnable event in the ColdBox framework. These events can then be defined for some implicit invocations in the coldbox.xml and they will execute when the framework detects them. Another important aspect of event-driven architectures is that the event action can be passed via the URL or the FORM. The framework captures this action variable and uses it to execute the correct event handler method. From within the event handler's method, you will program the flow of the application, redirect data to the correct business logical units (model calls), logging, error trapping, validation, etc.

> Does every event handler cfc need an init method?

Every event handler does NOT need an init method. However, if you create an init method for an event handler, then you will need to call the parent's init method by using: super.init(arguments.controller). If you do not write the super.init call, then the handler will fail.So if you write an init method for an event handler, make sure you make the appropriate call to the super.init() method like the example below:

<cffunction name="init" access="public" returntype="ehGeneral" output="false">
  <cfargument name="controller" type="any" required="yes">
  <cfset super.init(arguments.controller)>
  <!--- Your Code here --->
  <cfreturn this>
</cffunction>

> Can I call other events from my event handler's methods ?

Yes, you can call other public or private events from your current executing event. You can use the runEvent() method to do this. This way, you can chain events by calling them from your current executing event. (See API)

<!--- Call private method --->
<cfset runEvent(event="general.myPrivateMethod",private=true)>

<!--- Call public method --->
<cfset runEvent(event="general.doThis")>

> What are the best practices in the Event Handlers?

I always try to have some kind of mapping between the different logical sections or modules of my application and their event handlers. For example, if my application has a section for user management, with master and detail views, I'd create a single event handler cfc to hold all the methods related to that module. Now, large sections of your application that are more complex and have lots of actions and views, may require you to split the event handlers even more (like packages/directories), but the idea is the same.

The handler cfc's are also objects and therefore they should have their specific identity and function. So you need to map them in the best logical way according to their functions. If you need more flexibility you can even create directories (packages) and place them in logical buckets. This is mostly used in large applications as mentioned above. So think of them as entities and how they would do tasks for your via the events. Once you do this, you can come up with a very good cohesive event model for your applications.

> Can I unit Test my Handlers?

Well, since 2.0.1 you can!! A sample for unit testing handlers comes bundled in the Application Template. Just look inside the handlers directory, you will find a tests directory with a base unit test component and some samples. Look at the Unit Testing Handlers Guide. ColdBox supports event handler testing on MXUnit and CFCUnit.

> What are ColdBox Plugins?

What are plugins? Plugins are cfc's that are built to extend the core framework or application functionality without hindering system performance. The main distribution of !Coldbox contains several useful core plugins that not only makes ColdBox a framework but a developer toolkit. The idea behind the plugin concept is to create a reusable and extensible architecture for developers to build applications or framework specific tasks that could be easily shared and loaded on demand within your applications. This means that you can easily code plugins, completely extend your application and even share them with your friends. You can create as many plugins as you want and build a plugins' library that can be located by just specifying it on the coldbox.xml or be dropped in to the application's custom plugins convention. You will then be able to get the custom plugin and use it on any of your ColdBox applications.

Not only can you use them, but ColdBox maintains their persistence for you and can do cleanup on those objects for you. Via metadata (annotations) you can tell how the plugin behaves and persists. ColdBox detects the metadata and it will cache and persist them in its built in cache manager. You don't even have to worry about creating them, you just worry about how to use them. More free time to contribute to this project!!

> Can plugins be organized into packages?

ABSOLUTELY!! and please do. You can organize packages, either core plugins or custom plugins into their own directories. You can then call them using their qualified names.

Example: I create a log directory and place a log4j.cfc plugin inside of the log directory. In order to call this plugin, I would do the following (Assuming you placed the log directory inside of the core plugins directory of the framework: /coldbox/system/plugins/log):

getPlugin("log.log4j").info("This is an info message");

That is it! Called via its qualified name.

> What is the Request Collection?

The request collection is a data structure that the framework creates for every user request and places it in the request context object. It captures the FORM and URL variables into this structure for you to use in your event handlers, layouts, views and plugins. You can then place values and get values from this structure from anywhere in the life cycle of a request. For all the methods See the API:

> What is an application's Directory Structure?

- see cbDirectoryStructure

> Do I need cookies enabled?

Yes, if you will be using debug mode.

Coldbox Install and Cookie Datasource Error: If you are using ColdBox and run into the missing Cookie Datasource error, it's most likely because you have your Cookies set to NONE in the ColdFusion? Administrator and the Debug Console ENABLED in the ColdBox config. Toggle one of your settings and you'll be back in business.

> Does ColdBox support child applications?

Yes, you basically create another Directory Structure embedded within an application. However, the preferred way is to just create packages(directories) for the different application structures within your application. Create folders for handlers and views, you can then assign different rendering layouts and just code your application with ease.

> I just changed my coldbox.xml but I don't get the results or the framework just does not start?

Well, you need to reload the structures by using the fwreinit=1 URL action via the index page. Look at the URL Actions Guide

example: http://localhost/index.cfm?fwreinit=1

or if you are in development you can use the ConfigAutoReload setting in your coldbox.xml. This will auto reload your settings if you are developing your application. See Settings Guide

<Setting name="ConfigAutoReload" value="true" />

> My application executes the application start handler in every request?

Look at the ConfigAutoReload setting in your coldbox.xml and set it to false.

> I am using my own CustomExceptionHandler and I don't get any more bug reports? Why is this happening to me!

Well, you decided to use your own exception handler, so you need to log the bugs yourself!! So all you need to do is call

getPlugin("logger").logErrorWithBean(Event.getvalue("ExceptionBean"));

You are calling logErrorWithBean instead of just logError, because you are dealing with a thrown exception already and have the Exception Bean. However, if you wanted to, you can call log error, but send in the correct parameters. It goes to a bean anyways!!

See cbExceptionHandler

> How do I get data from my event handlers to my layouts and views?

Well, you use the request collection via the event object. You have the Event.setValue() method that you use to set values in the request collection, which is a global data structure where you can put and take values from anywhere in the framework: event handlers, layouts, views, plugins, etc. In your views you can then use the Event.getValue() method and retrieve your data. See CFC API. ColdBox also creates its own scope for the views & layouts to use: rc. So you can just reference the scope and the name of the variables this way.

> Can I render something and place it in a variable?

ColdBox supports Content Variables via the renderView() method. So if you wanted to render a view and place it in a variable, all you need to do is:

<cfset myCCV = renderView("customtags/navigation")>

And that is it, you have myCCV containing the navigation view from the customtags directory under your views directory in your main application.

Now, you also have the renderExternalView() method which will render any type of view "cfm,htm,js,*" and give you the content in a variable. The good thing is that that view will also have access to the request context object via the event variable.

> Can I render multiple views?

Yes, just use the renderer plugin or the renderView() method.

> How can I set a view to be rendered without a layout?

You use the same Event.setView() method but passing a second Boolean parameter. The second parameter is the nolayout flag. So if you want to render a view without a layout then use: Event.setView("vwMyView", true)

> Do I need to set a view in my Event Handler?

No, you can create event handlers without setting any views. These events can exist by themselves, relocate to other events or return data (if using the ColdBox Proxy). You can also explicitly tell the framework not to render anything by using the event.noRender() method. You can also set in your configuration file the DefaultView element so you don't have to set a view in your handlers.

> What takes precedence in ColdBox, FORM or URL?

FORM takes precedence.

Configuration File

> Can I override which configuration file gets loaded?

Since version 2.0.1 you can! A new variable has been setup: COLDBOX_CONFIG_FILE and you can use it before including the ColdBox template in your index.cfm or as a property in the Application.cfc file. You can declare the config file to load explicitly, else ColdBox will load the file used in its conventions. This is a great way to load the appropriate configuration file in multi-tiered environments or for unit testing.

See Custom Load a Config File

> What is this AppMapping Stuff in my config.xml? Do I really need a coldfusion mapping

You can set it to let the framework know where the application root resides. If you want the framework to auto-calculate it for you, then leave it blank. However, if you are using the framework as a remote framework or just using some remote calls, you NEED to set this setting. So as best practice, SET IT!

> How do I activate ColdBox AOP Logging?

In order for ColdBox to do your application logging, you must enable to settings in the config.xml.

EnableColdboxLogging set to TRUE
ColdboxLogsLocation set to the path where you want to store your log file. It can be relative only if within your application structure. If the location will be out of the application structure then the path must be absolute. The default location for this variable is logs

> How do I setup a datasource to use?

First of all, you need to declare the datasource in the xml using the new Datasources element. Look below for a sample:

<Datasources>
  <Datasource alias="myDSN" name="DSN" dbtype="mysql" username="" password="" />
</Datasources>

In this sample I declare a datasource called myDSN which points to the datasource DSN, which by the way is the name of the datasource in the Coldfusion Administrator, with no username or password. ColdBox reads the config and prepares Datasource beans for you to use in your application. So how do I get them? Simply by using the getDatasource("name") method.

<cfset mydsnBean = getDatasource("myDSN")>

And there you go, a datasource bean immediately available ON-DEMAND!!

> Can I use the i18N settings without a Resource Bundle?

Of course!! The resource bundles are complimentary to the i18N settings. So basically you leave the DefaultResourceBundle element empty. This tells the framework that you are using localization but without any resource bundles. However, you can load resource bundles on the fly by using the i18N plugin. So the sample below is to activate a Thai locale without any resource bundle:

<i18N>
    <DefaultResourceBundle></DefaultResourceBundle>
    <DefaultLocale>th_TH</DefaultLocale>
    <LocaleStorage>session</LocaleStorage>
</i18N>

ColdBox Dashboard

> How do I go to my ColdBox Dashboard?

You would use the following URLs:

http://localhost/coldbox/dashboard/cf8/index.cfm

OR

http://localhost/coldbox/dashboard/cf7/index.cfm

> What is my default ColdBox Dashboard Password?

- coldbox

Contributing, Reporting, Bugs

> How do I report a bug? How do I get Help?

The best way to report a bug is via email to the google groups mailing list: ColdBox@googlegroups.com or via bugs@coldboxframework.com You can also search for issues in the forums: http://forums.coldboxframework.com/

This is also the best way to get help.

> Who do I write to for contributing?

You can write to me: Luis Majano to the following address info@coldboxframework.com

> Who pays for all this?

Me, Luis Majano. So please donate! Click Here to Donate Now!