-
Notifications
You must be signed in to change notification settings - Fork 6
Introduction
After you've downloaded ColdMVC, there are three simple ways you can install the framework.
- Create a /coldmvc mapping inside ColdFusion Administrator that points to the framework.
- Put the framework directly inside your server's web root.
- Put the framework directly inside your application's root.
Pretty simple, right?
You can define configuration variables for your application inside an [INI file] [1] located at /config/config.ini. Each section represents a different environment for your application, with the exception of the default environment, which all other environments inherit settings from.
A typical config.ini file for a blogging application might look like the following:
[default]
controller=blog
sesURLs=true
[development]
development=true
autoReload=true
[production]
reloadPassword=mySecretPassword
Now let's describe the various parts of this parts of this file.
Inside the default environment, we define the name of our application's default controller. In this case, we've set the value to blog. If we were to make a request to our application without specifying a controller, our application will route the request to the BlogController by default.
We also set a sesURLs property to true. This tells our application not to include index.cfm on any URLs generated by the linkTo or redirect methods. Note: if you enable the sesURLs config setting, it is up to you to provide the necessary URL rewriting logic inside an .htaccess file or web.config file, depending on which web server you're using.
By setting development to true, we enable a couple convenience options in our application for working in development mode. First, your application's views, layouts, and tags are re-generated each
request, allowing you to see your changes immediately. Second, various internal component caches are cleared each request, such as caches for custom event listeners. Finally, debug information will be append to the bottom of your view, providing you with access to key information for your request.
Next, we set a autoReload setting to true, meaning the application will be automatically reloaded each request. This is very helpful when in development in order to automatically reload your singleton components.
In the production environment, we set a variable called reloadPassword to mySecretPassword. The reloadPassword is used when reloading your application through the URL. Be default, you can reload your application simply by adding an init variable to your URL without specify a password. By setting the reloadPassword to mySecretPassword, you can only reload your application by adding init=mySecretPassword to your URL. If you would like to change the init variable to something else, simply add a config setting for reloadKey inside your config.ini file with the value of your choice.
Your config settings are available to your application in a couple ways.
First, you can access any config setting by using the config helper.
var value = $.config.get("key");
Second, you can inject the config bean into your components.
component accessors="true" singleton="true" {
property config;
function sendEmail() {
if (config.get("allowEmails")) {
// do stuff
}
}
}
Third, you can inject your config settings directly into your singleton beans inside by using the the ${key} syntax inside your /config/coldspring.xml file.
<bean id="emailService" class="app.model.EmailService">
<property name="allowEmails">
<value>${allowEmails}</value>
</property>
</bean>
Finally, you can inject your config settings into your singleton beans simply by naming your keys using a {bean}.{method} syntax. For example, by specifying a config setting of emailService.allowEmails=true, the bean factory will automatically call the setAllowEmails method on the emailService bean and pass in a value of true when the bean is first constructed.
You can pass complex values into your beans by using [JSON] [2] syntax for the value of your config setting. The bean factory will automatically convert the JSON string into a complex object before injecting
the property into the component. The following example will inject an array into the setBar method on the fooService singleton bean.
fooService.bar=["boo", "baz"]
ColdMVC follows the Model-View-Controller design pattern. In this type of application, incoming requests are handled by a controller, which retrieves data from the model, and optionally renders a view.
If you're looking for a better description of MVC, there are plenty of online articles written on the topic.
Since ColdMVC is a convention-based framework, it's important that applications follow a similar directory structure in order to take advantage of the framework's conventions. A typical ColdMVC directory structure looks like the following:
app/
controllers/
LayoutController.cfc
helpers/
layouts/
index.cfm
model/
tags/
views/
config/
coldspring.xml
config.ini
environment.txt
hibernate.hbmxml
plugins.cfm
routes.cfm
public/
css/
images/
js/
index.cfm
Application.cfc
Here's a brief description of the various files and folders.
/app/ - Contains the majority of your ColdMVC application (.cfm and .cfc files).
/app/controllers/ - Contains your controllers.
/app/controllers/LayoutController.cfc - Handles putting data into layouts.
/app/helpers/ - Contains your helpers.
/app/layouts/ - Contains your layouts.
/app/layouts/index.cfm - The default layout.
/app/model/ - Your domain model. Contains any persistent entities and services.
/app/tags/ - Contains your custom tags.
/app/views/ - Contains your views.
/config/ - Contains your configuration files.
/config/coldspring.xml - Contains any custom ColdSpring bean definitions.
/config/config.ini - Contains your configuration settings.
/config/environment.txt - Contains the name of your current environment, which is used to determine your settings.
/config/hibernate.hbmxml - Contains your Hibernate mappings.
/config/plugins.cfm - Defines any plugins used by your application.
/config/routes.cfm - Defines any custom routes for your application.
/public/ - Your application's web root.
/public/css/ - Contains any CSS files.
/public/images/ - Contains any images.
/public/js/ - Contains any JavaScript files.
/public/index.cfm - Your application's front-controller index page. All requests are routed through this file.
Application.cfc - Your project's application page. Typically just extends coldmvc.Application.
You can very easily create singleton components and inject them into other components without much hassle.
To create a singleton component, simply add an @singleton annotation to the component.
When ColdMVC first loads, it will scan your application and any registered plugins to find components that have been marked as singletons. ColdMVC will then add the components to its bean factory, which then manages the dependencies between the objects.
If you want more a granular level of control over dependency injection, you can create a configuration file located at /config/beans.xml and ColdMVC will use the bean definitions within the configuration file to manage your dependencies.
ColdMVC allows you to create helper components that are available to your entire application. These helper components are good for containing useful methods similar to those found on cflib.org.
When ColdMVC first loads, it will load any helpers located within your application's /app/helpers/ folder, then any helpers inside /coldmvc/app/helpers/ folder that haven't been loaded yet. These helpers will then be available throughout your application inside the $ and coldmvc variables.
ColdMVC ships with a handful of helpers that can be found inside /coldmvc/app/helpers/. If you would like to override the functionality of one of ColdMVC's helpers, simply create a .cfc with the same name inside your application's /app/helpers/ directory, extend the corresponding ColdMVC helper, and make your changes.
You can create your own helpers by creating a .cfc and placing it inside your application's /app/helpers/ folder. For example, if you created a file located at /app/helpers/tony.cfc, you would then have access to that helper throughout your application by using $.tony or coldmvc.tony.
- array
- asset
- bind
- config
- data
- date
- factory
- form
- format
- framework
- html
- link
- list
- page
- query
- querystring
- request
- string
- struct
- url
- user
- valid
- xml