[[Dashboard|<< Back to Dashboard]] [[Category:level-beginners]] {| align="right" | __TOC__ |} = My First ColdBox Application = == Introduction == This quick guide will show you how to start off and create a running ColdBox application. You can generate it via ANT or do a simple copy/paste of the ColdBox application template or use the ColdBox dashboard to generate an application. I would recommend you at least read the ColdBox Overview guide before reading this guide. How to start? Start off by copying the !ApplicationTemplate folder to your web root and name it to something you want. Then, open the '''''config/coldbox.xml.cfm''''' file and adjust it to your liking. You can read the [[ConfigurationFile Config Guide]] in order to understand all the variables and settings in this file. The easiest way to create new applications is by using the ColdBox Dashboard application generator or the included ANT build script '''build.xml'''. You can run it either in the command line or via Eclipse. This script is an application generator wizard. After this it will auto-generate the entire application for you and you can then just modify to your liking. Look below for a screenshot on how to run the build file from eclipse. ''See [[DirectoryStructure-Conventions]], [[ConfigurationFile]]''
'''The ColdBox ANT Application Generator'''
'''ANT Script: Generated Application'''
== Extra Configuration == If you copied the directory and did not use the ANT script, then you need to change the name property of your Application.cfc template. So open the file Application.cfc and change the this.name property to whatever you want it to be. Remember that every application will need its own name property. Also, please note that ColdBox uses the session scope for some plugins and the application scope for the framework. So alter accordingly to what you need to do in your application, this is YOUR JOB. ''See [[SystemRequirements]]'' Open the provided event handler(s) in the template folder: '''main.cfc and general.cfc''' and modify them if you need to. I recommend you leave them as they are in order for you to see that the skeleton works. Now that you have completed editing your configuration file, Application.cfc and your first event handler, you are ready to see results. Point your browser to your application folder and you will see a screen similar to the one below:
== What Happened? == Well, before I actually go in and explain the code, you will have to do some reading first. This is necessary in order for you to understand what ColdBox is doing and how it is doing it. So read the following sections below if you would like to, if not continue in the next section: * [[ColdBox | ColdBox Overview]] : It will show you a top-down view of what ColdBox is. * [[RequestLifecycles | ColdBox Request LifeCycle]] : What happens in a request * [[DirectoryStructure-Conventions | Directory Structure & Conventions]] : How a ColdBox application is structured (More by convention than configuration) * [[ConfigurationFile]] : Understand how to configure your application with the implicit event model and application aspects. * [[EventHandlers | Event Handlers Guide]] : This is SUPER necessary in order to understand how to code in ColdBox * [[RequestContext | Request Context Guide]] : How data moves in a request and how to access it. === Step 1: Configuring the Application === Below you can see the coldbox.xml that the application runs on, for more in depth detail please look at the [[ConfigurationFile | Config Guide]] since the example below does not have all the elements an application can use. true 10 50 Layout.Main.cfm 60 30 true 1 100 0 LRU config/environments.xml.cfm true config/routes.cfm Basically, there are a lot of configurations you can do for your application like adding datasources, internationalization, IoC (Coldspring|Lightwire) support etc. For this application we only care about a few configurations: * '''AppName''' : The name of your application. * '''DebugMode''' : To show or not the debugging panel (set to true in development) * '''DebugPassword''' : Set to blank for dev use (please remember to fill one up) * '''ReinitPassword''' : Set to blank for dev use (please remember to fill one up) * '''EnableColdboxLogging''' : Enables AOP logging for exceptions and information messages. (set to true) * '''ColdBoxLogsLocation''' : Default location of the log files '''logs''' within your application * '''DefaultEvent''' : The event to fire when application starts up or there is no event defined. (set to ehGeneral.dspHello) * '''RequestStartHandler'''' : The event to fire at the beginning of every request. (set to ehMain.onRequestStart) * '''RequestEndHandler''' : The event to fire at the end of every request. (set to ehMain.onRequestEnd) * '''ApplicationStartHandler''' : The event to fire when application starts up. (set to ehMain.onAppInit) * '''ConfigAutoReload''' : To reload the configuration file and reinit the app(set to true, development only) * '''HandlerCaching''' : To cache the event handler cfc's in the ColdBox cache. (set to false) You do not want to enable this in development unless you are doing load tests. If not, you won't see changes reflected until you refresh the cache. * '''DefaultLayout''' : The default layout to use for rendering views. * The ses interceptor for pretty URL's. === Step 2: Understanding the Life Cycle === Now that we know how our application will start up and what events to fire we can understand the following life cycle. See [[RequestLifecycles | Application Life Cycle]]. === Step 3: The Handler Code === The application start, on request start and on request end handlers have no code in them. This is on purpose, so you can fill it up with whatever you want. The only meat for the created application resides on the '''general''' handler cfc and on the '''index''' method. Our convention is to have a handler called '''main''' or '''implicit''' and place all implicit events there. Below you can see the full '''general''' handler code: ---> You can see that we have divided it into several sections: * Dependencies : Where cfproperty dependencies go. (See [[Interceptors:Autowire | Autowire Guide]]) * Implicit Events : Some local interception points and local handler implicit executions * Public Events : Methods (actions) that are registered as public/remote access are considered public ColdBox Responding events. * Private Events : Methods (actions) that can only be called from within the framework Before I go into the code for this sample, you might be asking yourself why two cfc's for this. Well, remember that controllers are objects also. Don't try to have only one controller doing everything for you, that is plain old BAAAD!! You need to analyze your application and figure out logical [http://en.wikipedia.org/wiki/Ontology ontologies] for your handlers. What is [http://en.wikipedia.org/wiki/Ontology Ontology]?
Ontology is the study of being or existence. How this controller exists and why. What events and actions will be described by this handler.
These are all principles that you will need to understand before hand, in order to layout a good event model for your application. In this case, the model is simple. We have two distinct handlers, one for taking care of our implicit events such as onRequestStart and onRequestEnd, and a General handler that will say hello to you. As your applications become more complex and they need more functionality, you will come to start using handler packages. This means, that you will group your handlers into directories. A great example is if you are building a website with a forum and a blog application. You can then package your handlers into a blog directory, a forum directory and a site directory. The possibilities are endless. You can continue to add functionality to your applications without the need of configurations or xml for them. Back to our example. Below is the simple '''index''' method. To figure out the anatomy of an event (method), please look at the [[EventHandlers | Event Handlers Guide]]. First of all, you need to understand that the framework will create an event object for you that handles (simulates) and entire server request. Inside of this object you have a '''request collection''' which is a data structure that you use to set/get values for use in your application. All the FORM and URL variables get appended to this collection at the beginning of a request. It also contains more variables that you and the framework set for execution. This is a very handy object that gets passed around from the beginning of a request to the end of a request. Now that you understand that this event object simulates your incoming variables and more we can continue to analyze the code. ''See [http://www.coldbox.org/api Live API], [[RequestContext | Request Context Guide]]'' What this method does is first set a value into the event object (request collection) named '''welcomeMessage''' with a message. This basically sets a key into the request collection structure with the value you set. Then we proceed to tell the event object to set a view to render called '''vwHello''' by using the '''setView''' method. This creates a special variable key in the request collection that the framework will pick up later during the request process and render the set view. Below is what the method actually takes in as parameters. '''setView'''(string name, [boolean nolayout], [boolean cache], [string cacheTimeout], [string cacheLastAccessTimeout]) {| cellpadding=?5?, class="tablelisting" ! '''Argument''' !! '''Description''' |- || '''name''' || The name of the view to render |- || '''noLayout''' || Boolean flag that tells the framework to render the view with no layout |- || '''cache''' || Boolean flag that tells the framework to also cache this view after rendering |- || '''cacheTimeout''' || In minutes, tells the framework to cache the view. |- || '''cacheLastAccessTimeout''' || In minutes, tells the framework if view not used in X amount, then purge |} Ok, man, this stuff is really vague. I tell an object what view to render, then I don't specify a location or even an extension? What is this? Is this magic? Well, the reality is that IT IS MAGIC!! Remember that ColdBox has conventions that make it easy for the framework to find what it needs. That is why you have a '''handlers''' directory where you place your event handlers, a '''config''' directory where you place your coldbox.xml file or any other configuration files, '''layouts''' directory to keep layouts and a '''views''' directory where you will place your views. That is why you set the '''vwHello''' view, the framework will find it in the '''views''' directory as '''vwHello.cfm'''. Please read the [[DirectoryStructure-Conventions | Directory Layout & Conventions Guide]].
'''Note:''' When setting views, do not append the .cfm extension. The framework does it for you.
So in summary, this handler does the following: * Sets a variable in the request collection via the event object * Sets in the request collection the view to render. Once this method gets executed by the framework, the internal sequence of the framework will then continue to render the specified template. === Step 4: Layout/View combination === Now, how in the world, does my view get rendered. Well, ColdBox provides you with a very simple but flexible and powerful layout manager and renderer. The basic principles of rendering views in ColdBox is that in your coldbox.xml you declare a !DefaultLayout variable that points to the actual name of the template to use as your layout or container for views to be rendered in. Look below at the sample snippet from the configuration file: Layout.Main.cfm vwTest vwMyView As you can see from the snippet above, the default layout is called '''Layout.Main.cfm'''. This is a mandatory setting for your application configuration. The other xml elements below is where you can declare implicit renderings of views. In human terms, this is to implicitly determine in which layout to render the specified view(s) without actually telling the framework at runtime. In this sample a '''Popup''' layout is declared and two views with it: '''vwTest and vwMyView'''. This means, that those two views will be rendered inside of the Popup layout unless you specifically override them via the API.
'''Note:''' ColdBox 2.5.0 and greater allows you to have folder layout inheritance. You can declare a '''Folder''' element.
The layout source code is shown below: Welcome to Coldbox!! #renderView()# This is a very simple layout. You declare a simple html template and in between the body tags is where I will render my views. This is of course very simplistic. Once you get into AJAX interaction you can render views with no layouts, remove debugging, etc. For this simple example, just note that the method '''renderView()''' gets executed. One good thing to know here is that all layouts and views get rendered in their own context inside of the '''renderer''' plugin (see [http://www.coldbox.org/api Live API] ) This is why you can call the method directly and not use the full call '''getPlugin("renderer").renderView()''' which you can still use. Now to the view. Below is the source:

#Event.getValue("welcomeMessage")#

You are now running '''#getSetting("codename",1)# #getSetting("version",1)# (#getsetting("suffix",1)#)'''. Welcome to the next generation of ColdFusion applications. You can now start building your application with ease, we already did the hard work for you.

Getting Started

You have just auto-generated your application and are ready to customize your application. Several directories and files have been created for you. Please familiarize yourself with your application layout before customizing your application.

Good Starting Links

  1. Directory Structure & Conventions
  2. Coldbox.xml Guide
  3. Event Handler's Guide
  4. Request Context's Guide
  5. Layouts & Views Guide
  6. My First ColdBox App
* Wiki Docs

ColdBox URL Actions

ColdBox can use some very important URL actions to interact with your application. You can try them out below:

  1. Reinitialize the framework (fwreinit=1)
  2. Remove Debug Mode (debugmode=false)
  3. Enable Debug Mode (debugmode=true)
* URL Actions Guide

Customizing your Application

You can now start editing your application and building great ColdBox enabled apps. Important files & locations:

  1. /config/coldbox.xml.cfm: Your application configuration file
  2. /config/environments.xml.cfm: Your per-tier settings
  3. /config/routes.cfm: Your SES routing table
  4. /handlers: Your Application controllers
  5. /includes: Assets, Helpers, i18n, templates and more.
  6. /includes/helpers: Place all your application and specific helpers here
  7. /layouts: Where you place all your application layouts
  8. /logs: The ColdBox Logs directory
  9. /model: The meat of your app, your business logic objects
  10. /plugins: Where you place custom plugins built by you!
  11. /test: Your unit testing folder (Just DO IT!!)
  12. /views: Where you create all your views and viewlets

It basically just does a cfoutput and outputs some content. The first output is the '''welcomeMessage''' we set in the handler. The second message is actually outputting some framework settings. See [[ColdboxSettings | Settings Guide]] to learn to interact with the framework settings. That line gets the current codename, version and suffix of your running framework installation. One thing you will notice is that I also output the same welcome message without actually using the event object but the '''rc''' scope. Please see the note below.
'''Note:''' All layouts and views have access to the '''rc''' scope. This scope is a reference to the current request collection structure. This way it is easier to access variables without going to the event object.
== Conclusion == Now get your mind out of procedural code, dive into OO Programming. Please make sure to fasten your seat belts, it WILL GET BUMPY! == Related Guides == * [[DirectoryStructure-Conventions | Application Directory Structure & Conventions]] * [[ColdboxSettings | ColdBox Configuration Settings]] * [[ReservedWordsAndMethods | Reserved Words & Methods]] * [[URLActions | ColdBox URL Actions]]