Yesterday, we went over the initial steps on the config.xml, click here to read it. We went over the Settings element and all the configurations that ColdBox can do for you. Today we continue on reviewing the rest of the elements in this config file. This is the full config.xml file: mail.server.com myusername mypassword cfcoldbox@coldbox.com joe@coldbox.com luis@gmail.com dev localhost mydev Layout.Main.cfm vwEmails vwPhones vwContactBook includes/main en_US session

YourSettings

Today we start with the YourSettings element. This element is used by the developer to set any values he/she would like to use in the application. This can be configuration settings, etc. As you can see above, I use it to declare a datasource, a flag for maintenance, and a variable to hold my publish_emails. You can then use all this settings in your applications by simply calling the getSetting("name") Method. You can even change the settings that are loaded in memory using the setSetting("name", {value}) . This element is a great way to securely store your applications configurations.

MailServerSettings

This element is used to declare the mail server, username and password to use for the application. This is an optional element, due to the fact that if it is not declared, then ColdBox will send emails out using the values in the ColdFusion administrator. mail.server.com myusername mypassword In the MailServer element you declare the dns or ip address of the mail server. MailUsername is the username to use to log in to the mail server defined. MailPassword is the Mail Password, duh!

BugTracerReports

This element works in conjunction with the EnableBugReports setting in the first tutorial. You must have this setting flag enabled in order for ColdBox to send you any bug reporst. In this element you are going to declare all the email addresses that will receive bug reports by using the BugEmail element. cfcoldbox@coldbox.com joe@coldbox.com luis@gmail.com

DevEnvironment

Since we all work in development environments, hopefully, a common setting in development might be different in production. Thus, the nature of this element. In this element you will declare url snippets that the framework will test at initialization. Once a match is produced, the frameworks : Environment setting is set to "DEVELOPMENT" or "PRODUCTION" if none are found. This is a great way for you to declare your development urls, not the full url just parts of it, and ColdBox sets the correct internal environment. dev localhost mydev In the example above, I set three url fragments that the framework will test for: "dev", "localhost", "mydev" If at least one of them is found in the cgi.http_host, then ColdBox will set the Environment setting to DEVELOPMENT, else to PRODUCTION.

WebServices

Since we are now in a service oriented web architecture, this was a great way to declare all the web services my application will use. Not only that, I can declare two url's for webservice, one for development and one for production. ColdBox reads this elements and places them in the configuration structure. You can then use the webservices plugin to get the webservice's url, get a webservice object already instantiated or refresh the web services's stubs. So for example if I call getWS("luis"), ColdBox will retrieve the correct web service URL according to the environment I am on, DEVELOPMENT or PRODUCTION. I no longer have to create tons of if's statements. ColdBox does it for me by sensing its environment. In the second web service declaration you see that their is no DevURL attribute defined. Well, that is an optional attribute. If not used, then ColdBox will use the url in the URL attribute for both DEVELOPMENT and PRODUCTION.

Layouts

The layouts element is used to delare the Default Layout that all views will be rendering in and to declare other Layouts that with the views it can render. Layout.Main.cfm vwEmails vwPhones vwContactBook As you can see from the code above, the DefaultLayout element is mandatory and you define the name of the file. This file will need to be in the layouts directory. You can then continue to declare multiple Layout elements to declare how other views will be rendered. You can see the first Layout declaration has a name of "popup_black" and a file of "Layout.popup_black.cfm". It then defines two child View elements: vwEmails, vwPhones. This information gets loaded in the configuration structure of ColdBox, so when an event handler sets any of these views, it will automatically render them in the declared layout and not in the default layouts. So if I have in an event handler: setView("vwEmails") ColdBox will render the vwEmails view in the Layout.popup_black.cfm template. You can have as many layouts as you want. And also remember that you can override a view's layout by programmatically setting it in your event handlers. A perfect example of this feature is if you want to provide a cfdocument capability throughout your site, for any view, you simply can override the DefaultLayout of the view by using the setLayout("template") function. This tells ColdBox to render the view in the layout that was just set and not in the one in the configuration structure. The possibilties are endless.

i18N

ColdBox has basic Internationalization support built in thanks to Paul Hastings and Raymond Camden. It makes use of java resource bundles and java locales. If you need more information about internationalization, please visit the following sites:

• i18ngurus
• Open Source Listing of i18N by Brian Rinaldi

Now, some people might not be that familiar with this concept, I am no expert, so I tried to make ColdBox give applications i18N support without a big headache or a lot of configuration. So basically the way to add i18N support for a ColdBox application is to fill out the following configuration (3 LINES ONLY!!!) and create your resource bundles with your key-value pairs using UTF-8 encoding. At the end of the post is a resources section that can help you out even more. includes/main en_US session In the first element: DefaultResourceBundle you declare the location of your resource bundles without the locale part: includes/main This tells ColdBox that in the includes directory there will be a file that starts with main in the includes directory. The second element DefaultLocale is used to define the default locale to use: en_US. Please remember that this is using standard java locale syntax. Look here for more details some examples are es_SV, es_DO This gets appended to the first element to define the default file to load: includes/main_en_US.properties The text in italics is what is defined in the xml, the rest is appended by ColdBox. So make sure your files look like the following format: {name}_{java standard locale}.properties The third element is LocaleStorage and you have two possibilities: session or client. This tells ColdBox in what scope to store the locale of each user. This way, you can have a users running the application in different locales (languaages) There is no big deal about resource bundles, they are files that have key-value pairs, look at the example below: help_button=Help close=Close Me relocate_button=Relocate Now! intro_message=Welcome to my website. search_button=Search It! search_test=Search for postings now. And that is it for this config.xml tutorial. You can see all the features that apply to the config.xml file, what you can do and declare. If you have any comments, suggestions or critics, please post them. One important thing to notice, is that you are not developing in your xml file. You just use it to declare your configuration. The real programming is done in the event handlers using ColdFusion and not XML. This gives you more flexibility because, you can reuse your code if you want to switch to another framework or another application. You do not have to recode whatever was coded in XML.

Resources:

Paul Hastings cfc: http://www.sustainablegis.com/unicode/resourceBundle/rb.cfm For ISO Language Code information look at: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt For ISO Country Code information look at: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html For locale information look at http://java.sun.com/j2se/1.4.2/docs/guide/intl/locale.doc.html