-
Notifications
You must be signed in to change notification settings - Fork 141
Developing Applications Manual
This documentation covers FW/1 2.5 (and earlier, to some extent). See the FW/1 3.0 Documentation for the latest Developing Applications Manual (for release 3.0).
FW/1 is intended to allow you to quickly build applications with the minimum of overhead and interference from the framework itself. The convention-based approach means that you can quickly put together an outline of your site or application merely by creating folders and files in the views folder. As you are ready to start adding business logic to the application, you can add controllers and/or services as needed to implement the validation and data processing.
FW/1 applications must have an Application.cfc that extends org.corfield.framework (will be framework.one in 3.0) and an empty index.cfm as well as at least one view (under the views folder). Typical applications will also have folders for controllers, services and layouts. The folders may be in the same directory as Application.cfc / index.cfm or may be in a directory accessible via a mapping (or some other path under the webroot). If the folders are not in the same directory as Application.cfc / index.cfm, then variables.framework.base must be set in Application.cfc to identify the location of those folders.
Note: because Application.cfc must extend the FW/1 framework.cfc, you need a mapping in the CF Administrator. An alternative approach is to simply copy framework.cfc to your application’s folder (containing Application.cfc and index.cfm) and then have Application.cfc extend framework instead. This requires no mapping – but means that you have multiple copies of the framework instead of a single, central copy.
The views folder contains a subfolder for each section of the site, each section’s subfolder containing individual view files (pages or page fragments) used within that section. All view folders and filenames must be all lowercase.
The layouts folder may contain general layouts for each section and/or a default layout for the entire site. The layouts folder may also contain subfolders for sections within the site, which in turn contain layouts for specific views. All layout folders and filenames must be all lowercase.
The controllers folder contains a CFC for each section of the site (that needs a controller!). Each CFC contains a method for each requested item in that section (where control logic is needed). Controller CFC filenames must be all lowercase.
You would typically also have a model folder containing CFCs for your services and your domain objects – the business logic of your application. Prior to Release 2.5, you would have had a service folder for service CFCs but there would have no consistent structure for the rest of your business logic.
An application may have additional web-accessible assets such as CSS, images and so on.
Views and layouts are simple CFML pages. Both views and layouts are passed a variable called rc which is the request context (containing the URL and form variables merged together). Layouts are also passed a variable called body which is the current rendered view. Both views and layouts have direct access to the full FW/1 API (see below).
The general principle behind views and layouts in FW/1 is that each request will yield a unique page that contains a core view, optionally wrapped in a section-specific layout, wrapped in a general layout for the site. In fact, layouts are more flexible than that, allowing for item-specific layouts as well as section-specific layouts. See below for more detail about layouts.
Both views and layouts may invoke other views by name, using the view() method in the FW/1 API. For example, the home page of a site might be a portal style view that aggregates the company mission with the latest news. views/home/default.cfm might therefore look like this:
<cfoutput>
<div>#view('company/mission')#</div>
<div>#view('news/list')#</div>
</cfoutput>
This would render the company.mission view and the news.list view.
Note: The view() method behaves like a smart include, automatically handling subsystems and providing a local scope that is private to each view, as well as the rc request context variable (through which views can communicate, if necessary). No controllers are executed as part of a view() call. As of 1.2, additional data may be passed to the view() method in an optional second argument, as elements of a struct that is added to the local scope.
As hinted at above, layouts may nest, with a view-specific layout, a section-specific layout and a site-wide layout. When FW/1 is asked for section.item, it looks for layouts in the following places:
- layouts/section/item.cfm – The view-specific layout
- layouts/section.cfm – The section-specific layout
- layouts/default.cfm – The site-wide layout
For a given item up to three layouts may be found and executed, so the view may be wrapped in a view-specific layout, which may be wrapped in a section-specific layout, which may be wrapped in a site-wide layout. To stop the cascade, set request.layout = false; in your view-specific (or section-specific) layout. This allows for full control in authoring section and/or page specific layouts which may be very different from your site-wide layout.
This approach also allows you to have a view which returns plain XML or JSON, by using a view-specific layout that looks like this:
<cfoutput>#body#</cfoutput> <cfset request.layout = false>
(although you’d probably want to set the content type header to ensure XML was handled correctly!).
By default, FW/1 selects views (and layouts) based on the action initiated, subsystem:section.item but that can be overridden in a controller by calling the setView() and setLayout() methods to specify a new action to use for the view and layout lookup respectively. setLayout() is new in 2.0. This can be useful when several actions need to result in the same view, such as redisplaying a form when errors are present.
The view and layout CFML pages are actually executed by being included directly into the framework CFC. That’s how the view() method is made available to them. In fact, all methods in the framework CFC are directly available inside views and layouts so you can access the bean factory (if present), execute layouts and so on. It also means you need to be a little bit careful about unscoped variables inside views and layouts: a struct called local is available for you to use inside views and layouts for temporary data, such as loop variables and so on.
It would be hard to give a comprehensive list of variables available inside a view or layout but here are the important ones:
- path – The path of the view or layout being invoked. For a given view (or layout), it will always be the same so I can’t imagine this being very useful. Strictly speaking, this is arguments.path, the value passed into the view() or layout() method.
- body – The generated output passed into a layout that the layout should wrap up. Strictly speaking, this is arguments.body, the value passed into the layout() method.
- rc – A shorthand for the request context (the request.context struct). If you write to the rc struct, layouts will be able to read those values so this can be a useful way to set a page title, for example (set in the view, rendered in the layout where appears).
- local – An empty struct, created as a local scope for the view or layout.
- framework – The FW/1 configuration structure (variables.framework in the framework CFC) which includes a number of useful values including framework.action, the name of the URL parameter that holds the action (if you’re building links, you should use the buildURL() API method which knows how to handle subsystems as well as regular section and item values in the action value). You can also write SES URLs without this variable, e.g., /index.cfm/section/item as long as your application server supports such URLs.
In addition, FW/1 uses a number of request scope variables to pass data between its various methods so it is advisable not to write to the request scope inside a view or layout. See the ReferenceManual for complete details of request scope variables used by FW/1.
It is strongly recommended to use the local struct for any variables you need to create yourself in a view or layout!
If you have data that is needed by all of your views, it may be convenient to set that up in your setupView() method in Application.cfc – see Taking Actions on Every Request below. Added in 2.0.
Prior to 2.2, if you wanted to create an API that returned JSON or XML to a caller, you had to format data in a special view and set the content type correctly and suppressed layouts and so on. It was possible, but ugly.
As of 2.2, you can use the renderData() framework API to bypass views and layouts completely and automatically return JSON, XML, or plain text to your caller, with the correct content type automatically set. See below for more details.
Controllers are the pounding heart of an MVC application and FW/1 provides quite a bit of flexibility in this area. The most basic convention is that when FW/1 is asked for section.item it will look for controllers/section.cfc and attempt to call the item() method on it, passing in the request context as a single argument called rc and controllers may call into the application model as needed, then render a view.
Controllers are cached in FW/1’s application cache so controller methods need to be written with thread safety in mind (i.e., use var to declare variables properly!). If you are using a bean factory, any setXxx() methods on a controller CFC may be used by FW/1 to autowire beans from the factory into the controller when it is created. Release 2.0 supports property-based autowiring as well as explicit setters. Alternatively, you can let the bean factory take care of the controller CFC’s lifecycle completely: just name the bean with a suffix of Controller and when FW/1 is asked for section.item it will ask the bean factory for sectionController . See the note about Controllers and the FW/1 API below for a caveat on this.
In addition, if you need certain actions to take place before all items in a particular section, you can define a before() method in your controller and FW/1 will automatically call it for you, before calling the item() method. This might be a good place to put a security check, to ensure a user is logged in before they can execute other actions in that section. The variable request.item contains the name of the controller method that will be called, in case you need to have exceptions on the security check (such as for a main.doLogin action that attempts to log a user in).
Similarly, if you need certain actions to take place after all items in a particular section, you can define an after() method in your controller and FW/1 will automatically call it for you, after calling the item() method and after invoking any service method.
Note that your Application.cfc is also viewed as a controller and if it defines before() and after() methods, those are called as part of the lifecycle, around any regular controller methods. Unlike other controllers, it does not need an init() method and instead of referring to the FW/1 API methods via variables.fw… you can just use the API methods directly – unqualified – since Application.cfc extends the framework and all those methods are available implicitly. Added in 2.0.
Here is the full list of methods called automatically when FW/1 is asked for section.item :
- Application.cfc : before()
- controllers/section.cfc : before()
- Deprecated: controllers/section.cfc : startItem()
- controllers/section.cfc : item()
- Deprecated: (any service calls that were queued via the service() API call)
- Deprecated: controllers/section.cfc : endItem()
- controllers/section.cfc : after()
- Application.cfc : after()
Methods that do not exist are not called. Application.cfc methods were not called in FW/1 1.×.
FW/1 supports onMissingMethod(), i.e., if a desired method is not present but onMissingMethod() is declared, FW/1 will call the method anyway. That applies to all five potential controller methods: before, startItem , item , endItem and after. As of Release 2.5, startItem and endItem are deprecated and will not be called by default (unless you set suppressServiceQueue false). That means you must be a little careful if you implement onMissingMethod() since it will be called whenever FW/1 needs a method that isn’t already defined. If you are going to use onMissingMethod(), I would recommend always defining before and after methods, even if they are empty; and if you are still using start and end items, be extra careful! As of 2.1, onMissingMethod() calls will receive two arguments in missingMethodArguments: rc (as in earlier versions) and method which is the type of the method being invoked (“before”, “start”, “item”,“end”, “after”).
FW/1 provides a default onMissingView() method for Application.cfc that throws an exception (view not found). This allows you to provide your own handler for when a view is not present for a specific request. The most common usage for this is likely to be for Ajax requests, to return a JSON-encoded data value without needing an explicit view to be present. Other use cases are possible since whatever onMissingView() returns is used as the core view and, unless layouts are disabled, it will be wrapped in layouts and then displayed to the user.
Be aware that onMissingView() will be called if your application throws an exception and you have not provided a view for the default error handler (main.error – if your defaultSection is main). This can lead to exceptions being masked and instead appearing as if you have a missing view!
FW/1 provides direct support for handling a specific request’s lifecycle based on an action (either supplied explicitly or implicitly) but relies on your Application.cfc for general lifecycle events. That’s why FW/1 expects you to write per-request logic in setupRequest(), per-session logic in setupSession() and application initialization logic in setupApplication(). FW/1 2.0 adds setupView() which is called just before view rendering begins to allow you to set up data for your views that needs to be globally available, but may depend on the results of running controllers or services.
If you have some logic that is meant to be run on every request, the FW/1 way to implement this is to implement setupRequest() in your Application.cfc and have it retrieve the desired controller by name and run the appropriate event method, like this:
function setupRequest() {
controller( 'security.checkAuthorization' );
}
This queues up a call to that controller at the start of the request processing, calling before(),checkAuthorization() and after() as appropriate, if those methods are present.
Note that the request context itself is not available at this point! setupRequest() is to set things up prior to the request being processed. If you need access to rc, you will want to implement before() in your Application.cfc which is a regular controller method that is called before any others (including before() in other controllers which get queued up):
function before( struct rc ) {
// set up your RC values
}
If you need to perform some actions after controllers and services have completed but before any views are rendered, you can implement setupView() in your Application.cfc and FW/1 will call it after setting up the view and layout queue but before any rendering takes place:
function setupView( struct rc ) {
// pre-rendering logic
}
You cannot call controllers here – this lifecycle method is intended for common data setup that is needed by most (or all) of your views and layouts. If services from your model have been autowired into Application.cfc, you can call those. Added in FW/1 2.0. Release 2.5 added the rc argument. Prior to 2.5, you had access to rc in variables scope inside this method but you’d have been safer to use request.context explicitly.
Finally, there is a lifecycle method that FW/1 calls at the end of every request – including redirects – where you can implement setupResponse() in your Application.cfc:
function setupResponse( struct rc ) {
// end of request processing
}
This is called after all views and layouts have been rendered in a regular request or immediately before the redirect actually occurs when redirect() has been called. You cannot call controllers here. If services from your model have been autowired into Application.cfc, you can call those. Added in FW/1 2.0. Release 2.5 added the rc argument. Prior to 2.5, you had access to rc in variables scope inside this method but you’d have been safer to use request.context explicitly.
If you need to immediately halt execution of a controller and prevent any further controllers or services from being called, use the abortController() method. See the Reference Manual for more details of abortController(), in particular how it interacts with exception-handling code in your controllers. Added in 2.0.
As of 2.2, you can return data directly, bypassing views and layouts, using the new renderData() function.
variables.fw.renderData( contentType, resultData );
Calling this function does not exit from your controller, but tells FW/1 that instead of looking for a view to render, the resultData value should be converted to the specified contentType and that should be the result of the complete HTTP request.
contentType may be “json”, “xml”, or “text”. The Content-Type HTTP header is automatically set to:
- application/json; charset=utf-8
- text/xml; charset=utf-8
- text/plain; charset=utf-8
respectively. For JSON, the resultData value is converted to a string by calling serializeJSON(); for XML, the resultData value is expected to be either a valid XML string or an XML object (constructed via CFML’s various xml…() functions); for plain text, the resultData value must be a string.
You can also specify an HTTP status code as a third argument. The default is 200.
When you use renderData(), no matching view is required for the action being executed.
Services – and domain objects – should encapsulate all of the business logic in your application. Where possible, most of the application logic should be in the domain objects, making them smart objects, and services can take care of orchestrating work that reaches across multiple domain objects.
Controllers should call methods on domain objects and services to do all the heavylifting in your application, passing specific elements of the request context as arguments. FW/1’s populate() API is designed to allow you to store arbitrary elements of the request context in domain objects.
If you’re using a bean factory (recommended – and covered in the next section), your services can be autowired into your controllers, making it easier to call them directly, without having to worry about how and where to construct those CFCs. Bean factories can also be used to manage your domain objects, autowiring services into them as necessary, so your controllers can simply ask the bean factory for a new domain object, populate() it from the request context, call methods on the domain object, or pass them to services as necessary.
Services should not know anything about the framework. Service methods should not “reach out” into the request scope to interact with FW/1 – or any other scopes! – they should simply have some declared arguments, perform some operation and return some data.
There are many ways to organize how you save and load data. You could use the ORM that comes with ColdFusion or Railo, you could write your own data mapping service, you could write custom SQL for every domain object. Regardless of how you choose to handle your persistence, encapsulating it in a service CFC is probably a good idea. For convenience it is often worth injecting your persistence service into your domain object so you can have a convenient domainObject.save() method to use from your controller, even if it just delegates to the persistence service internally:
function save() {
variables.dataService.save( this );
}
The convention introduced in FW/1 1.x to invoke service methods was intended to reduce the number of controller methods that simply delegate to a service method and store the result in the request context. The default service method was invoked as if you had written:
request.context.data = section.item( argumentCollection=request.context );
In other words, any declared arguments on the service method were matched against values passed in through the URL or form scope, and the result of the call placed in the data element of the request context for use by the view in that request.Service method calls queued up by the controller placed their results in the designated elements of the request context.
FW/1 expected to find service CFCs in the services folder and when it created them, it invoked their init() method, if present, passing no arguments, and then cached the service instance in application scope, just as controllers were cached. That meant that service methods needed to be written with thread safety in mind.
If you used a bean factory but let FW/1 create and manage service CFCs, any setXxx() methods on a service CFC could be used by FW/1 to autowire beans from the factory into the service when it is created. _Release 2.0 added support for property-based autowiring as well as explicit setters. _Alternatively, you could let the bean factory take care of the service CFC’s lifecycle completely: just name the bean with a suffix of Service and when FW/1 is asked for section.item, it will ask the bean factory for sectionService.
The implicit management of services and queuing up of their method calls was deprecated in Release 2.5 and will be removed in 3.0. The recommended approach has always been to use a bean factory to manage services and autowiring.
FW/1 supports your favorite bean factory (aka IoC container or DI factory). As long as you have a CFC that supports the following API, FW/1 will accept it as a bean factory:
- boolean containsBean(string name) – returns true if the factory knows of the named bean
- any getBean(string name) – returns a fully initialized bean identified by name
Telling FW/1 about your bean factory is as simple as calling setBeanFactory(myFactory) inside your Application.cfc’s setupApplication() method. The following example uses DI/1:
var bf = new framework.ioc('/controllers,/model');
setBeanFactory(bf);
or WireBox:
var bf = new framework.WireBoxAdapter();
bf.getBinder().scanLocations('/controllers,/model');
setBeanFactory(bf);
or ColdSpring:
var bf = createObject('component','coldspring.beans.DefaultXmlBeanFactory').init();
bf.loadBeans( expandPath('config/coldspring.xml') );
setBeanFactory(bf);
Note: If you are using subsystems, please read UsingSubsystems for details about setting up bean factories for subsystems.
When you tell FW/1 to use a bean factory, it does several things behind the scenes:
- If the factory knows about a sectionController bean, FW/1 will use that instead of controllers/section.cfc
- Else FW/1 will create an instance of controllers/section.cfc and attempt to call any setters that match beans from the factory (autowiring beans into the controller)
The FW/1 API includes the following methods related to bean factory support:
- hasBeanFactory() – returns true if FW/1 knows about a bean factory
- getBeanFactory() – returns the bean factory you told FW/1 about
Since an application should know whether it is designed to use a bean factory, it is expected that only the latter method will actually be used and even then only rarely (since controllers and services are autowired and views should not need beans to do their work).
By default, if an exception occurs, FW/1 will attempt to run the main.error action (as if you had asked for ?action=main.error), assuming your defaultSection is main. If you change the defaultSection, that implicitly changes the default error handler to be the error item in that section. The exception thrown is stored directly in the request scope as request.exception. If FW/1 was processing an action when the exception occurred, the name of that action is available as request.failedAction. The default error handling action can be overridden in your Application.cfc by specifying variables.framework.error to be the name of the action to invoke when an exception occurs.
If the specified error handler does not exist or another exception occurs during execution of the error handler, FW/1 provides a very basic fallback error handler that simply displays the exception. If you want to change this behavior, you can either override the failure() method or the onError() method but I don’t intend to “support” that so the only documentation will be in the code!
Note: If you override onMissingView() and forget to define a view for the error handler, FW/1 will call onMissingView() and that will hide the original exception.
All of the configuration for FW/1 is done through a simple structure in Application.cfc. The default behavior for the application is as if you specified this structure:
variables.framework = {
action = 'action',
usingSubsystems = false,
defaultSubsystem = 'home',
defaultSection = 'main',
defaultItem = 'default',
subsystemDelimiter = ':',
siteWideLayoutSubsystem = 'common',
home = 'main.default', // defaultSection & '.' & defaultItem
// or: defaultSubsystem & subsystemDelimiter & defaultSection & '.' & defaultItem
error = 'main.error', // defaultSection & '.error'
// or: defaultSubsystem & subsystemDelimiter & defaultSection & '.error'
reload = 'reload',
password = 'true',
reloadApplicationOnEveryRequest = false,
generateSES = false,
SESOmitIndex = false,
// base = omitted so that the framework calculates a sensible default
baseURL = 'useCgiScriptName',
// cfcbase = omitted so that the framework calculates a sensible default
suppressImplicitService = true, // this used to be false in FW/1 1.x
suppressServiceQueue = true, // false restores the FW/1 2.2 behavior
enableGlobalRC = false, // true restores the FW/1 2.2 behavior
unhandledExtensions = 'cfc',
unhandledPaths = '/flex2gateway',
unhandledErrorCaught = false,
preserveKeyURLKey = 'fw1pk',
maxNumContextsPreserved = 10,
cacheFileExists = false,
applicationKey = 'org.corfield.framework', // will be 'framework.one' in 3.0
trace = false
};
The keys in the structure have the following meanings:
- action – The URL or form variable used to specify the desired action (section.item).
- usingSubsystems – Whether or not to use subsystems – see Using Subsystems below.
- defaultSubsystem – If subsystems are enabled, this is the default subsystem when no action is specified in the URL or form post.
- defaultSection – If subsystems are enabled, this is the default section within a subsystem when either no action is specified at all or just the subsystem is specified in the action. If subsystems are not enabled, this is the default section when no action is specified in the URL or form post.
- defaultItem – The default item within a section when either no action is specified at all or just the section is specified in the action.
- subsystemDelimiter – When subsystems are enabled, this specifies the delimiter between the subsystem name and the action in a URL or form post.
- siteWideLayoutSubsystem – When subsystems are enabled, this specifies the subsystem that is used for the (optional) site-wide default layout.
- home – The default action when it is not specified in the URL or form post. By default, this is defaultSection.defaultItem. If you specify home, you are overriding (and hiding) defaultSection but not defaultItem. If usingSubsystem is true, the default for home is “home:main.default”, i.e., defaultSubsystem & subsystemDelimiter & defaultSection & ‘.’ & defaultItem.
- error – The action to use if an exception occurs. By default this is defaultSection.error.
- reload – The URL variable used to force FW/1 to reload its application cache and re-execute setupApplication().
- password – The value of the reload URL variable that must be specified, e.g., ?reload=true is the default but you could specify reload = ‘refresh’, password = ‘fw1’ and then specifying ?refresh=fw1 would cause a reload.
- reloadApplicationOnEveryRequest – If this is set to true then FW/1 behaves as if you specified the reload URL variable on every request, i.e., at the start of each request, the controller/service cache is cleared and setupApplication() is executed.
- generateSES – If true, causes redirect() and buildURL() to generate SES-style URLs with items separated by / (and the path info in the URL will begin /section/item rather than ?action=section.item – see the Reference Manual for more details).
- SESOmitIndex – If SES URLs are enabled and this is true, will attempt to omit the base filename in the path when constructing URLs in buildURL() and redirect() which will generally omit /index.cfm from the start of the URL. Again, see the Reference Manual for more details.
- base – Provide this if the application itself is not in the same directory as Application.cfc and index.cfm. It should be the relative path to the application from the Application.cfc file.
- baseURL – Normally, redirect() and buildURL() default to using CGI.SCRIPT_NAME as the basis for the URL they construct. This is the right choice for most applications but there are times when the base URL used for your application could be different. As of 1.2, you can also specify baseURL = “useRequestURI” and instead of CGI.SCRIPT_NAME, the result of getPageContext().getRequest().getRequestURI() will be used to construct URLs. This is the right choice for FW/1 applications embedded inside Mura.
- cfcbase – Provide this if the controllers and services folders are not in the same folder as the application. It is used as the dotted-path prefix for controller and service CFCs, e.g., if cfcbase = ‘com.myapp’ then a controller would be com.myapp.controllers.MyController.
- suppressImplicitService – Use this option to tell FW/1 to automatically invoke a service that matches section.item in the request. Added in 1.2. In 2.0, the default of this option is true no implicit service call is queued. In FW/1 1.x, the default was false and FW/1 called a service method automatically. Experience has shown that was not a good idea (sorry!).
- suppressServiceQueue – Use this option to tell FW/1 to allow service() calls and start/end controller handlers. Release 2.5 deprecated the service queue and introduced this option to allow the release 2.2 behavior to continue until users can migrate away from the service queue. Release 3.0 will remove all of the service queue machinery. New in Release 2.5
- enableGlobalRC – Use this option to tell FW/1 to setup rc in the framework’s variables scope. That was the default behavior in FW/1 2.2 but 2.5 adds getRC() and getRCValue() which are a better, safer way to access the request context, and adds this option with a default of false. Set this option to true in FW/1 2.5 to restore the 2.2 behavior to help with migration.
- unhandledExtensions – A list of file extensions that FW/1 should not handle. By default, just requests for some.cfc are not handled by FW/1.
- unhandledPaths – A list of file paths that FW/1 should not handle. By default, just requests for /flex2gateway are not handled by FW/1. If you specify a directory path, requests for any files in that directory are then not handled by FW/1. For example, unhandledPaths = ‘/flex2gateway,/404.cfm,/api’ will cause FW/1 to not handle requests from Flex, requests for the 404.cfm page and any requests for files in the /api folder.
- unhandledErrorCaught – By default the framework does not attempt to catch errors raised by unhandled requests but sometimes when you are migrating from a legacy application it is useful to route error handling of legacy (unhandled) requests through FW/1. The default for this option is false. Set it true to have FW/1’s error handling apply to unhandled requests. Added in 2.1
- preserveKeyURLKey – In order to support multiple, concurrent flash scope uses – across redirects – for a single user, such as when they have multiple browser windows open, this value is used as a URL key that identifies which flash context should be restored for that browser window. If that doesn’t make sense, don’t worry about it – it’s magic! This value just needs to be something unique that won’t clash with any of your own URL variables. As of 1.2, this will be ignored if you set maxNumContextsPreserved to 1 because with only one context, FW/1 will not use a URL variable to track flash scope across redirects.
- maxNumContextsPreserved – If you expect users to have more than 10 browser windows open at the same time, you’ll want to set this value higher. I know, Ryan was very thorough when he implemented multiple flash contexts! As of 1.2, setting maxNumContextsPreserved to 1 will prevent the URL key from being used for redirects (since FW/1 will not need to track multiple flash contexts).
- cacheFileExists – If you are running on a system where disk access is slow – or you simply want to avoid several calls to fileExists() during requests for performance – you can set this to true and FW/1 will cache all its calls to fileExists(). Be aware that if the result of fileExists() is cached and you add a new layout or a new view, it won’t be noticed until you reload the framework. Added in FW/1 1.2.
- applicationKey – A unique value for each FW/1 application that shares a common ColdFusion application name.
- noLowerCase – If true, FW/1 will not force actions to lowercase so subsystem, section and item names will be case sensitive (in particular, filenames for controllers, views and layouts may therefore be mixed case on a case-sensitive operating system). The default is false. Use of this option is not recommended and is not considered good practice. Added in FW/1 2.0.
- subsystems – An optional struct of structs containing per-subsystem configuration data. Each key in the top-level struct is named for a subsystem. The contents of the nested structs can be anything you want for your subsystems. Retrieved by calling getSubsystemConfig(). Currently the only key used by FW/1 is baseURL which can be used to configure per-subsystem values. Added in FW/1 2.0.
- trace – If true, FW/1 will print out debugging / tracing information at the bottom of each page. This can be very useful for debugging your application! Note that you must enable session management in your application if you use this feature. Added in FW/1 2.1.
At runtime, this structure also contains the following key (from release 0.4 onward):
- version – The release number (version) of the framework.
This is set automatically by the framework and cannot be overridden (well, it shouldn’t be overridden!).
In addition you can override the base directory for the application, which is necessary when the controllers, services, views and layouts are not in the same directory as the application’s index.cfm file. variables.framework.base should specify the path to the directory containing the layouts and views folders, either as a mapped path or a webroot-relative path (i.e., it must start with / and expand to a full file system path). If the controllers and services folders are in that same directory, FW/1 will find them automatically. If you decide to put your controllers and services folders somewhere else, you can also specify variables.framework.cfcbase as a dotted-path to those components, e.g., com.myapp.cfcs assuming that com.myapp.cfcs.controllers.Controller maps to your Controller.cfc and com.myapp.cfcs.services.Service maps to your Service.cfc .
In addition to the standard /section/item URLs that FW/1 supports, you can also specify “routes” that are URL patterns, optionally containing variables, that map to standard /section/item URLs.
To use routes, specify variables.framework.routes as an array of structures, where each structure specifies mappings from routes to standard URLs. The array is searched in order and the first matching route is the one selected (and any subsequent match is ignored). This allows you to control which route should be used when several possibilities match.
Placeholder variables in the route are identified by a leading colon and can appear in the URL as well, for example { “/product/:id” = “/product/view/id/:id” } specifies a match for /product/something which will be treated as if the URL was /product/view/id/something – section: product, item: view, query string id=something.
Routes can also be restricted to specific HTTP methods by prefixing them with $ and the method, for example { “$POST/search” = “/main/search” } specifies a match for a POST on /search which will be treated as if the URL was /main/search – section: main, item: search. A GET operation will not match this route.
Routes can also specify a redirect instead of a substitute URL by prefixing the URL with an HTTP status code and a colon, for example { “/thankyou” = “302:/main/thankyou” } specifies a match for /thankyou which will cause a redirect to /main/thankyou.
A route of “*” is a wildcard that will match any request and therefore must be the last route in the array. A wildcard route may be restricted to a specific method, e.g., “$POST*” will match a POST to any URL.
The keyword “$RESOURCES” can be used as a shorthand way of specifying resource routes: { “$RESOURCES” = “dogs,cats,hamsters,gerbils” } (Added in FW/1 2.2). FW/1 will interpret this as if you had specified a standard set of routes for each of the listed resources. For example, for the resource “dogs”, FW/1 will parse the following routes:
{ "$GET/dogs/$" = "/dogs/default" },
{ "$GET/dogs/new/$" = "/dogs/new" },
{ "$POST/dogs/$" = "/dogs/create" },
{ "$GET/dogs/:id/$" = "/dogs/show/id/:id" },
{ "$PATCH/dogs/:id/$" = "/dogs/update/id/:id", "$PUT/dogs/:id/$" = "/dogs/update/id/:id" },
{ "$DELETE/dogs/:id/$" = "/dogs/destroy/id/:id" }
There are also some additional resource route settings that can be specified. First you should note that the following three lines are equivalent:
{ "$RESOURCES" = "dogs,cats,hamsters,gerbils" },
{ "$RESOURCES" = [ "dogs","cats","hamsters","gerbils" ] },
{ "$RESOURCES" = { resources = "dogs,cats,hamsters,gerbils" } }
The first two lines are shorthand ways of specifying the full configuration struct given in the third line. An example of a full configuration struct would be the following:
{
resources = "dogs",
methods = "default,create,show",
pathRoot = "/animals",
nested = "..."/[...]/{...}
}
The key “methods”, if specified, limits the generated routes to the method names listed.
The key “pathRoot”, if specified, is prepended to the generated route paths, so, given the above configuration struct, you get routes such as { “$GET/animals/dogs/:id” = “/dogs/show/id/:id” }.
Alternatively (or in addition), you can specify a subsystem: subsystem = “animals”, which generates routes such as { “$GET/animals/dogs/:id” = “/animals:dogs/show/id/:id” }.
The key “nested” is used to indicate resources which should be nested under another resource, and again can be specified as a string list, an array, or a struct. For example: { “$RESOURCES” = { resources = “posts”, nested = “comments” } } results in all of the standard routes for “posts”, and in addition generates nested routes for “comments” such as { “$GET/posts/:posts_id/comments” = “/comments/default/posts_id/:posts_id” }. Here it should be noted that the convention is to map the parent resource key to the variable name “#resource#_id”. Also, you cannot specify a path root or subsystem for a nested resource as it inherits these from its parent resource.
The specific routes that FW/1 generates are determined by the variables.framework.resourceRouteTemplates array. By default it looks like the following:
variables.framework.resourceRouteTemplates = [
{ method = 'default', httpMethods = [ '$GET' ] },
{ method = 'new', httpMethods = [ '$GET' ], routeSuffix = '/new' },
{ method = 'create', httpMethods = [ '$POST' ] },
{ method = 'show', httpMethods = [ '$GET' ], includeId = true },
{ method = 'update', httpMethods = [ '$PUT','$PATCH' ], includeId = true },
{ method = 'destroy', httpMethods = [ '$DELETE' ], includeId = true }
];
If you wish to change the controller methods the routes are mapped to, for instance, you can specify this array in your Application.cfc and then change the default method names. For example, if you want “$GET/dogs/$” to map to “/dogs/index”, you would change method = ‘default’ to method = ‘index’ in the first template struct.
A route structure may also have documentation by specifying a hint: { “/product/:id” = “/product/view/id/:id”, hint = “Display a product” }.
Here’s an example showing all the features together:
variables.framework.routes = [
{ "/product/:id" = "/product/view/id/:id", "/user/:id" = "/user/view/id/:id",
hint = "Display a specific product or user" },
{ "/products" = "/product/list", "/users" = "/user/list" },
{ "/old/url" = "302:/new/url" },
{ "$GET/login" = "/not/authorized", "$POST/login" = "/auth/login" },
{ "$RESOURCES" = { resources = "posts", subsystem = "blog", nested = "comments,tags" } },
{ "*" = "/not/found" }
];
As of version 2.1, FW/1 supports environment control – the ability to automatically detect your application environment (development, production, etc) and adjust the framework configuration accordingly. There are three components to environment control:
- variables.framework.environments – An optional structure containing groups of framework options for each environment.
- getEnvironment() – A function that you override in Application.cfc that returns a string indicating the application environment.
- setupEnvironment( string env ) – A function that may optionally override in Application.cfc to provide more programmatic configuration for your application environment.
Environment control is based on the concept of tier – development, staging, production etc – and optionally a server specifier. This two-part string determines how elements of variables.framework.environments are selected and merged into the base framework configuration. A string of the format “tier” or “tier-server” should be returned from getEnvironment(). FW/1 first looks for a group of options matching just tier and, if found, appends those to the base configuration. FW/1 then looks for a group of options matching tier-server and, if found, appends those to the configuration. After merging configuration options, FW/1 calls setupEnvironment() passing the tier/server string so your application may perform additional customization. This process is executed on every request (so be aware of performance considerations) which allows a single application to serve multiple domains and behave accordingly for each domain, for example.
Your getEnvironment() function can use any means to determine which environment is active. Common methods are examining CGI.SERVER_NAME or using the server’s actual hostname (accessible thru the new getHostname() API method). Here’s an example setup:
public function getEnvironment() {
if ( findNoCase( "www", CGI.SERVER_NAME ) ) return "prod";
if ( findNoCase( "dev", CGI.SERVER_NAME ) ) return "dev";
else return "dev-qa";
}
variables.framework.environments = {
dev = { reloadApplicationOnEveryRequest = true, error = "main.detailederror" },
dev-qa = { reloadApplicationOnEveryRequest = false },
prod = { password = "supersecret" }
}
With this setup, if the URL contains www, e.g., www.company.com, the tier will be production (“prod”) and the reload password will be changed to “supersecret”. If the URL contains dev, e.g., dev.company.com, the tier will be development (“dev”) and the application will reload on every request. In addition, a detailed error page will be used instead of the default. Otherwise, the tier will still be development (“dev”) but the environment will be treated as a QA server: the development error setting will still be in effect but the framework will no longer reload on every request.
Here is another example:
public function getEnvironment() {
var hostname = getHostname();
if ( findNoCase( "local", hostname ) ) return "dev-" & listFirst( hostname, "-" );
var svrname = listFirst( hostname, "." ); // drop domain name etc
switch ( svrname ) {
case "proserver14a": return "prod-1";
case "proserver15c": return "prod-2";
case "proserver22x": return "prod-3";
case "proserver03b": return "qa";
default: return "dev-unknown";
}
}
This maps local hostnames to specific developers machines (e.g., my development machine is called Sean-Corfields-iMac.local and my team’s machines follow similar naming). It specifically identifies the three servers in the production cluster and the QA server. All other environments are treated as development with an unknown server specifier.
If you want to ensure that all environments are known configurations, your setupEnvironment() function can halt the application if a default environment is detected.
The easiest way to setup application variables is to define a setupApplication() method in your Application.cfc and put the initialization in there. This method is automatically called by FW/1 when the application starts up and when the FW/1 application is reloaded.
The easiest way to setup session variables is to define a setupSession() method in your Application.cfc and put the initialization in there. This method is automatically called by FW/1 as part of onSessionStart().
The easiest way to setup request variables (or even global variables scope) is to define a setupRequest() method in your Application.cfc and put the initialization in there. Note that if you set variables scope data, it will be accessible inside your views and layouts but not inside your controllers or services.
The subsystems feature allows you to combine existing FW/1 applications as modules of a larger FW/1 application. The subsystems feature was contributed by Ryan Cogswell and the documentation was written by Dutch Rapley. Read about Using Subsystems to combine FW/1 applications.
FW/1 uses the request scope for some of its temporary data so that it can communicate between Application.cfc lifecycle methods without relying on variables scope (and potentially interfering with user data in variables scope). The ReferenceManual specifies which request scope variables are used and what you may and may not do with them.
In addition, the API of FW/1 is exposed to controllers, views and layouts in a particular way as documented below.
Each controller method is passed the request context as a single argument called rc, of type struct. If access to the FW/1 API is required inside a controller, you can define an init() method (constructor) which takes a single argument, of type any, and when FW/1 creates the controller CFC, it passes itself in as the argument to init(). Your init() method should save that argument in the variables scope for use within the controller methods:
function init(fw) {
variables.fw = fw;
return this;
}
Then you could call any framework method:
var user = createObject('component','model.user').init();
variables.fw.populate(user);
This will call setXxx() methods on the user bean, passing in matching elements from the request context. An optional second argument may be provided that specifies the keys to populate (the default is to attempt to match against every setXxx() method on the bean):
variables.fw.populate(user,'firstName, lastName, email');
This will call setFirstName(), setLastName() and setEmail() on the user bean, passing in matching elements from the request context.
The other framework methods that are useful for controllers are:
variables.fw.redirect( action, preserve, append, path, queryString );
where action is the action to redirect to, preserve is a list of request context keys that should be preserved across the redirect (using session scope) and append is a list of request context keys that should be appended to the redirect URL. preserve and append can both be omitted and default to none, i.e., no values preserved or appended. The optional path argument allows you to force a new base URL to be used (instead of the default variables.framework.baseURL which is normally CGI.SCRIPT_NAME). queryString allows you to specify additional URL parameters and/or anchors to be added to the generated URL. See the Reference Manual for more details.
I cannot imagine other FW/1 API methods being called from controllers at this point but the option is there if you need it.
Note: if you let your controllers be managed by a bean factory, in FW/1 1.1 and earlier you lose the ability to pass the framework in at construction time and therefore the ability to call API methods. My recommendation is to use a bean factory to manage your services but let FW/1 create your controllers, pass itself into their constructors and autowire dependencies from the bean factory. As of 1.2, you can use a setFramework( any framework ) method on your controller to have FW/1 injected into your controller.
As indicated above under the “in depth” paragraph about views and layouts, the entire FW/1 API is available to views and layouts directly (effectively in the variables scope) because of the way views and layouts are executed. This allows views and layouts to access utility beans from the bean factory, such as formatting services, as well as render views and, if necessary, other layouts. Views and layouts also have access to the framework structure which contains the action key – which could be used for building links:
<a href="?#framework.action#=section.item">Go to section.item</a>
But you’re better off using the buildURL() API method:
<a href="#buildURL( 'section.item' )#">Go to section.item</a>
You can provide additional query string values to buildURL():
<a href="#buildURL( 'section.item?arg=val' )#">Go to section.item with arg=val in URL</a> <a href="#buildURL( action = 'section.item', queryString = 'arg=val' )#">Go to section.item with arg=val in URL</a>
I cannot imagine a view or layout needing full access to the FW/1 API methods beyond view(), layout() and getBeanFactory() but the option is there if you need it.
FW/1 provides a number of convenience methods for manipulating the action value to extract parts of the action (the action argument is optional in all these methods and defaults to the currently requested action):
- getSubsystem( action ) – If subsystems are enabled, this returns either the subsystem portion of the action or the default subsystem. If subsystems are not enabled, returns an empty string.
- getSection( action ) – Returns the section portion of the action. If subsystems are enabled but no section is specified, returns the default section.
- getItem( action ) – Returns the item portion of the action. If no item is specified, returns the default item.
- getSectionAndItem( action ) – Returns the section.item portion of the action, including default values if either part is not specified.
- getFullyQualifiedAction( action ) – If subsystems are enabled, returns the fully qualified subsystem:section.item version of the action, including defaults where appropriate. If subsystems are not enabled, returns getSectionAndItem( action ).