Critical-Web

The State Of Affairs

Fri, 27 Jul 2012 08:09:00 -0500

Wow, I haven't been here in a while. Things have been pretty crazy over the last two years. Hopefully things will be getting better soon. A little bit of a recap. For the last three years my work has been implementing e-commerce websites for one of the leading players in the industry. The platform is built on a massive ColdFusion layer. I was responsible for creating new modules, customizing implementations and everything in-between. In August of last year it was announced that our company was merging with another provider. A decision had to be made: there were now two very different platforms available from the same company. In the end, the other platform was chosen, for a variety of reasons. The implication, aside from the obvious "I now need to learn a new platform", is much more important: the entire platform is built on Java. The last time I used Java was in college, almost ten years ago. To say I'm rusty would be an understatement. I have a whole lot of learning to do. Luckily, the company is assisting us in this process. There are several ColdFusion developers on the floor with little to no experience with Java. A training path has been set forth and broken down into manageable chunks. We've all got a lot of work ahead of us, but I see it as a challenge. In the next couple of months I will be sharing my experiences as I struggle to continue supporting our legacy implementations while learning a new language and platform. This is going to be fun. Over and out

The "Behind-the-scenes" of SQUASH's Authentication

Tue, 04 Aug 2009 09:20:00 -0500

Yesterday we looked at how to setup a login form and process the information with ColdBox. Today we'll go a step further by viewing the code behind the authentication model.

At the very beginning of our processLogin event we called upon the authenticationService object to, well, authenticate the user. The authentication model is made up of three distinct objects: authentication.cfc, authenticationService.cfc and authenticationGateway.cfc. The authenticaionService is the main entry for all requests to the model. The gateway is the part that interacts with the database. Authentication.cfc is basically just a bean that gets passed around alot.

authentication.cfc

Basically just a bean, it has a couple of properties and a series of get/set methods:

Nothing too special happening here. The setX methods store the value in the bean's instance so they can be retrieved later with the getX methods.

authenticationGateway.cfc

AuthenticaionGateway is the main entrance to our model. This is the object we request from ColdSpring in our processLogin event.

Our first method, init(), is going to be called by Coldspring to set the gateway automatically. The authenticate method is the one we call when we want to confirm that the entered user name and password are correct. The way we achieve this is by instantiating an authentication object and then passing it to the gateway for processing. We then return the processed bean to the requester.

The final method, isAuthenticated(), is a way to encapsulate the logic behind testing for successful authentication. The processLogin event doesn't need to know the rules behind a proper login. It just needs to ask the service by passing back the bean. The service knows that if the user_id isn't 0 and that there were no errors the authentication was a success.

authenticationGateway.cfc

This object is really simple and contains only two methods: init and authenticateUser.



	
		
		
		
	
	
	
		
		
		
	
		
		SELECT
			name.user_id
			, CASE WHEN pw.user_id IS NULL THEN 1 ELSE 0 END AS incorrect_password
		FROM
			users AS name
		LEFT JOIN
			users AS pw
		ON
			name.user_id = pw.user_id 
			AND pw.password = 
		WHERE
			name.user_name = ;

As before, the init method is called by Coldspring to properly initialize the object. We configured our coldspring.xml.cfm file to pass in the dsn parameter to the authenticationGateway object, which it does supernaturally. The authenticateUser method is where everything happens. Basically, it queries the database with the bean's user name and password properties.

I built my query this way so that with a single cfquery tag I could confirm the user name exists even if the password check fails. The first table (name) will have a record if the user name matches. If not, the entire resultset will be empty. The second table (pw) will only have a result if the password matches as well. The CASE clause checks for the existence of a record in the second table. If a row is found, it returns 1 (true). Otherwise, it returns 0 (false).

The second part of the method sets the user_id or the error, depending on the situation:

If there are results and
- the password is correct: the user_id is set;
- the password is incorrect: an error is set ("INVALID_PASSWORD");
If there are no results: an error is set ("INVALID_USERNAME");

Why go through all this?

You might be asking yourselves: why go to the trouble of doing all of this in the first place? Sure, I could've put that query right in the middle of my processLogin event and checked for the logic there. There are a couple of good answers to that (I hope!).

Encapsulation of logic

Best practice dictates that a controller of an MVC framework should do as less as possible. It's a traffic agent. It doesn't need to know how the cars run, it just has to know how to get them across the intersection without causing an accident. Getting our authentication logic out of the controller and into it's own model allows us to separate concerns and keep logic where it needs to be.

Reusability

What if our processLogin isn't the only one that will need to handle authentication? There might be other reasons to call upon the authentication logic: web services, different frontends (Flex, among others). If we have all of our login code in the controller we need to copy it to every event that needs to check for authenticaion. Our authenticaion code is also pretty generic. We could very easily copy it over to a different object, validate the query is still valid against the different database and we're set!

It ain't that complicated!

At first glance, it does look complicated. There are three .cfcs where a query and a couple of lines would've done the trick. However if you look closer you'll notice that there really isn't that much going on. Some generic set/get methods, another one for querying the database and two more for authenticating the user and making sure the authentication was a success. On top of that, the code within the controller is much simpler. All it needs to do is ask the authenticationService to do the heavy lifting.

I hope that clears it all up. One of the nice bonuses of our authentication model is that, although it relies on the users table, it isn't built from it. We couldn't use Illudium PU-36 Code Generator to generate our cfcs for us, we needed to write them on our own. I feel this helps to understand the relation between the different objects in our model. In most cases, however, our models are built from database tables so most of the code can be generated rather simply. All we need to do after is query them from our controllers and we're set!

Getting To Know Our Users

Mon, 03 Aug 2009 13:28:00 -0500

Now that we know what we're working with, we're going to need to sit down and understand how our users will be defined and how they will authenticate with the system.

We'll start out with a really simple table to define our users. We can always come back later and add additional information.

users
------------------
user_id integer
user_hash string
user_name string
password string
email string
[...]

The user_id column is the primary key of our table. It's set to auto-increment, so each new user will have a unique user_id. We also create a unique user_hash for each user. The plan is that in cookies and forms we won't want to use the user_id as it would be too easy to change the cookie's value to a different number to try and log in with someone else's credentials. This user hash is simply going to be a UUID stripped of dashes. Why strip the dashes, you may ask? Well, that's rather simple: I think they don't look good. That and the fact that the dashes don't add to the uniqueness of the UUID. We can remove them without fear of corrupting our data. As for the password, we'll store it as a hashed string encrypted using the SHA-512 algorithm. This will convert the user's password to a 128-character long string.

A UUID, or Universally Unique IDentifier, is a string that is intended to be unique. It uses a combination of the computer's MAC address, the timestamp and several other magic components to generate this string.

Let's start by giving our table a test user to work with. This script was written for MySQL but should also work in most other SQL languages.

INSERT INTO users ( user_hash, user_name, password, email ) VALUES (
  '50F6E9B5D6765C61F23A6BD60D1EF328',
  'Admin',
  '67E1B608EB15C93A327D13BDD7D61EE9B38BAC84E5F4E005B2278953EE9A7A1D28EF4299A32BEC704F0E6D9A098B744C3051403D30E518A127E5BE5EAB459D02', -- squash
  'your.email@here.com'
);

Preparing our login screen

To display a login screen, we'll have to prepare an event in ColdBox. To keep concerns separated, we'll create a separate handler for users. This handler will do stuff that users do: log-in, log-out, manage profile, user options, etc. But we're getting ahead of ourselves. For now, let's just create an empty handler and save it as /handlers/users.cfc:

Now that our handler's set up, we need to give it an event. When we don't request a specific event from a handler, it looks for the default one: index. That's a perfect spot to put our login form in, so let's create that event:

Remember: when ColdBox is looking for an event, it will look in the component for the requested handler, and then call the method with the name of the requested action. For example, when we call index.cfm?event=users.index, it will call the index method of the users component. The first thing we're doing in our action is creating a local variable with a reference to the request collection. The request collection is a copy of all URL and FORM variables. It also has access to several of ColdBox's inherent methods. What we do next is create an eXit Event Handler. The purpose of this variable is to tell the view where it will be submitted to. This allows forms to be reused and is a best-practice in most MVC-based frameworks.

"The basic idea of SES URLs is to create a URL that is passing variables (variable=value pairs) but does not look like it is. Why? Because search engines don't always pick up links to pages where variables are passed." (source)

ColdBox automatically converts SES URLs to it's native format (index.cfm?event=handler.action).

ColdBox has a handy method called getSetting that allows you to access it's internal settings structure. One of these values is SESBaseURL. Basically, it is the complete link to your index.cfm file. After that all you need to do is add the event in the form /handler/action, or, in our case, /users/processLogin. We then tell ColdBox to display our form through the setView method.



	
		
		
			#rc.login_error#
		
		
		
			User name:
			
		
		
		
			Password:
			
		
		
		
			 Stay logged in?

Just a basic HTML form! We know that ColdBox provides us with the an rc struct, which is a reference to the request collection. On line 5 we use another of ColdBox's methods: event.valueExists(). This functions returns true if the requested variable exists in the request collection and false if it doesn't.

Working with the form data

We setup our page to submit to the processLogin action of the users handler. Before I paste the code here's a rundown of what this event needs to do:

Ensure the user name and password provided is valid;
If invalid, return to login page and display the error;
If valid, construct a structure with the user's info;
Store the user information in the session scope;
If the user wants to stay logged in, store a cookie;
Return the user to the main page.

Here's what I have right now to go through this:

I'll start by going through the entire event, and then I'll show the code behind some of these objects. So, we start by asking our authentication service to check if the user's information is valid. If the information is incorrect, we set a variable in our request collection and call the previous event. As you can see, all we need to do is call the method associated to that event to have it fire again. If everything's OK we can use the user service to retrieve the user's remaining information and store it in a structure.

ColdBox has a built-in plugin that encapsulates calls to the session variable. It basically takes care of locking the scope whenever you need to read from/write into it. By calling the plugin and using it's setVar method we can place our user's information in the session scope. Then, we use ColdBox's event.getValue() method to return the persist variable. However, since it's a checkbox if it wasn't checked it won't exist. The second parameter of the method is the value returned if it doesn't exist. Handy, right? So, if the checkbox was checked, store a cookie with the user's hash in it. Once we're done we tell ColdBox to send the user back to the default action of the general handler, which in our case will be our home page. The last call to event.noRender() tells ColdBox not to show a page for this event.

I had planned to go show how I setup the authentication model today, but then I looked back at all that's already there and I thought it's probably more than enough for today. We at least covered how to submit and process forms in ColdBox, and saved the user's information in the session scope. Tomorrow we'll see more code from the authentication system.

SQUASH: Unveiling

Fri, 31 Jul 2009 09:20:00 -0500

Surprise! Yeah, I bet you didn't see that one coming, did you? It's Friday and I didn't want to start getting into the code just before a week-end. What better opportunity, then, to go ahead and announce the details of my new project? For your reading pleasure, I give to you: SQUASH.

What is SQUASH?

You've all been waiting for it, so here it is. SQUASH is (will be) a full-featured bug tracker / ticketting system. The goal is simple: to provide a streamlined, easy-to-use interface for tracking bugs and enhancement requests. It will also integrate a wiki-based templating system that'll allow for documentation and other resources to be placed within the system.

Another tracker? Why?

There are several reasons, really. The first thing that motivated me into doing this is that the tracker we currently use at work is a complete piece of crap. Granted, it's the first tracker I had to work with, but still, nothing about it is easy or practical. A simple example: the interface for replying to a thread doesn't display past posts. I actually need to have two windows open: one for the original thread, one for the response so I can respond to each point.

Another reason is that there aren't many ColdFusion solutions out there for bug tracking. Sure, there's Ray Camden's Lighthouse Pro, but if I stopped myself from doing something just because Ray did it already, I'd be out of a job :P.

And then, there's the plain fact that I needed something to do. I want to prove to myself that I can see this project through. It's a relatively large project in that it has several compoments working together to achieve a single goal: making our lives as programmers easier and more efficient (*cries*).

Okay, you win. What will SQUASH have that'll make it so awesome?

Well, I wouldn't say awesome (*blushes*). Really cool, though. Anyways, here's a quick rundown of a couple of key features I'd like SQUASH to have when launched, in no particular order:

Complete user management (roles, permissions, etc.);
Ticket bucketting: categories, folders, groups, etc.;
User and ticket queues;
Wiki-based templating system;
Simple and streamlined user interface;
Mylyn integration (this would be neat, though could be tough);
Ajaxified elements? This one's tricky, as some functions warrant AJAX, and some don't. Might need to think a bit more on this one;
And much, much more!

Like I said, not necessarily all of these features will make it, but I'd sure like them to. As work progresses on the project I might even add in new features as I play around the interface and think of new ways to make it more awesomer.

This project sounds cool. How can I help?

There's no denying that several people working on a project will generally get it out the door faster. I'm not necessarily aiming for a quick release, though. Like I stated previously, I'm using this project to hone my skills using ColdBox and Coldspring. If people want to join in on the learning experience, that's fine by me. If I see enough interest I might setup a project on RIAForge to facilitate collaboration. In the meantime, this blog will serve as a daily log of my progress, as well as way for me to share what I've learned working on the project. Of course, any comments / insight / complaints and insults are always welcome.

Thanks for sticking around this long. Stay tuned for more.

Using Coldspring With ColdBox

Thu, 30 Jul 2009 10:28:00 -0500

So what does Coldspring do, anyways? We know by now that it's an Inversion of Control (IoC) framework. We also know that it helps us manage dependencies between objets. And yet, we're not quite sure what that means exactly yet. To help demonstrate the power of Coldspring, I've prepared a simple example.

To show what Coldspring can do, we need objects. For the purpose of our example, we're going to use a dummy Person model. Our model needs properties, so let's try and see how we can define a person. A person generally has a couple of generic traits: name, birth date, sex (*giggle*), height, weight, and so on. Generally we'd need a way to save all of our people, so we'll have to think of a table that can hold all of them:

person_id	integer
name		varchar
birth date	datetime
sex		char
height		smallint
weigth		smallint
[...]

Simple stuff. Now, our generic template for most of our templates will require four objects: a bean, a service object, a gateway and a DAO.

Bean: Picture the bean as the actual representation of our object. Through the bean we can set and get it's properties and make sure that it's valid in it's current state.
Service object: This is generally who we're going to be talking to. We'll ask our service object for an instanciated bean of our person model; we'll ask our service object to retrieve a series of beans; we'll ask our service object to save our bean in the DB; etc. The service object then handles the request and sends it to the appropriate object for processing.
Gateway: The gateway serves as the proxy to the database for multi-user queries. Generally the gateway will be used to select a list of model objects.
DAO: The DAO, or Data Access Object, is the proxy for CRUD (Create, Read, Update, Delete) operations on an object. The service object will use the DAO to perform CRUD operations on the model.

Real-life update 1: Electrical problems on the train. It's hot as hell but I get more time to write :P.

Using a tool like cfcgenerator can save you alot of time when writing your domain model. It will take a table and generate all four objects for you.

If we look at what a tool like cfcgenerator generates for us, we'll notice four new .cfcs. Here they are with the interesting parts outlined:

Real-life update 2: Turns out a cable snapped and it'll take at least half an hour to fix. Ironically I'm 10 minutes' walk away from my parents house.

person.cfc
--------------
init()
setPerson_id()
setName()
[...]
getPerson_id()
getName()
[...]

personService.cfc
--------------
init()
	personGateway personGateway
	personDAO personDAO
getPerson()
getPersons()
savePerson()
[...]

personGateway.cfc
--------------
init()
	dsn string
getPersonsByAttribute()
[...]

personDAO.cfc
init()
	dsn string
create()
read()
update()
delete()
[...]

As you can see I didn't list out all the methods: just enough to show what these objects actually do and what they depend on. Notice that personService object needs to have the personGateway and personDAO objects passed in when inited. Also, both the personGateway and personDAO objects require a dsn string be passed in when inited. Without IoC, here's how that would look like:


dsn = "mydsn";

// remember we have a squash mapping that points to our install location
oPersonGateway = createObject( 
		"component", 
		"squash.model.personGateway" 
	).init( dsn=dsn );

oPersonDAO = createObject( 
		"component", 
		"squash.model.personDAO" 
	).init( dsn=dsn );

oPersonService = createObject( 
		"component", 
		"squash.model.personService" 
	).init( 
		personGateway=oPersonGateway, 
		personDAO = oPersonDAO 
	);

That's alot of code! Enough to turn anyone away from using object-oriented programming. With Coldspring, however, things get much easier.

There's a plugin within ColdBox called "ioc". This is basically what talks to Coldspring and makes all the magic work. Using the plugin's getBean method we ask Coldspring to return the personService object instantiated. It takes care of resolving any and all dependencies.

But how does Coldspring know how to resolve these dependencies? In our config folder there's a coldspring.xml.cfm file. Within that file we define our objects (beans) and declare how they depend on each other. When cfcgenerator generates all our model code, it also generates a coldspring definition file for each of the objects generated. We just need to merge them all together and put them in our own file:

  


	
		${dsn}
	
	
		${dsn}

Each "bean" represents an object in our domain model. We give them an ID so they can be referenced elsewhere in the config file as well as by the getBean method. The class attribute points to the actual .cfc file.

Within each bean you can notice that there are constructor-arg nodes. These are arguments that will be passed in to the init method of each object. For both the personGateway and personDAO nodes the single constructor-arg is the dsn, which in this case is a reference to a ColdBox setting variable. Anytime you enclose a value with ${}, ColdBox will attempt to pass in a value from the YourSettings node in the coldbox.xml.cfm.

The personService bean is slightly different. Instead of having a value node within it's constructor-args, it has a ref node. This is how you tell Coldspring that a bean depends on another (or others). You pass in the ID of the bean and Coldspring knows that it will need to resolve their dependencies and inject them into the bean requested before sending it back.

You might also notice that there's nothing in there relating to the person object. The reason is that generally we won't need to access the person bean directly: the service object will provide it for us. Since it isn't a dependancy of anything, and that we won't be asking Coldspring for it, we can leave it out.

And that's the end of my eventful ride to work. We won't be needing the person model for SQUASH so we won't be seeing it again. Tomorrow, if nothing goes wrong (*knocks on wood*), we should be looking at some actual SQUASH code.

Creating Our First Event

Tue, 28 Jul 2009 09:33:00 -0500

Now that our application is setup, we want to make sure that it works. We'll start out by removing extra files we won't need. Once that's done we'll setup our default event and make sure everything's working.

Pruning the install

ColdBox includes a couple of extra files in it's application template. These files generally serve to display the default "welcome" event. Since we'll be replacing this event by our own, we can strip out a couple of files from the template:

/
	includes/
		helpers/
			ApplicationHelper.cfm
		images/
			coldbox.png
	logs/
		YourAppNamehere.log (a new one will be generated with our actual app name)
	build.properties
	build.xml
	readme.txt

All that should be left now is all that we need for our ColdBox-based application to work.

An event

An event is basically an action. When you request a page in ColdBox, you call an event. ColdBox then wires that event to a method in one of it's handlers, which then handles the request.

It's important to understand the idea behind event handling before proceeding. When you call a page, traditionally, your url would look something like this:

/squash/some_folder/file.cfm

In a ColdBox-based app (and many other MVC style frameworks), your url would look more like so:

/squash/index.cfm?event=some_handler.some_action

We're passing in a URL variable to ColdBox: event. This variable contains two very important parts delimited by the period. The first part, some_handler, is the handler. The handler is basically a .cfc file with loads of methods in it. The second part, some_action, is the name of the action. The action represents a method in the handler. By convention, when ColdBox receives an event call, it will look for a .cfc file with the name of handler in the handlers folder. It will then call the method within it that has the same name as the action. In our case, it will look for a some_handler.cfc file in the handlers folder, and call it's some_action method.

Now that the groundwork is done, let's override the default event left by ColdBox and create our own. In the coldbox.xml.cfm file, in the config folder, there's a setting named "DefaultEvent". This represents the event called in the case that none is provided; when someone hits index.cfm without providing an "event" variable, this is what will be called. Right now it's set to general.index which is just fine. Knowing what we now know, we can open up general.cfc in the handlers folder and search for the index method within it to see what it actually does:

Not much happening here. All actions receive an event variable, which contains all the functions/methods pertaining to the current request. One of those methods is setValue(). This adds/sets a variable within the request collection, which is then available through all methods/views for that particular request. We provide the variable name and then it's value.

A view is a ColdFusion template for displaying, well, stuff. In a MVC style framework, data is parsed/mashed in the model (M) and controller (C), while the view (V) should only bother with displaying stuff. In a ColdBox application, the model layer (M) is consisted of your beans (more on that later) and the controller (C) is made of your handlers and events.

We won't need the welcomeMessage where we're going, so we can remove it. Once we're done, we tell ColdBox which view to use to display our data. By convention, the views are located in the views folder. Tricky, huh? Let's open up home.cfm in the views folder and clear it out. We'll start by a simple hello world message:

Hello world!

When outputting that in the browser (by calling index.cfm or by providing the event parameter with index.cfm?event=general.index) we get the expected result... or do we? We can see our hello world message just fine, however some things are off. Why is there a title to our page? Also, some styles seem to be applied by default. The answer to these questions is rather simple: ColdBox uses a layout system to "wrap" around your views. You can create any amount of layouts you want and assign them to specific views or events. For now, we'll settle with using just the default layout. To modify it, we first have to figure out where it is. In the coldbox.xml.cfm file, there's a Layouts node. Within this node there's another one named DefaultLayout. This is currently set to Layout.Main.cfm, which is fine. By convention, layouts are in the layouts folder. Now that we know which file is causing our problems let's open it. For the time being we'll just clean out everything we don't need and leave it as a simple shell:



	
		
		Oooh, a layout!
	
	
		#renderView()#

A quick refresh to confirm everything is working well... great!

I took a little longer than expected to go over these basics because I think it's important that at least this is covered before going into the nitty-gritty of the application coming up ahead. I won't go into as much detail for the basics in the next posts, however. One more post about the basics of ColdBox and ColdSpring and we actually get to work on SQUASH.

edit: removed ColdSpring from the title, that's for the next post ;).

Weird lsDateFormat issue

Mon, 27 Jul 2009 15:34:00 -0500

Today I stumbled upon a strange lsDateFormat issue. On a project I'm currently working on (not THE project ;)) dates are stored in this format: "mm/dd/yyyy". Today, one of the pages started throwing an odd error:

7/29/2009 is an invalid date format.

For some reason this particular date was throwing it off. I also ran a couple of tests to try and figure out where things were going wrong.





	Is date valid: #isValid( "date", dtstring )#


	lsDateFormat, plain:
	
		#lsDateFormat( dtstring, "long" )#
		FAIL
	


	lsDateFormat, fixed?:
	
		#lsDateFormat( dtstring+0, "long" )#
		FAIL
	


	dateFormat:
	
		#dateFormat( dtstring, "long" )#
		FAIL

Running the above code I was left with the following output:

Is date valid: YES

lsDateFormat, plain: FAIL

lsDateFormat, fixed: July 29, 2009

dateFormat: July 29, 2009

The first thing that's odd is that the isValid call returns true. ColdFusion recognizes that this is a valid date. Also, passing it to dateFormat works perfectly. Why, then, does sending it to lsDateFormat fail?

The fix I ended up putting in is rather simple. By adding 0 to the string, we are forcing ColdFusion to convert the date to it's integer representation before performing the operation. Once that's done, the original date's format is no longer important.

It's also worth noting that using the ISO format (yyyy-mm-dd) in this case would've also solved the problem. However, in my case, changing the date formats was not a possibility and I had to rely on this "quick-fix".

Getting Our Project Started

Mon, 27 Jul 2009 09:35:00 -0500

Last week we were talking about using ColdBox and Coldspring to run our project. Let's take a look at how we actually make this happen.

The first thing we need to do is download the latest stable release of both frameworks. You can download ColdBox from http://www.coldbox.org/index.cfm/download and Coldspring from http://www.coldspringframework.org/. The docs recommend we unpack the archives directly unto our web root. Personally I do it slightly differently. Using the power of application-specific mappings, we can place them pretty much anywhere we want, as long as we create a mapping for them in our application.cfc file. On my install, I have a frameworks folder in my web root and within it version-specific folders for each framework

/
	frameworks/
		coldbox_2.6.2/
		coldbox_2.6.3/
		coldspring_1.2/

This allows me to tell each distinct application which version of each framework to use. The next step is copying over the application template from ColdBox's install folder to where we want our application to be. In the root of our new folder, there are now two files of interest: Application.cfc and Application_noinheritance.cfc. This is where we get to choose which one we want.

Application.cfc: This file extends the ColdBox framework. Since the link to the framework is (and has to be) in the first line, there is no way to specify where to find the appropriate version without hard-coding it in the extends attribute.
Application_noinheritance.cfc: This version extends no other cfc's. This is perfect for us, since we now have plenty of room to create our mappings before the application creates a reference to the framework.

At this point, we can safely delete Application.cfc and remove _noinheritance from the other file's name. In our new Application.cfc file, we'll add a couple of lines just before the application sets it's root path:

Notice the three lines starting with "<cfset this.mappings". These three lines do the same thing than actually going into your admin and creating three mappings, with one major difference: the mappings are exclusive to this application. That means that you could actually have a /coldbox mapping in your admin but within this application it would use a different path for it.

A mapping is a way for your application to link to a specific path on your system, without having to write the entire string out each time. When

The first two lines are for the frameworks. The mappings require an absolute path (c:\path\to\your\folder) which is why we need to use expandPath. The third line is a shortcut I use for linking to the application's folder. By retrieving the directory from the current template (Application.cfc) we have a direct link to the application's root. As a bonus, even if we move our application (new folder, new server, etc.), it will always have a squash mapping linking to it's exact installation location.

ColdBox is great for using IoC frameworks: out of the box it can handle both Coldspring and Lightwire. For this project I've decided to use Coldspring. So ColdBox knows which choice I've made I'll tell it in the coldbox.xml.cfm file, located in the config folder of our install. In the settings block there are two nodes that we need to make sure are set appropriately: IOCFramework and IOCDefinitionFile:

With these two little lines of code ColdBox now knows which IoC framework we want to use and where to find it's definition file. Now then, what do we put in that definition file? Well, that's s story for another day. At this point, ColdBox and Coldspring stand ready, but all that's in the application is the default event. We can call it by hitting the application's index.cfm file. Ain't it pretty? We'll strip all of that out tomorrow morning. In the meantime, don't forget to eat your vegetables.

New project: additional details are leaked

Fri, 24 Jul 2009 09:25:00 -0500

Two days ago I had announced that I'd started work on a new project that I'd been wanting to work on for a while. Rather than spill out all the details in one post, I thought it'd be better (and funnier) to stretch it out a little.

What's in a name? A product's name is what defines it. When people first see / hear about your product, they see / hear it's name. Your first impression is achieved by how you call your project. You could always name your project something like "Another Forum Software" or "Blog" and, although original (in their simplicity), these names simply don't stand out. Sure, they give us a pretty good idea about what they actually are, but that's pretty much it. No emotion. No power. So... cold. On the other end of the spectrum, you have names like Galleon Forums, by Raymond Camden, or Mango Blog by Laura Arguello, both excellent products. When I think of galleons, I see ships crossing the Atlantic Ocean reuniting long-separated continents. For mangos, I think of sweet, sexy, sure; I especially think of enjoyable. These projects and several others served as an inspiration.

Now what did I name my project? I can't give you too many details about the thought process (that'd give you too many hints), but I will say what I've decided to call it:

SQUASH

Yes, in caps. It adequately represents the core of what the project is, and still has an original ring to it.

Now, for the project itself. I will be writing using the excellent ColdBox Framework as a base for the application. It has served me well in the past, and will provide a robust structure from which I can build my project. I will also be using Coldspring to manage my object dependancies. Coldspring is an IoC (inversion-of-control) framework that can relieve many of the headaches associated with having several objects in your domain model. It also integrates seamlessly with ColdBox, which is a plus. As a time-saver, I will use Illudium PU-36 Code Generator (or cfcgenerator for close friends) to generate my basic model files and Coldspring definition file. This is a great tool and saves you from typing the same validation and set/get functions over and over again.

So that's it for today. The train is arriving in the station. In the next episode we'll go over getting all of these great tools working together. If you're nice, I might also have some more details on my project as well.

A New Dawn

Wed, 22 Jul 2009 12:53:00 -0500

I'm back again. Over the last couple of months I've been pretty busy with a lot of things in my life. A new addition to the family and a new job all happening at the same time had a bigger impact on my "blogging time" that I had anticipated. Luckily, I feel that I've finally struck a balance in my schedule and the time I spend commuting by train will be a perfect time to work on projects / blogging.

I've actually started work on something that I've wanted to tackle for a while now. I'll have more information in the following days, but for now I just wanted to let the world know that I'm still alive.

Stay tuned.

Beginner's Guide Series - Basic ColdFusion, part 2

Sat, 16 May 2009 02:05:06 -0500

Moving on with basic ColdFusion topics, today we'll look into the different variable types available. We'll also talk about the different ways of controlling the flow of the page through the use of conditional blocks and loops.

ColdFusion variable types

A really nice feature of ColdFusion is that it is a typeless language. What that means, in plain English, is that even though we declare a variable with a certain type, we can always come back later and assign it a different variable type later. However, the type of the variable will give us access to different functions that we'll be able to use later.

Simple types

The simple variable types are remarkable due to the fact that they're, well, simple. The best way to explain them is that they hold a simple value, as opposed to complex data.

String

String variables contain basic text. In our Hello world! example yesterday we stored our text in a string variable. When setting your string variable you need to enclose it within single- or double-quotes.

I realize now I haven't talked about comments in ColdFusion. They're very simple, really. "" closes it. Whatever is encompassed within will not be parsed by ColdFusion, and will not be returned to the browser.

Numeric

This type of variable contains numbers. The only difference between numeric and string is that numerics can only contain numbers. ColdFusion can convert between types automatically as long as the value is a number. Numeric values do not need to be enclosed within quotes.

This variable type can also contain floating numbers (1.23, 8.234, etc).

Complex types

Complex variable types generally contain a collection of data.

Lists

A list is basically a string variable, however it is notable due to the fact that it may contain several values separated by a delimiter (the default is a comma (,)). Nothing special needs to be done for ColdFusion to recognize the variable as a list.

As you can see, the list is defined the same way as a string. The only difference is the way we treat the variable.

Arrays

An array is basically a collection of variables. In its simplest form you'll see an array with a collection of simple variables:

The way we store values within an array is through square brackets ([ and ]). Within them, we specify the position (also known as index) at which we want to save our value. It's important to know that the array must have a value at all the previous positions before you assign it to a new one. What that means is you can't assign a value to position 2 before assigning something to position 1.

What's really neat with arrays is that you can also store other complex variables within it:

If you want to display a value stored at a particular position in the index, all you need to do is use the same square brackets:

The value at position 2 is: #myArray[2]#

The value at position 2 is: 24

Structures

A structure, in many ways, looks a lot like an array: it's designed to store a collection of data. It can also contain other complex variables. The main difference between the two is that structures don't use an index to store the position of the values. Instead, it uses keys.

A key is generally a string, although it can also be a numeric value, that is unique within the structure. This key reserves a spot for other values to be saved at. Where an array will always have indexes in sequence (ie.: 1, 2, 3, n... ), a structure's keys may have no apparent logic between them:

Outputting data from a structure is as easy as with an array. In fact, it's actually more verbose: since you retrieve the value using a key rather than a numeric index, it gives a better idea as to what you are trying to return:



My hair color is #myStructure.color# and my favorite movie is #myStructure["favoriteMovie"]#.

My hair color is red and my favorite movie is Scary Movie XII.

Queries

Queries are a little more complicated, so we'll come back to them later. Basically, a query is a collection of data represented by rows. Generally this kind of data is retrieved from a database, although there are exceptions. A perfect example of a query is an Excel spreadsheet we're you'd have a list of the people in your little league and their information in columns. ColdFusion is really great for getting data out of databases and making it easy to handle it, so more on that in a couple of posts.

As you can see there are plenty of variable types out there. The trick is using the right one for the situation. I'll be coming back on these topics later and referencing back to this page in the following posts. We'll see the different things we can do with them and the best way to use them.

Beginner's Guide Series - Basic ColdFusion, part 1

Wed, 13 May 2009 13:32:08 -0500

We now make it to the pice-de-resistance. The next 2 or 3 posts should go over the basics of ColdFusion.

What is ColdFusion?

ColdFusion is a server-side scripting language that was first released in July 1995. It's most distinguishing feature is it's tag-based syntax which looks a lot like HTML (you can easily distinguish them, however, since ColdFusion tags all start with cf). The advantage this has for us is that's it's relatively easy to learn. We already know about tags and attributes, thanks to the previous posts. ColdFusion is basically more of the same, with a slight twist.

How is a ColdFusion page processed?

To better understand the role of a ColdFusion template (that's what a ColdFusion file is called), it's important to know how it gets processed. ColdFusion templates have the .cfm extension. When the client points his browser to a page with a .cfm extension, the server knows that it must first parse this file before sending it back. This is where ColdFusion comes in.

ColdFusion looks at the file and determines what it needs to change. What it would need to do can vary:

Display a part of the document if a certain condition is fulfilled;
Query a database and output the recordset;
Include repeated sections on multiple pages (think page headers, footers).

Once ColdFusion is done processing the template, it then sends the finished page back to the server who passes it on to the browser as a plain HTML document. The browser has no notion of ColdFusion or of the processing that had to take place. All it receives is the finished product. It is therefore impossible, with ColdFusion, to change something once the page has been processed. To change something in the resultant page (hide/show a section when a button is clicked, display a pop-up, etc.), you'd need to use a client-side scripting language like JavaScript. We'll talk more about that subject in future posts.

"Hello world!", ColdFusion style

Once again, the "Hello world!" example will allow us to demonstrate the basic principles behind a programming language. To achieve this, we'll first see how we can declare and set a variable. We'll then output it's value back to the result page.

This post assumes that you have a ColdFusion environment available that will process your .cfm templates. If this isn't the case, you first need to download and install ColdFusion. Luckily, there is a nice, free developer edition available on the Adobe site.

Start by creating a new ColdFusion template in your webroot. Let's call it helloWorld.cfm. In this file, we're going to start by placing a new HTML page.


	

		Hello world!, ColdFusion style

There's nothing really special about it yet. If you can point your browser to the page all you'll see is a blank page with the provided title. Now, to set a variable in ColdFusion we need to use the <cfset> tag. This tag accepts only one attribute, which is the name of the variable we want to declare. The attribute's value will become the new variables value.

Once the variable is set, we can come back as often as we want to change it's value with additional <cfset> tags. Place the new <cfset> tag inside the body of our template:


	

		Hello world!, ColdFusion style

If you point your browser to the page once again you'll still see a blank page. That's because all we've done is set the variable. We still need to output it. The way to identify that we're referencing a variable, when we're amongst other text, is to surround it with hash (#) signs:


	

		Hello world!, ColdFusion style

	

	

		

		Say hello: #outputString#

Here's how that looks in the browser:

Say hello: #outputString#

The reason the variable wasn't replaced by it's value is because, generally speaking, ColdFusion doesn't bother parsing text that isn't part of a ColdFusion tag. However, there's a very easy way to force ColdFusion to look at our text: the <cfoutput> tag.


	

		Hello world!, ColdFusion style

	

	

		

			

			Say hello: #outputString#

And we finally get our expected result:

Say hello: Hello world!

Things to watch out for

In it's simplest form, the <cfoutput> tag looks for hash signs within it's content, and replaces variables by their value. What happens, however, when you actually want to write out a hash sign to the browser (say, for a telephone number)? If ColdFusion sees a lonely hash sign it'll throw an error. Luckily, escaping in ColdFusion is super-easy (escaping is the process of removing the special nature of a character): you double it. You need to output a hash sign? Put two of them together!

Enter your telephone ##

Becomes:

Enter your telephone #

The process is the same for pretty much all the other special characters in ColdFusion.

This post took a little longer than intended. Hopefully I haven't crammed too much into it. There's more to cover, but that'll be for another day.

The train keeps-a rolling.

Beginner's Guide Series - Basic CSS

Sun, 10 May 2009 11:25:00 -0500

I know I'd promised that the next post would be about ColdFusion, but I guess I forgot to take a look at my list: what I want to talk about first is Cascading Style Sheets (CSS).

What is CSS?

CSS is used to "style" your HTML page. Where HTML defines the structure of your document, CSS gives it a look and feel. It can be used to change the font of the document or of a specific element. It can also change colors, apply backgrounds, modify layout, change size and more. It's a series of rules that apply changes to the different elements of the page.

Declaring rules

There are three places where we can define these rules. The first and simplest way is inline with the element. Say you want to change the font size of the text within a particular paragraph. We'd do this by using the HTML style attribute. This attribute can be placed in any HTML tag, and simply defines the CSS styles to apply to that specific element:

This is some text with the default font size.

The text in here should be 14pt.

The result:

This is some text with the default font size.

The text in here should be 14pt.

A CSS rule is made up of two parts: the property and the value. They are separated by a colon (:). The semi-colon (;) at the end of the rule is optional, although it becomes mandatory if you want to declare additional rules within the style attribute.

The other two places are in the header of our HTML document. One of them has the rules in the actual page, whereas the other one has the rules in an external file, called from within the HTML page. To define the rules from directly within our HTML document, we need to add a <style> tag inside the head of the document:


	
	

		Learning CSS

We could place as many rules as we'd want within that tag. However, we can also keep our style information inside a completely different file. To call it from our document we use the <link> tag:


	
	

		Learning CSS

The rel and type attributes are standard. The href tells the browser where to retrieve the CSS information from. You can specify the location the same as with images. In the .css file, you do not need to start with the <style> tag; you only need to write down your rules.

In both cases, however, since we aren't directly declaring the rules in the element we want to style, we need to have a way to reference it. Luckily for us, there are three ways to reference elements from within a CSS declaration:

All elements of the same type (ie.: all paragraphs (<p>));
All elements of the same class (more on this later);
The single element with the provided id (also more on this later).

The first way is pretty simple. We want to change the default font size for all paragraphs. To define a series of a rules, all we need to do is place the element we want to style, open up some curly braces ({,}) and start styling:

p {
	font-size: 14pt;
}

Within the curly braces we can put as many rules as we want:

p {
	font-size: 14pt;
	font-family: Arial;
	color: red;
}

The second way applies rules to elements with the certain class. This is a way of regrouping elements (not all necessarily of the same tag) so that we can quickly apply certain style rules to them. This is done by using the class HTML attribute with the elements we want styled.

Just a regular paragraph.

Make me smaller!

I want to be smaller too!

When you want to reference elements of the same class in CSS, you simply need to use the name of the class, preceded by a period (.):

.smaller {
	font-size: smaller;
}

Here's how that looks like when it's all put together:

Just a regular paragraph.

Make me smaller!

I want to be smaller too!

The last way is by referencing an element with a specific ID. The id attribute is used to give a specific identity to an element. This ID can then later be used by CSS and JavaScript to reference it directly. To reference an element by it's ID in CSS, we precede it by a hash sign (#):

#title {
	font-size: 20pt;
}

And in the HTML, we simply use the id attribute to distinguish it:

Welcome to my page
This is just a basic paragraph.

The result:

Welcome to my page

This is just a basic paragraph.

There are loads of possibilities. It would take far too long to list out all available properties here, but luckily the w3schools site is a really great reference.

Beginner's Guide Series - Basic HTML, part 3

Fri, 08 May 2009 16:16:00 -0500

In this last part for basic HTML, we'll be looking at generating a table. Tables, in HTML, are used to display data. It can be a report. It can be a list of people and their related information. It can be, well, a lot of things. It should not, however, be used to create the layout for your page. There are much better and more convenient ways to do that, which we'll see in a couple of sections.

The tags

Tables are represented by a collection of tags. As such, they are one of the most complex aspects of pure HTML. Luckily, it's not really that bad, and once these are mastered everything else should be pretty easy. Here are the basic tags for tables in HTML:

<table>: This is the outer tag. It encloses the entire table;
<tr>: This represents a table row. It's inside the table and contains all the cells for that row;
<th>: This is a column header. It is contained within a table row;
<td>: This is an actual cell. It is contained within a table row.

There are other tags available for defining tables, however they are not within the scope of this entry. For now, we just want to be able to design a table and output it in the browser.

Like I wrote earlier, tables are a relatively complex object. Like lists, we need to nest a couple of tags to get the desired result:


	
		Column 1
		Column 2
	
	
		Row 2, Cell 1
		Row 2, Cell 2
	
	
		Row 3, Cell 1
		Row 3, Cell 2

Column 1	Column 2
Row 2, Cell 1	Row 2, Cell 2
Row 3, Cell 1	Row 3, Cell 2

Here's how that looks like:

Column 1 Column 2

Row 2, Cell 1 Row 2, Cell 2

Row 3, Cell 1 Row 3, Cell 2

Column 1	Column 2
Row 2, Cell 1	Row 2, Cell 2
Row 3, Cell 1	Row 3, Cell 2

You can see we have three distinct rows, each identified in the code with a <tr> tag. In the first row, we've defined headers with <th>. In the other two rows we've used regular cells with <td>. Notice the first row's cells are in bold text and are centered. This is how most browsers output <th> tags.

One of the neat things we can do with table cells is merge them. Using the colspan attribute, we can tell a cell to span more than one column. Let's take the previous example, and modify it so there is only one header cell.


	
		This is a header
	
	
		Row 2, Cell 1
		Row 2, Cell 2
	
	
		Row 3, Cell 1
		Row 3, Cell 2

This is a header
Row 2, Cell 1	Row 2, Cell 2
Row 3, Cell 1	Row 3, Cell 2

This is a header

Row 2, Cell 1 Row 2, Cell 2

Row 3, Cell 1 Row 3, Cell 2

This is a header
Row 2, Cell 1	Row 2, Cell 2
Row 3, Cell 1	Row 3, Cell 2

The colspan attribute can be used in both <th> and <td> tags. Another nice feature is making a cell span over multiple rows. Let's take the first column for rows 2 and 3 and merge it:


	
		This is a header
	
	
		This is a merged cell!
		Row 2, Cell 2
	
	
		Row 3, Cell 2

This is a header
This is a merged cell!	Row 2, Cell 2
Row 3, Cell 2

This is a header

This is a merged cell! Row 2, Cell 2

Row 3, Cell 2

This is a header
This is a merged cell!	Row 2, Cell 2
Row 3, Cell 2

Notice I had to remove a cell in row 3. Since the first cell in row 2 spanned two rows, there's less space for cells in row 3. Again, the rowspan attribute can be used in both <th> and <td> tags.

There are plenty of other things we can do with tables in HTML. We'll get back to it in another episode. However, that'll have to wait, as starting in the next post we'll be looking at basic ColdFusion.

Stay tuned...

Beginner's Guide Series - Basic HTML, part 2

Thu, 07 May 2009 18:40:00 -0500

Yesterday, I talked about what HTML is and what an HTML document looks like. In part two of this section we'll cover general HTML tags, what they represent and how they are used. Remember, these can be placed anywhere between the document's <body> tags.

The paragraph: <p></p>

One of the most-used tags in HTML is the paragraph. This tag is used to separate text in blocks. Very easy to use, it comes with a built-in margin to space out the text.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum placerat lorem vel arcu convallis pellentesque. Nullam nunc orci, ornare ut suscipit vitae, fermentum id tellus. Aliquam erat volutpat. Nullam nec.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque lectus urna, bibendum quis eleifend quis, mattis ac velit. Aliquam ac tellus vel tortor mollis fermentum ac et orci. In sagittis.

Here's how that looks like once output to the screen:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum placerat lorem vel arcu convallis pellentesque. Nullam nunc orci, ornare ut suscipit vitae, fermentum id tellus. Aliquam erat volutpat. Nullam nec.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque lectus urna, bibendum quis eleifend quis, mattis ac velit. Aliquam ac tellus vel tortor mollis fermentum ac et orci. In sagittis.

The line-break: <br />

When all you need is a line-break and a paragraph is simply too much, you can always turn to the <br /> tag. In HTML, all kinds of whitespace (spaces, tabs, line-feed, etc.) are displayed as a single space. What that means, amongst other things, is if you try writing something like this:

This is some
really cool text.

What you'll actually get will look like this:

This is some really cool text.

The easy way around this is to place a <br /> tag where we'd normally enter a normal line-break (the enter key):

This really cool text

will actually work.

Using the appropriate tag to force a line-break we get the following result:

This really cool text
will actually work.

You might be wondering why I'm using the forward slash for this tag. Modern day standards for HTML require that every single tag be closed. Since the <br /> tag isn't put around anything else, we don't normally use the closing </br> tag. However, there's a shortcut. Placing a forward slash before the closing chevron allows to open and close the tag in one move. Practically speaking, however, <br> and <br /> are equivalent, although the example with the forward slash is more standards-compliant.

Headers: <h1> through <h6>

Headers are used to highlight new sections or particular elements. The difference between the six versions is the size of the text (<h1> is larger than <h6>)

h1 sample output
h2 sample output
h3 sample output
h4 sample output
h5 sample output
h6 sample output

And the result:

h1 sample output

h2 sample output

h3 sample output

h4 sample output

h5 sample output

h6 sample output

Lists: <ul> and <ol>

Lists are used to enumerate items. In HTML, there are two types of lists: ordered an unordered. The difference is that ordered lists will display numbers next to each item, while unordered lists will use bullets. The <ul> and <ol> tags and their corresponding closing tags define the start and end of the list. Each element will be enclosed within them, and be identified by <li> tags (list item).


	Item 1
	Item 2
	Item 3
	Item 4



	Item 1
	Item 2
	Item 3
	Item 4

The example first shows how to prepare an unordered list, and ends with an ordered list. See the difference below:

Item 1

Item 2

Item 3

Item 4

Item 1

Item 2

Item 3

Item 4

The nice thing is you can nest lists, too. This would allow for further indenting.


	Item 1
	
		Item 2
		
			Sub-item 1
			Sub-item 2

Item 1

Item 2

Sub-item 1

Sub-item 2

Links: <a>

Up until now, all the tags we've used have been pretty simple. The two next ones require a little more information. The first we'll look at is the link. Links play a really important role on the internet. They're what makes pages relate to each other. To create a link, we need two things: where the link will lead to and what text to display. The displayed text is enclosed between a start the end <a> tags. However, we also need to tell it where to go once it's clicked. We do this using an attribute.

Attributes are a series of extra information that we can add in a starting tag. You can have more than one attribute per tag (simply separate them with spaces). Here is the <a> tag with it's main attribute, href (hypertext reference):

Click me!

Click me!

There are two different ways of linking to a page: absolute and relative. Absolute means that you provide the entire address for the page, including http://. This is useful when linking to an external site. A relative link only needs to provide the location of the page relative to the caller. Imagine a page in the root of the web server. That page (page-a.html) has a link to another page (page-b.html) in the folder sections:

Site root
- sections/
  - page-b.html
- page-a.html

Our link would only need to provide sections/page-b.html in the href attribute to link to page-b.html.

Images: <img>

The image tag allows to, well, show an image in the browser. It has three major attributes:

src: location of the image file (absolute or relative);
width: the width of the image, in pixels;
height: the height of the image, in pixels.

The src attribute is pretty self-explanatory (see the link section above for more information). The width and height tag, however, are important as they provide a way for the browser to create a placeholder for the image. In a situation where the image cannot be found (either because it was renamed, or the server providing it is down) or there's a delay in downloading them, the layout of the page will be exactly as it would if the image was loaded. Without specifying the width and height the browser will only reserve a small space for the image, and expand to the actual size when ready. Since we don't want our page layout to jump around during loading, we're better off specifying the width and height in the image's attributes.

You have to be careful, though, when specifying the width and height of your image (notice I changed the width):

That's it for this episode. I'll have a little more HTML goodness for another post, and then we'll take our first look into ColdFusion.