One of the things I like about CFWheels is that its based on sensible conventions. If you follow these conventions, they can really save you a ton of time writing boiler-plate code as well as configuration. Working synergistically with these conventions are a lot of helper methods that will also reduce the amount of code you have to write as well as keeping your application DRY (Dont Repeat Yourself).
I am working on some new features for SplashCMS and ran into a situation that helped clean up quite a bit of code in some of my views and I thought it warranted a little example to show how nice this feature really is.
I have several places where I want to display a list of snippets in this application. Normally you would just write this code in each of the views that display the listing:
Not really a big deal I know. Pretty simple code to display a small list in a table. But consider this, if you do this 2 or 3 times for each different type of list you have, that could really start to get unruly in a hurry. So to help us keep our views as DRY as possible, we can leverage a feature in CFWheels called partials.
Partials can best be described as CFINCLUDE on steroids. They work exactly like a CFINCLUDE in their simplest form but, are pretty cool in the fact that they can be as simple or complex in functionality as you need. In order to keep things as simple as possible for this post we will simply look at how using a Wheels Partial over a CFINCLUDE is beneficial for our situation and will delve further into some of their more powerful features in another post.
So, in order to keep from repeating ourselves and having as little code as possible in our app, lets look at how we can simplify this. Since we know we are outputting a list of snippets thats returned in our query, we can strip out the code thats used in each view and place it into a partial named the same as our query. By doing this, we are going to take advantage of one of the features of partials that allows us to automatically handle data being passed into it.
First lets look at the code that makes this happen and then I will explain it further.
Notice in the view file (index.cfm) how we are calling the partial and instead of passing a file name, we are passing the actual query into the includePartial() method. By doing this, we are telling Wheels that we want it to find our partial named _snippet and loop over it once for each record in the query. Pretty nice, right? We are letting Wheels handle looping over the query and including our display code for us. This is much more portable now. Any place we want to display this list, we can simply call the partial and we have only one file with display code to manage the list. This helps to DRY up our code.
One thing to note. You will notice that Im passing a query named “snippets” plural. However the file Wheels will look for is “_snippet.cfm” singular. Partials are always named starting with an underscore “_” and when Wheels evaluates the query passed into it, it knows we are dealing with a Snippet model and our models are always singular, so the convention is to use singular names for the partials as well. Just think of it like this, the partial is always dealing with only one record at a time, thus its singular.
I hope this helps explain this really cool feature of partials a bit. In my next post we will expand on this example by demonstrating how CFWheels helps you to use grouping in this same partial.