Iterate Me: Brian Klaas: Blog

cfcache Early, cfcache Often, 'Cause It's Just So Darn Easy

Thu, 02 Sep 2010 09:21:00-0400

Each new version of ColdFusion (be it from Adobe, Railo or OpenBD) brings with it a raft of new features. As a busy developer just trying to get things done, it's easy to skip over most of the new features and use what you've always used. I'd like to share a brief story about the <cfcache> tag in Adobe ColdFusion 9 and why it's the one tag in CF9 that you should start using now. Improving performance is always an issue, regardless of the technology you're using to build and deploy Web sites. I ran into an issue yesterday where a tool that had worked just fine suddenly began to experience significant slowdowns. The tool is for managing groups of students in classes. Normally, a class will have 3-7 groups of students. In two cases, relatively large classes (100+ students) needed to divide students into groups in multiple ways. In one class, they ended up with 42 different groups of students. In the other, they ended up with almost 100 groupings. With this many groups, the main listing page of all groups in these courses started to run quite slowly. Response times dropped from a couple of seconds to 40+ seconds. After a brief investigation, the issue was that core information about the class was being retrieved for each and every group on the page. The core information about the class included quite a bit of information, usually returned in approximately 420ms, and the increase in repeat calls to get this information was really slowing things down.

I'm not going in to the discussion of using queries or structs instead of business objects for performance reasons at this point. Refactoring the course data retrieval service to return a simple struct or query would definitely improve performance, but a) that's not what this post is about and b) would involve mucking with core business objects and that's not something I wanted to do given the need to quickly address the situation.

Repeatedly retrieving the same data from the data source is costly and foolish. A quick solution to the problem was to cache the required data and use that cached information instead. As the core information about a course doesn't change very often, I could cache this information for 5 minutes with no problems and get a nice performance boost. Until CF9, you couldn't cache objects without rolling your own struct-based caching code. In CF9, though, the <cfcache> tag makes it super easy to cache objects, page fragments, query results, or whatever you need. As this call to get the core course information was being made a number of times in the same CFC, I refactored this call in to a private function. Here's the code:

The key to this function are the cacheGet, isNull, and cachePut functions. You use cacheGet(itemName) to put something in to the cache, and cacheGet(itemName) to get something out of the cache. Super simple, right? This function shows off some of the issues you need to be aware of when using CF9's built-in instance of Ehcache.

I've been asked "How do you make sure you have a unique name for the item you want to put in the cache and how do you remember that unique name later when you need to get the item from the cache?" The first cfset line takes care of that. It's convenient to generate the name for the item in the cache using a key value associated with that item, like courseID. You just have to make sure that no other item anywhere in the cache is going to have the same name.
You need to check to see if an item in the cache exists, otherwise how will you know to use the cached item or put the item in the cache? That's what the cacheGet(courseNameInCache) and the isNull(cachedCourseInfo) calls do. You first try to get the item out of the cache. If it exists, great! If not, CF will return a null value for the item in the cache. If you get a null value for the item in the cache, you need to put the item in the cache.
If the item isn't in the cache, you need to generate the item and then put it in the cache via cachePut(itemName). Again, be sure to make your item names unique!
If the item is in the cache, return the cached version of the item.

One concern that's often raised about using the default <cfcache> setup in ColdFusion 9 is that items put in the cache are put in the JVM along with everything else that ColdFusion puts there. As such, the items you cache will take up some memory, along with the CF runtime, your application code, items in persistent scopes (server, application, session), and objects generated on a per-request basis. However, in many cases, you're going to be caching items that take up 1K of memory or less. That means it'll take about 1000 items in the cache before you use 1MB of memory. Unless you are caching really big data sets using <cfcache> or expect that you'll have hundreds of thousands of items cached on a server with limited memory, this generally won't be a problem and you shouldn't let caching items in memory scare you. (You can configure CF9 to use a separate, standalone instance of Ehcache, should you so desire.) To wrap up my little story, the end result of taking 15 minutes to write up this simple caching function, run my unit tests, and deploy the change was a reduction in page load times from 40+ seconds to under two (2) seconds. That's an excellent improvement for so little work.

The Best Online Guide to the ColdFusion Debugger

Mon, 16 Aug 2010 08:08:00-0400

Charlie Arehart is an indefatigable contributor to the ColdFusion community. He always manages to dig through the dark and unexplored corners of CF and CF-related products, and comes up with some excellent gems and insights along the way. One area of ColdFusion development that still remains something of a black art to me is getting the debugger in ColdFusion Builder (or, previously, CFEclipse/Eclipse) up and running. The official CF docs aren't particularly great on this front. While they give you the basics of setting up the debugger, they don't cover all the little details and gotchas that can make getting the debugger to run seem like the darkest of Dark Arts. Today, Charlie posted an awesome, detailed guide to setting up and using the ColdFusion Debugger. It's in a PDF which contains three chapters from the ColdFusion 9 Web Application Construction Kit, Volume 2, that weren't included in the final version of the book because of page count limitations. I've read a number of blog entries, the official docs, and even a Fusion Authority guide to using the debugger in CFBuilder, but none are as clear or detailed as Charlie's guide. He covers the issues with setup (especially if you're on a multi-server install or debugging against a remote server) and the details of the sometimes persnickety debug session itself. It should be your first (and probably only) read if you want to get started with CF debugging. If you download the PDF, you also get a chapter on Globalization and one on Error Handling. Sweet!

Setting Up SSL for Local Development on Mac OS 10.6

Fri, 06 Aug 2010 15:56:00-0400

I spent the better part of the other morning reading various Web entries about setting up SSL on a local development machine running Mac OS 10.6. If you build sites that utilize SSL, it's sometimes valuable to be able to test this functionality locally, especially if you have events in your Web app that switch from SSL to non-SSL connections. The resource I found that finally got everything working was Larry Ullman's blog post "Enabling SSL on Mac OS X Leopard." Everything posted there works for 10.6 (Snow Leopard) as well as 10.5 (Leopard). The same couldn't be said for other blog posts and, unfortunately, some of the tips on MacOSXHints.com. Note that you don't need to install MAMP or MAMP Pro to get things working. If you're developing with ColdFusion, there's no real need for MAMP as 10.6 (and 10.5 before it) come pre-installed with Apache. You just need to install a CF server. As Larry and the author of the Apple article which Larry references both note, you're not making a real, valid SSL certificate here. You're going to have to tell Safari/Firefox/Chrome that it's OK that you can't validate the authenticity of your localhost site.

On App Inventor: Speaking the Language of Novices

Mon, 12 Jul 2010 09:08:00-0400

Google's App Inventor is a great idea. Empowering consumers to create is always a good thing. Visual Basic was the key to Microsoft's long-time success. Map making tools are the reason why Warcraft III and Starcraft still sell on retail shelves, more than a decade after their release. iMovie, Windows Movie Maker and its counterparts have helped make YouTube the site for almost every Web meme of the last five years. Visually-oriented IDEs are a great way to develop software quickly. Visual Basic and Delphi are two classic examples of this, and their tradition of partial WYSIWYG views carries on to Visual Studio and Flex Builder today. (I've also made the argument that if Adobe wants CFBuilder extensions to really take off, they need a visual UI to create them.) They've even evolved to have a similar visual language: panels spread out on the screen which allow for inter-panel communication and interaction, playing off visual and interaction patterns common to many IDEs. When you fire up Eclipse or Visual Studio, you, as a programmer, can say "Oh, I know the basics of how this IDE works because it looks like other IDEs I've worked with." All of those tools, however, expect that the user has some kind of fundamental understanding of the basics of programming: simple data structures, simple logic controllers, and so on. You simply can't get by without them. Now let me say that I've had minimal direct experience with Google's App Inventor. I don't think that's a problem here because I want to talk about first impressions, as those mean a lot to the average, non-technical user at whom Google is targeting the product. Take a look at this screenshot from the product's home page: The focus of the UI is on the simulated phone screen in the middle of the window, as it should be. Take a look at the list of controls under "Palette," on the left. There you'll see titles for controls such as "Canvas," "ListPicker," and "TinyDB." Although there is a question mark next to each which, when clicked, tells the user what the control is, that text (and other text on the screen) is very much the language of the programmer and not the user. A non-technical, non-programmer, average, everyday Android phone user (who is the target user of App Inventor) would probably look at that and say "What the heck is a ListPicker?" I've worked with a lot of "non-technical, non-programmer users," and know pretty well that when any "programmer-ese" comes in to play in the UI, users tend to be taken aback and almost immediately take a combative approach to this UI written in a language other than their own. This programmer-centric language works its way in to other elements in very subtle ways. Look at the properties you can manipulate in the "Components" and "Properties" panels. The text which describes the properties you can manipulate, while clear, is written in camel case — a programmer's, not average user's, convention. "CheckBox1" could just as easily have been displayed as "Check Box 1." The same goes for "BackgroundColor" and "BackgroundImage." I know this sounds trivial, but it's clearly the work of programmers who expect that users will get or, at least, grow accustomed to the way software is written by programmers, not "average end users." I also have to wonder if the basic assumption of the standard IDE UI as the default UI is an appropriate one. In my experience, users are task-focused. They want to be able to make a movie from video on their camera and upload it to YouTube. They want to write a letter to their congressman about an issue that is important to them. They want to set up a quiz for the students in their class to take. As users are task-focused (and not document focused), an application should start with smart defaults and help a user accomplish basic tasks quickly. Instead of showing the standard IDE UI at startup, App Inventor may be better served with a "Start Screen" which could ask:

What kind of application would you like to build?

One that uses data from my Twitter account.

One that uses maps to display places that are important to me.

One that lets me chat with my friends.

None of the above.

The options presented here, when selected, would then pull together some of the basics for the application, saving the "average user" quite a bit of time and lay out most of hte plumbing required to get their desired application off the ground. This "Start Screen" could be turned off in the application's preferences for user who don't want to be bothered with this kind of getting started page. The blocks tool that the team has devised to map out the internal logic of the application is really smart. It makes visualizing the logic clear and it's easy to drag and drop components in to the right order. No-code development environments like this are key to getting "average users" to use the tool to create applications that do what they want. I've used "average users" in quotation marks throughout this entry. That's because I don't think the real audience is "average users" — meaning someone who owns a smartphone but hasn't developed software before. The tool was developed by university-level faculty and targeted towards students at various levels (elementary, middle, high and university) but in the context of teaching software development. As such, I believe the tool makes the fundamental assumption that you have to have some knowledge of the art of programming. That assumption informs the design of the UI and how users interact with it. It makes it vastly simpler for individuals to develop applications (even me!), but it's not a tool that can be used by just anyone with experience with smartphones. App Inventor was created by a lot of people much smarter than I. It's also still in beta and something I know that the team will improve upon over time. I just have to point out that if they really want to create something which allows the average user of a cell phone to build their own applications, they need to create a UI that, from start to end, reads in the way that an average, non-programmer user would understand.

How My iPad Has Unexpectedly Replaced My Desktop. Sort Of.

Mon, 24 May 2010 08:53:00-0400

I'm fortunate enough to have been given an iPad by my employer for R&D purposes. I certainly wasn't looking to buy one on my own. I have an iPhone, which I think is a fantastic mobile computing device (yes, even though most of my software development work is done using Adobe's tools — we're allowed to live in both camps, if we want, you know). I didn't see the point in the iPad. I also happen to have a PowerMac G5 that I purchased in June 2004 as my primary desktop computer at home. It's a bit old and underpowered now, but it still does the job. I even play and raid in World of Warcraft using that box. That is, until the weekend before last. That Saturday was the day that my video card decided to completely blitz out, making any display rendering almost totally unusable. I can still perform certain tasks on the computer, but that's mostly through muscle memory and deep recognition of application windows. The display is largely illegible. I've cleaned the card, using pressurized air to blow off every spec of dust off the card, to no avail. Because the machine is so old and because replacing the card will set me back about $350-400 (because the machine and the cards for it are so old), there's no good reason not to replace the machine. The iMac line (which I'd buy from to replace this desktop) is nearing the end of its current cycle and due for a refresh. I don't want to buy a new iMac only to find the line refreshed in the next 14 or 21 days. I can only go for so long without a desktop at home, so what to do? My partner has been gracious enough to let me play WoW on his computer (in spite of the fact that he intensely dislikes the game and the years of late nights I've spent as a raid leader). That's one problem down. I don't do a lot of digital photography or video, so there's no urgency there. I can still buy music and apps via iTunes because I can kind of make things out on the screen on my desktop (though I'm sure I'll soon buy something I did not want because of this on-screen guesswork), so that's another problem that's handled. But what about my daily Web browsing activities, and shopping, and email? Enter the iPad. I've been remarkably surprised at how well the iPad takes care of my consumption activities on the Internet. Between regular old Web sites and specialized apps (like a news reader for my 150+ RSS feeds or LogMeIn Ignition for remote desktop control), I've not had to give up much in terms of going about my normal Web consumption activity on my iPad. I don't play Farmville (or any Flash games), and most movie trailers I watch are in QuickTime, so I don't miss Flash too terribly. It's easier on the eyes than my iPhone, and the increased physical space and gestural flexibility make it a better choice for my daily Web activities than the iPhone. But I can't run Eclipse, so no development work for me. If I need to do some management in Adobe Connect (or teach using Connect, for that matter), I have to turn to my partner's desktop. If I ever get around to making a DVD of my family's videos from our 2009 African safari, it's not going to happen on the iPad. And I still need to connect to my desktop in order to sync my iPad (or iPhone). I can download music and apps over WiFi, but I'd like to have everything backed up so when I do move to a new machine it's all seamless and stuff. (That part of the process once again shows that Apple should cut the cord between their mobile devices and the desktop — in spite of the halo effect and the extra sales they get from it — and take a cue from Google's Android 2.2 OS and push cloud sync front and center.) As many critics have pointed out, the iPad is not a good creation device on a number of fronts (software development being a big one), but it's a pretty damn fine device for consumption. No one complains that you can't develop desktop/mobile/Web apps on your XBox 360 or PlayStation, now do they? Having used the iPad for a few weeks now, I can easily see how it will replace an extra computer in the house, or two. I can see how it will eventually grow in to a device for creation and consumption (though I think consumption will be its primary focus for a number of product iterations). It lacks the power and flexibility of my desktop, but like all things technological, isn't that just a matter of time?

Mach-II Modules Don't Automagically Inherit ColdSpring Configuration

Fri, 16 Apr 2010 13:01:00-0400

This is probably obvious to anyone who's spent time with Mach-II and ColdSpring, but I ran in to the issue the other day, spent about an hour missing the obvious, and thought I'd post. If you have a Mach-II module, are using ColdSpring to manage dependencies in the parent application, the Mach-II module won't automatically inherit the ColdSpring setup. I had begun work on a simple module that didn't have any of its own objects to be managed by ColdSpring but instead would exclusively use objects managed at the parent application level. So I went about setting up a simple "home" view which needed some data from an object managed by ColdSpring in the parent app, and made a <call-method> command to it. I received an error stating that the bean I was looking for couldn't be found. "Well that's not right," I thought. "I know the bean is in the parent app and other parts of the application are calling it just fine." After an hour or so of debugging, thinking that someone had broken the object in the latest build of the application, and getting a little annoyed, it dawned on me that I had never set up the ColdSpring property in this child module. Without the ColdSpring property being defined in the module, Mach-II had no idea how to call the bean I had specified in the <call-method> command. So if you are creating a module that has no ColdSpring-managed objects of its own, but do want to use ColdSpring-managed objects in the parent application, you still have to set up a basic ColdSpring Mach-II property in your module, and point it to an (essentially) empty ColdSpring config file. Your ColdSpring config file can look like this:

Once that is in place (and as long as you also define the parentBeanFactoryScope in your module's ColdSpring property CFC), your module will have access to all the ColdSpring managed objects in the parent application.

Yes, Apple Really Is Out to Obviate Flash, But They Do Listen to Customers (Sometimes)

Fri, 09 Apr 2010 08:06:00-0400

If you haven't heard, John Gruber at Daring Fireball has the lowdown on Apple's pointed attack on Adobe and Flash in particular in the iPhone 4.0 license agreement. The key point: Apple has basically banned the use of tools like the Flash -> iPhone packager that is a key piece of Adobe's flagship Creative Suite 5, set to launch on April 12. The bits are finalized, the discs are being burned and pressed as I write this, and a marquee feature of the suite has just been rendered null and void by a change in Apple's licensing agreement. While I'm more on the HTML5/JavaScript side of the fence than the Flash side of the fence when it comes to building rich internet applications, there's a lot of great stuff that Flash can do that HTML5/JavaScript simply cannot. It's not just about video. It's about the applications that can be built. For now and the foreseeable future, Flash makes it drop-dead easy to build multi-user, rich media applications. It's a shame that those apps won't be able to make it on to the iPhone, or the iPad. While the change in the licensing agreement also affects Mono (.NET) -> Objective-C and other similar converters, it seems like the result of the will of one very powerful and very gifted individual who has exercised his power to reshape the landscape of the Web. It's feels mean, but that's business sometimes, isn't it? (See Gruber's most recent post on the issue for the business reasons (alas, logical) why Apple made this change.) On that note, there was something that struck me in the iPhone 4.0 SDK announcements yesterday which I thought was interesting from a UI perspective: the inclusion of folders in the iPhone UI. While Apple's products (and team) are extraordinarily opinionated, and those opinions are rigorously thought through, I found it surprising that an "old" desktop metaphor found its way back in to the iPhone/iPad UI. With Apple's very clear attempt to break from the desktop UI of files and folders in the iPad, and their reluctance to introduce any kind of hierarchical organizational system in to the iPhone SDK in previous iterations, the return of folders was surprising. My guess is that folders returned for a very simple reason: it was the choice that made the most sense to their users. While Apple may appear arbitrary and capricious, they listen very, very carefully to their users when it comes to designing the experience. They probably iterated through a number of organizational ideas and most likely came back, time and again, to a simple, obvious, universally understood idea: the folder. Rather than forcing something new and unfamiliar to most (ie; stacks), they said "Simple and already understood, if not radical and new." So Apple does listen to their customers. Sort of. Sometimes.

Bug with Multiple <cffileupload> Controls and Different onComplete Handlers

Wed, 10 Mar 2010 09:35:00-0400

A co-worker of mine has been bashing her head against a wall in recent days trying to figure out why a view with multiple <cffileupload> controls wasn't behaving properly. No matter what she did, a page with multiple <cffileupload> controls that also specified a different onComplete handler for each control always caused the last onComplete handler to be fired. She even made sure to have unique names for each file upload control. It turns out that this is a completely reproducible bug in ColdFusion 9. Here's how you can replicate this bug:




	
	cffileupload Bug Test
	


Upload One, calls uploadOneDone() when finished.


Upload Two, calls uploadTwoDone() when finished.

You'll need a file called upload.cfm in the same directory as this test page. It can be as simple as:

Upload a file using the first uploader on the page. Here is the result you'll get:

The last onComplete handler is fired, no matter how many of the controls are added to the page. Maybe we're doing something wrong here, and if we are, I'd love to know. In the meantime, I've opened this as bug #82396 in the ColdFusion bug tracker. Feel free to vote for it!

Mach-II Call Method Command, How Do I Love Thee?

Fri, 19 Feb 2010 10:34:00-0400

Now that Mach-II 1.8 is out, I figured I'd write a little bit about one of my favorite new features of the release, the <call-method> command. Here's the problem that this new feature is designed to solve: In a well-designed Mach-II application, you don't want to have a lot of business logic in your listeners. As a result, a lot of the methods in Mach-II listeners wound up being simple pass-throughs to a method in the service layer. This was repetitive, and tedious. Here's an example:

We had to write a function that simply called a service layer method and returned the results. It's not hard to do. It is, however, clutter. The <call-method> command eliminates the need for these kinds of placeholder method calls in your listener. Now you can do this in your Mach-II XML configuration file:

The "bean" referenced in this tag is a ColdSpring-managed bean that has already been auto-wired by the ColdSpring property in Mach-II. So this feature only works if you are also using ColdSpring (and — I've said it many times before — if you're not using ColdSpring or some other IoC container in your ColdFusion applications, you're costing yourself time and money.) By using the <call-method> command, you've turned four lines of code into one. Not bad! What if your service layer methods require arguments to be passed to them? That's easy, and Mach-II handles this.

The args attribute of the <call-method> command can take single or multiple, comma-separated values, or even an argument collection structure. But what's the ${ } syntax? That's the expression language syntax that's built in to Mach-II. This feature arrived in Mach-II 1.5 under the name "Bindable Property Placeholders," and has evolved since then and is even more useful. It allows you to provide variables evaluated at runtime within the Mach-II configuration file. You can even provide default values in case the variable you're looking for in the expression doesn't exist (ie; ${event.userID:0}). So in the example above, it's going to to pass the result of evaluating event.userID (getting the value of the userID variable in the current event) to the userService.getUser() method. I'm using the <call-method> command in my latest project using 1.8. It's saving me time, makes the event flow as defined in the Mach-II XML config file clearer, and eliminates a duplicate layer of abstraction in the app. The official documentation for the <call-method> command can be found in the Mach-II wiki.

Why the Mac OS X 10.7 UI Will be the iPad UI

Sun, 31 Jan 2010 08:52:00-0400

I don't work at Apple. I have absolutely no evidence for this. This is pure speculation, but after processing the iPad announcement and the vortex of commentary about the iPad, I had an idea, and wanted to write it out. The next major version of the Mac OS (10.7, or maybe 11) will likely adopt the iPad UI as its default UI. Here's why: First, if you haven't read Steven Frank's commentary about Old vs. New World Computing, you should. It strongly influenced my thought path. Steven makes some excellent points about customer expectations when it comes to "new world" computing. Apple has made it very clear that they are becoming a mobile computing company. The company derives a majority of its revenue from iPods, iPhones, and laptops. Revenue from desktop sales accounts for less than a quarter of their overall revenue. The biggest area of growth they've had (and are going to have) is in the mobile sector. This is going to influence their overall direction, even when it comes to their "crown jewel": the Mac OS. Millions more people use iPods (including the Touch) and iPhones than Mac desktops and laptops. Millions of people have probably switched to the Mac due to their very positive experience with the iPod/Touch or iPhone (the "halo effect" as business analysts have called it), and that's the "Apple experience" that they are used to. The iPhone OS was/is a variation on the Mac OS. It carried a similar design aesthetic and even some of the same basic iconography (Safari, Mail) that the desktop OS used. As the iPhone and its SDK have exploded on to the computing scene, I've heard many people say (or write, or tweet) that "it sure would be nice if you could [insert some iPhone capability] on the Mac too." Functionality may be a driver for iPhone -> Mac OS UI adoption, but I don't think that's it. I think it's about the experience. The iPhone/Touch/iPad UI is super simple. You touch (essentially click) on something, and it responds. There are few, if any menus. You do one thing at a time and when you're done with one task, you move on to the next. It's hard to get lost in the iPhone UI. There are no files, no file structures, no antiquated, computing-device-from-1980-centric notions of how to get things done.

A small detour: the iPad isn't for you, Person in the Software/Hardware/Web Application Development industry. I think that's a huge point that most of the analysts, pundits and commentators on the iPad this week missed. It's not a device that's going to replace your desktop/laptop with your 200 programs that you switch between at any given time to build the next Facebook. It's a device built for my Mom. Or your Mom. It's a device built for a 12 year-old kid who wants to connect and communicate in the very simple ways that IM, Facebook and SMS allow us to communicate while they watch TV, or sit on the bus, or are hanging out with friends. It's for people who don't care about a multitasking OS, or that it doesn't support real 720/1080p video (do you think they know what that means?), or — here comes the big one — that it doesn't support Flash.
A detour from the detour: I miss Flash on my iPhone. I would like to see it on the iPad. But it's not going to happen. Ever. Apple has no business interest in making Flash run on the iPhone/Touch/iPad. John Gruber clearly explains why. And the average customer won't think that there's something wrong with the iPhone/Touch/iPad. They'll think there's something wrong with your Web site. More than a decade of using the Web has taught users that when something goes wrong on a Web site, or something doesn't work on a Web site, it's the Web site's fault, not their computer. Not their iPhone. Their iPhone just works.

Back to the topic at hand. If you buy an iPhone (or iPad) and you decide to move to a Mac from Windows, you've got another UI to learn. You learned the Windows UI, then you learned how to use the iPhone (or iPod Touch) UI, and now you've got a third one to learn. And that can be scary, and an annoyance, and a big time sink, and maybe a reason that you won't switch to a Mac desktop or laptop. But if the UI you see when you buy that Mac laptop or desktop looks a whole lot like the UI you already know (and probably really like) on the iPhone/Touch/iPad, switching suddenly seems a lot less scary. But what about the desktop? The Finder (or file system)? What about the Dock? What about having iTunes and Mail and iPhoto and Safari and iChat all open at the same time and clicking on their respective windows to quickly switch between them? One of the major areas of frustration for most users in modern desktop/laptop computing is the file system. I know this may sound absurd, but as someone who works directly with users in face-to-face training classes (and online doing the occasional support that anyone who has a job in computing technology eventually does), users still, after 20+ years, don't get how a file system works and they don't get how to organize files, and, most importantly, to find them once they've saved them somewhere. This isn't just a Mac OS thing. This applies to Windows as well (perhaps even more so in the Windows word, but that's just me being a Windows basher). Beyond storing everything in the default location provided by the OS (or on the Desktop, because that's where a user can "see" their files), most users are utterly baffled by the complexity of a file system. If the computer could just figure it out for them and find the file when they needed the file, they'd be so much happier. Why do people send and store everything via email? Because it's really simple to find what they need using their mail client's search functionality.

(Please note that I'm not saying that you, dear reader, aren't smart enough to figure out the file system. If you're reading this rather unknown blog that mostly focuses on Web application development in ColdFusion, then you probably know more than your average user about computers and file systems.)

Apple has already taken steps in the iPad (iPhone SDK) to mask the complexity of the file system by having documents for a given application stored in the installation directory for the application. According to the article in RoughlyDrafted Magazine: "Documents copied to the app's shared folder will be graphically presented by the app when it launches, sparing users from having to figure out where to look for their document files and avoiding any need to sort through different kinds of documents." Sounds like Apple has taken a giant step towards masking the complexity of the file system to me. It would be easy for Apple to offer a real, separate, standalone Finder app (not the one that still acts as the Mac OS desktop) in an iPad UI-based desktop/laptop OS for those times that anyone needs to navigate the hierarchy of the file system. If you want to get under the hood, you still could via the Finder app or the Terminal app, just like you do now. (If you reflect on it a bit, you can see the direct, clear line between the idea of the iPhone/Touch/iPad UI and the Simple Finder from Mac OS 8.) OK, so what about multitasking then? One of the great things about computers is that you can be working in 7 different programs at once if you need to and you can switch between them super easily. When was the last time you watched (not just assumed) how a non-computer/software development-centric user gets things done? Most people use their computers for one task at a time. I check my email. I search for this thing on Google. I write this in Word. I play WoW. Most users focus on a single task in a single interface and then move on to another task in another interface. There is little to no need to jump between applications to get their work done. Google is taking this idea to its logical end by making the Chrome OS run a single application: the Web browser. Everything you could/should need to do can be accomplished via the Web browser, so why have any other applications in the OS?

(And, again, as a side note for the software developers reading this: think about Eclipse. Part of the success of Eclipse as a platform is the ability to add plug-ins of myriad scale and functionality to Eclipse so that it can do just about anything you want from a single interface, in a perspective that helps you focus on the task at hand. Isn't that what tools like Mylyn are all about?)

It would be trivial, in an iPad-based UI, for Apple to allow for multiple processes so that you could listen to iTunes while you surfed the Web in Safari, or receive incoming IMs or Facebook notifications while you read your email. That's not a problem and wouldn't be an issue in an iPad-based Mac OS 10.7 UI. Apple can keep the multitasking nature of the OS while masking the complexity of a multitasking environment behind a simple, one-app-at-a-time view. Does the idea a single, full-screen view of a single application at any given time sound familiar? An operating system made by a company based in Redmond, Washington, adopted this model of computing years ago. When an application opens in Windows, the default view is for the application to expand to fill the screen. You can switch to other applications as needed (or even make them smaller so you can see multiple applications at once, like you can on the Mac OS). You are, however, focusing on a single application at any given time if you go with all of the defaults. Yes, the Start menu, like all menus, is an exception. But this is the desktop window UI that a majority of users have come to learn and expect. One of the things I see switchers from Windows to the Mac struggle with is the concept of multiple application windows being open and visible at once. If you've used Windows for a long time, you expect that when you open Word, it's going to fill the screen. Not so on the Mac. Most windows don't fill the screen (iMovie and other non-linear video editors being an exception). There are floating palettes. There's a whole bunch of stuff that quickly piles up in a single window and it's easy to accidentally click on the wrong window and bring up an application that you don't want to work with at the moment. Apple isn't shy about stealing from Redmond when it needs to. If it would make it easier for switchers to actually make that switch if the single-application-visible approach taken by default by Windows became the standard, out-of-box experience on Windows, that's a compelling argument for making that change. And that's how the iPad UI works. Apple has a business interest in updating the Mac OS (and the iPhone SDK) on a regular basis. It sells. It sells hardware. It helps them to remain competitive and gives them yet another opportunity to dance circles around the folks in Redmond. OS additions like 64-bit computing and offloading computing power to the GPU sure sound nice if you know what they mean, but it's the UI changes that are the big ticket items, the big showpieces, and the big drivers for most consumers of an OS. Saying that "we've left the UI from 1984 behind and have made a true OS for the mobile Internet era" would be a big ticket item for Apple. (If it was actually, deeply tied to the Internet and cloud storage.) Apple is, at its core, a company about the user experience. From the original Macintosh (making the arcane art of the command line go away in favor of a GUI) to the genius of using your finger as the primary interaction point between you and your computing device, Apple is about making the user experience simple and elegant. Apple doesn't care about offering 5,437 features in a single device. They care about offering 10 things that really matter, are core to getting the primary tasks of the device completed, and making those 10 things work flawlessly. If you've used the iPhone or iPod Touch, it's definitely simple and elegant. It just works. It's a really nice experience. It's the epitome of the "New World" computing that Steven Frank writes about. Why wouldn't Apple want to capitalize on that to make a simple, elegant, seamless experience from one of their devices to another? I've left out just a few minor details, like how file storage would work in an OS that masks the file system and directory heirarchy as much as possible, and how cloud integration might allow the OS to become a true "OS for the Internet" (see Apple's acquisition of Lala, their new billion dollar data center in North Carolina, and our eternal hopes for a revamped MobileMe service as indicators), but this covers the basics of my hypothesis. Enjoy!

Lessons Learned in Making Many Mach-II Modules Out of Standalone Apps

Wed, 30 Dec 2009 09:39:00-0400

This entry is about a month overdue, but given the holidays and Getting Stuff Done (SM) at work, it's been delayed. As I mentioned in my first posting in the series, I'm in the process of converting a bunch of standalone Mach-II apps in to modules inside of a new, monolithic application. It's been a surprisingly smooth process, thanks to the tools that the Mach-II framework gives us to work with. Most of the bumps along the way have been related to bad software design practices in some of the oldest apps that I've created, and continuing, after many years building Web applications, to do dumb things like hardcoding URLs and other strings which will change when converting the app to a module (or moving the app to a different server). Here are a few key lessons I've learned:

Use BuildURL and the View Tag Library generously. One of the major time sinks I've had to endure in this process is changing all of the links and constructed URLs in the apps-to-modules. If you're using Mach-II and still writing <a href>s in your views, you're throwing money out the window. Sooner or later, those URLs are going to change, and you're going to have to rewrite them. BuildURL and the View Tag Library encapsulate the creation of URLs/links in your views so that when you change servers (or need to roll out a new version of a module in a different directory), you do very little (to no) work to make the URLs/links all update nicely. And, yes, you can use them to create links in your inline JavaScript (if you use inline JavaScript).
Avoid redundancies in your ColdSpring configuration files. If you're going to share functionality across modules and you manage your object dependencies with ColdSpring, you're going to run in to instances where you define a bean multiple times in multiple ColdSpring configuration files. This is a really common situation. If you have a userService, for example, you're probably going to refer to this userService throughout the modules in your application. It's easy to define that userService in each of the ColdSpring configuration files in each of the modules that uses the userService, but don't. Simply define the userService bean in the ColdSpring configuration file at the top level of the application, and then if you inherit beans defined in the parent (top level) app as discussed in this post, you have access to that userService in your module. You don't need to define it again, and doing so is wasteful, and may lead to subtle (or not so subtle) issues when the a new version of the service is rolled out in the parent but your child is using an old version of the service because it's been define that way in the child ColdSpring config file. If your module needs a specific version of the service (eg; it needs to keep an old version for compatibility with something else), you can define it in the child ColdSpring config file as needed.
Avoid per-module session objects. This is a really easy trap to fall in to if you are porting existing Mach-II applications to modules inside a new, larger application. Most of your existing apps will have information stored in the session scope. It's tempting to keep your perfectly fine code as-is and just create new session variables as needed in each of your apps-to-modules. The problem here is that if you're creating new session variables in 7 or 15 or 22 modules, you're going to start to eat up memory and, more importantly, you're going to have to try to track down why things are going wrong in 7 or 15 or 22 session variables rather than in a single location. It's just bad form to not encapsulate everything you need in the session scope in a single variable created and managed at the top layer of your application. In all likelihood, all those redundant session variables generated in your modules largely contain the same information — userIDs, user objects, security or role-permission information, and the like. Managing this in one place makes a heck of a lot more sense than spreading it out in to each of your modules.
Handle exceptions and errors at the main app level. As with redundant bean definitions or per-module session objects, per-module exception and error handling is most often redundant. While there may be cases where you want to handle an exception in a special way in a module, there's no good reason to have different exception or error views in each module. Provide a consistent way of handling errors and exceptions for the developers behind the app and a consistent experience for the people using the app. If you want to do some module-specific handling of errors (to try to recover, to log something specific to the module, etc.), you can do this in your module's Mach-II XML config file:

<-- OR --> <-- FINALLY -->
Get rid of the extra junk. Not using all the plugin points you stubbed out in your plugins? (Or, in my case, left in there because you copied from the samplePlugin.cfc that came with the framework?) Get rid of them. No longer using that sessionFacade.cfc because you're managing your session objects centrally? Get rid of it. Get rid of everything you're not using. It's good practice and will make things cleaner and easier to understand for the poor sap who has to work on the app your absence.

So that's it for this series. I have to give major props to the Mach-II team for making it so easy to convert existing Mach-II applications to Mach-II modules. It's made this big project so much easier.

Mach-II Modules and Views

Mon, 30 Nov 2009 11:56:00-0400

It looks like I'm going to spend another Monday morning writing about Mach-II modules. In this entry in the series, I'm going to look at how your CFML-based views are affected by the Mach-II module structure. Mach-II provides a lot of convenience methods for handling views. In Mach-II 1.8, there's a whole new set of tag libraries which make tying your views to other actions in a Mach-II application even simpler. Of particular interest are the <form> and <view> tag libraries as they make dealing with mundane tasks like binding form fields to event objects and creating links simpler and more flexible under the Mach-II framework. Prior to Mach-II 1.8, there were the BuildURL() and BuildURLToModule() methods, which were your biggest friends in building links within and between modules in a Mach-II app. I realize that not everyone likes to have a framework write their URLs for them. There are issues of convention, framework agnosticism, SEO optimization, and individual style that can and often should be factored in. However, if you're using Mach-II modules or Mach-II SES URL rewriting, or the new routes support in Mach-II 1.8, it would be quite unwise to write URLs on your own. I'd argue that as you've made the investment in the framework to begin with, you should let the framework generate your URLs for you via its various convenience methods in all cases. If you ever switch domains or even move the base URL path of your application or need to swap one module for another, changing a single value in your Mach-II XML config file is going to be a lot faster (and a lot less error prone) than doing a search and replace on every <a href> in your code base. (As a side note, I've had issues with outputting BuildURL() calls within JavaScript blocks, and did use that as an exception to the above rule. However, the new buildUnescapedUrl() function introduced in Mach-II 1.8 eliminates that exception.) Using BuildURL() and BuildURLToModule() By using BuildURL() and, more relevant to this post, BuildURLToModule(), you let Mach-II handle the writing of your <a href> tags. These functions are available in views only, and not inside plugins, filters, or listeners. If you use Mach-II modules, you're going to want to use BuildURLToModule() over BuildURL() in most cases. Here's why:

BuildURLToModule() ensures that the module is preprended to the event name in the resulting URL. This ensures that the user is routed to the right module when the event is requested.
BuildURLToModule() allows for an empty module name in the module argument of the function. This lets you write events which point to the main/parent application and forces the request to go to the main/parent application.

If you just use BuildURL(), Mach-II is going to assume that you want an event in the same/current module. This works fine if you are at the top level of your application, in the main/parent portion of the application. This doesn't work so well if you're inside a module. For example, if you have an event called "logout" tied to a "Logout" link and you are inside a module and a user clicks on the "Logout" link, BuildURL() is going generate a link that looks for an event called "logout" in the current module. As the logout event is (probably) defined in the main/parent application, Mach-II won't be able to find the event in the current module, and an exception will be thrown. As a result, it's a good idea to use BuildURLToModule() instead of BuildURL() in both the parent and child (module) application views. This way, you ensure that the user is being routed to the right event in the right module, even if it's the default/parent module. This is my personal preference, and not an official guideline of Team Mach-II. Using the <view> Library The <view:a> tag is a handy way to let Mach-II write your <a href> links. It does much of what the BuildURL() and BuildURLToModule() functions have done for some time now, only in a simpler and more elegant wrapper. Now that I'm using Mach-II 1.8 to build my applications (and for this particular, module-heavy project), I prefer it to BuildURL() for generating <a href>s. I still use BuildURLToModule() when I'm not generating a <a href> tag. There are lots and lots of options when using the <view:a> tag, but the basic format of generating a link is as follows:

You simply specify the event name in the event attribute, the module name in the module attribute, and any key/value pairs you want to add to the link in the p attribute. If you have multiple key/value pairs you want to add, just put multiple p attributes in the tag, as follows:

You can put CF variable names in lieu of static values, or use the expression language syntax available in Mach-II to generate the values:

Again, you should provide a blank value for the module attribute if you want the link to point to an event in the main/parent application. This ensures that Mach-II looks for an event in the main/parent application and not in the current module. Using the <form> Library When it comes to generating form action attributes, the <form> tag library works just like the <view:a> tag. An example:

It's very unlikely you'd be doing a form post from a module back to the parent/main application. As a matter of fact, I can't think of a good use for it. It's still a good idea to specify the module in which the event exists via the actionModule attribute, however, to ensure that the link is always written properly. There's lots of documentation for the <form> tag library, so please review it to see what it's capable of. Binding, for example, is just plain useful and cool. Reducing Most of the Above to a Single Point The key point is this: no matter how you write your URLs, always make sure that a module (or an empty string for a module) is specified. This will ensure that event requests are routed to the right place. Start doing this when you begin to build your views, and you'll find it saves you time down the road when you're connecting everything.

Mach-II Modules and ColdSpring

Mon, 23 Nov 2009 11:32:00-0400

Ah, ColdSpring. In my opinion, you're the bees' knees. You're what makes managing object dependencies a breeze. You simplify and enable the development of object-oriented ColdFusion apps so much that you're core to most large-scale ColdFusion applications written in the last couple of years. The teams behind Mach-II, Model-Glue and ColdBox like you so much that they made you a key player in their framework stacks. I'm not going to sell you on the virtues of ColdSpring any longer, so if you're not using it already, start please. The key to using ColdSpring in Mach-II modules is the super-fantastic ColdSpring property that comes bundled with Mach-II 1.6 (and later). You need to be using the ColdSpring property and not the old ColdSpring plug-in which was available prior to Mach-II 1.6. I know that updating core infrastructure components like frameworks can be scary, but Team Mach-II has done a great job with making Mach-II backwards-compatible to the 1.1 version, so upgrading to take advantage of newer framework features shouldn't be too scary. If you need to learn how to get the ColdSpring property working in your Mach-II application, please review the documentation. The key point about using ColdSpring in Mach-II modules is that you can both set up individual ColdSpring factories for each module in your application and have access to a main, or parent, factory defined at the base level of your application. This is quite powerful for two reasons:

ColdSpring managed objects become specific to the module in which they are needed, and don't clutter up the rest of the application, and,
Commonly used objects can be created at the main/parent application level and be re-used throughout the entirety of the application, as needed.

In order to use ColdSpring in a module, you need to create a ColdSpring property and define it in your Mach-II XML configuration file for the module:



   
   < includes>
      < include file="/myApp/modules/sampleMod/config/sampleMod-coldSpringProperty.xml" />
   

   ...listeners, events, plugins, etc...

The basic information you need to provide in your coldSpringProperty.xml file to use ColdSpring in a module is as follows:

Here's what each parameter does:

beanFactoryPropertyName — This one isn't required, but you really should give your ColdSpring bean factory a name. You must do this in the ColdSpring property XML file for your base application, for reasons I'll describe below.
configFile — This is the path to the ColdSpring XML file for your module, in which ColdSpring-managed beans are defined. This one's required.
configFilePathIsRelative — This lets Mach-II know if it should be using an absolute or relative path to find the ColdSpring XML file defined above. Defaults to false.
resolveMachIIDependencies — This defaults to false, but if you plan on using the super-convenient Mach-II autowriring introduced in Mach-II 1.6, then this must be set to true, or nothing gets autowired in to your plugins, listeners, or filters.
parentBeanFactoryScope — Here's where you tie in the bean factory from your base/parent Mach-II application to your module. By setting this to true, you complete one half of the steps needed to pull in beans defined in the base application but that are used across your whole application. This merely defines the scope in which your parent bean factory is stored. That's most often going to be the application scope.
beanFactoryPropertyName — The value provided here must match the beanFactoryPropertyName value defined in your parent/base app. If it does, you've completed the second half of the steps needed to pull in beans defined in the base application but that are used across your whole application.

So how does all of this work in practice? I'm not going to go in to how you define ColdSpring-managed beans in the ColdSpring XML file. That's all in the ColdSpring documentation. I'll show you how you can use the beans defined in your base app in your module. Let's say you have a userService that is defined in your base ColdSpring XML file. This is a pretty common scenario, as you'll most likely need that userService (for things like getting user information) throughout your application, and in all of your modules. Here's the userService defined in your base ColdSpring XML file:



	
		
			${dsn}
		
	

         ...more beans defined here...

In your module's ColdSpring XML file, you can then utilize the userService like this:



	
		
			
		
	

         ...more beans defined here...

You don't define the userService in your module's ColdSpring XML file. Because you've defined it in the parent/base app's ColdSpring XML file, and you set the parentBeanFactoryScope property to "application" (because that's where the parent bean factory is stored) and you set the beanFactoryPropertyName property to the same value as defined in the parent/base app's ColdSpring XML file, Mach-II's ColdSpring property is smart enough to figure out how to grab the userService and put it in the right place. This is just one example. You can use as many beans from your parent/base app in your modules as you need. By defining commonly used beans in your parent/base app, you reduce your application's overall memory footprint and encourage good object reuse. One Big Caveat There's one thing you really need to watch out for when using ColdSpring and Mach-II modules: bean name collisions. If you define a bean in your parent/base app called "page" and you also define a bean in your module ColdSpring XML called "page," guess which one is going to get used in your module? I'd recommend that you always using module-specific bean names for the beans defined in your module's ColdSpring XML file. This way, you can ensure that you're not going to run in to naming collisions. A Few Other Options You can put the bean factory from your module back in to the parent scope if you need to utilize the module bean factory in the parent/base app. You may have bits of functionality encapsulated in a module that need to be utilized elsewhere in your application. For example, if you have a threaded discussion module, you may want to display the 10 most recent posts on your application's home page. As the functionality for doing this is already defined in a bean that is managed by the threaded discussion module's ColdSpring bean factory, you may want to use that bean in the parent/base application rather than defining it again in the parent/base application's ColdSpring XML file. To accomplish this, you need to add this one line to your module's ColdSpring property file:

This places the module's ColdSpring bean factory in the parent application's application scope. As explained in the Mach-II documentation for the ColdSpring property, Mach-II appends the name of the module to the beanFactoryPropertyName value when the module's ColdSpring bean factory is added to the parent's bean factory to avoid beans in the module overwriting those defined in the parent. Pretty smart stuff! Finally, you can use ColdSpring in your module, but not worry about utilizing beans defined in the parent/base application at all. You lose some power and code-reuse, but you may have no good need to use the parent bean factory. In that case, just omit the parentBeanFactoryScope and parentBeanFactoryKey parameters from your module's ColdSpring property XML file, and you're good to go. Whew! These entries are turning out to be longer than I expected. But there are more to come!

Mach-II and Module Config Files

Mon, 16 Nov 2009 08:55:00-0400

In this installment of my mini-series on modules in Mach-II, I'm going to talk about the Mach-II XML config file for your module, how it relates to the parent (main application) Mach-II XML config file, and try to offer some tips on what should and should not go in your module's Mach-II XML config file. Before I go any further, it's important that you understand the context of this particular series on Mach-II modules and the fact that, for my specific purposes, I am not talking about building modules which are intended for drop-in deployment into any Mach-II app anywhere, like the fantastic Mach-II Dashboard. I'm focusing on building modules that represent mini-applications operating under the auspices of a larger application. Examples of these modules would be a threaded discussion system in a larger community site, or an exam system in an online course site. A Sample Module XML Config File Below is a really simple Mach-II XML config file for a module.



	
	< includes>
		< include file="/myApp/modules/sampleMod/config/sampleMod-coldSpringProperty.xml" />

<includes> You can include other configuration XML files in your module XML configuration file with no problem. In this example, I've included a Mach-II property for ColdSpring because there are certain objects that I want managed by ColdSpring and that are only pertinent to this module. I'll talk more about Mach-II modules and ColdSpring in an upcoming post, but I did want to show you how you'd configure the module to utilize ColdSpring, should you need to (and you most likely will). <properties> At a minmum, you need to include two properties in your module's Mach-II config file:

applicationRoot — The absolute path to your module under Webroot
defaultEvent — The default event to call should no event be specified by a request

Notice that the following Mach-II properties you would have in a Mach-II XML configuration are not listed here:

eventParameter
parameterPrecedence
maxEvents
MACHII_CONFIG_MODE
urlBase or any of the URL rewriting properties

All of these properties have to be defined at the main application level and cannot be overridden at the module level. You can include the following properties in your module's Mach-II XML config to override what's being used in the main application:

exceptionEvent
Module-specific caching property
Module-specific logging property

While you can include these here, I would recommend that you handle exceptions, caching and logging at the main application level. This way you consolidate your exception handling, caching and logging setup in to a single location and don't wonder why you've set up logging in the main application but it's not logging as expected in the module due to a configuration override there. There are perfectly legitimate reasons to handle exceptions at the individual module level. I just prefer to do it centrally. <listeners> You define listeners here exactly as you would in a main Mach-II XML configuration file. Nothing special here. Move on. <filters> Any filters that are needed for this module and this module only are defined here. You'll notice in my configuration file that I call a filter in the sampleProtectedEvent event, but I don't define any such filter in this XML config file. How can this possibly work? Your module inherits all of the properties, event filters, and plugins defined in your parent (main) Mach-II configuration file. So if you have a "admins only" filter which you use to only let administrators access certain events in your application, define it in your parent (main) Mach-II configuration file. You can then refer to that filter in any of the module Mach-II configuration files that operate under the parent app. This is much cleaner, simpler, and more encapsulated than defining a "admins only" filter in each of your modules. You're free to write a special "admins only" filter for a specific module that has special requirements, of course, and you'd define it in this block if that is what you need to do. <event-handlers> Event handlers are defined exactly as they are in the main Mach-II XML configuration file. Nothing special here. Move on. <page-views> As with listeners and event-handlers, page views are defined exactly as they are in the main Mach-II XML configuration file. The <view-loader> introduced in Mach-II 1.8 is a godsend and helps to remove all of the endless page-view declarations you'd normally find in a Mach-II XML configuration file, and if you're not using it, you should. <plugins> As previously mentioned, your module inherits all of the properties, event filters, and plugins defined in your parent (main) Mach-II configuration file. As such, you'd find common plugins like "is the user logged in plugin" and "put properties from a property CFC in to the current event plugin" defined at the main application level. Every event in your module would be subject to the plugins in your main application running on each and every event in the module, just as they do in the main application. If you have a plugin which needs to run on every event in your module, define it here and it will work as expected. There is one additional configuration option you can provide for plugins in a module, and that's the runParent attribute. This attribute tells Mach-II when your module plugins should be run in relation to the plugins in the parent/main app. As I mentioned in my first post in this series, I haven't used this myself because I keep to the default behavior in this regard. I'll simply quote from the Mach-II docs and you can take it from there:

Defines if or when parent (base application) plugins should be run. This attribute only applies to Mach-II module XML configuration files and has no effect if defined in a base application. A value of after will run the defined module plugins first then the parent plugins, a value of before will run the parent plugins first then the module plugins and a value of none will run only the module plugins with no parent plugins whatsoever. The default value is after if not defined and the XML configuration file is a module.

Including Your Module's Config File in the Main App Config File The developers behind Mach-II made it super easy to add a module to any existing Mach-II application. To add a module to an existing Mach-II application, you simply need a <modules> block which tells Mach-II where to find each module you want to include.


...all the rest of your main Mach-II config file, including plugins, listeners, events, etc...

That's it. It takes nothing more than a single line of XML to include your super-complex module in your main application. If you want to pass startup parameters to your module, you can do that too. Here's the example from the Mach-II Dashboard module:

The name that you give the module here (in the name="" attribute) is really important. The name gets prepended (that is, put before) every event name generated by Mach-II functions such as BuildURL(), BuildURLToModule(), and the <view:a> tag. You also have to include that module name in any links you hand-build to the other events in your module, or other modules in the larger application. It's what tells the framework to look for an event within a specific module, and not in the main Mach-II app itself. So an event name like "dashboard:main" would look for an event called "main" inside of the "dashboard" module. To use the sample module XML config file above, an event with the name "sampleMod:sampleProtectedEvent" would look for the event "sampleProtectedEvent" inside the module named "sampleMod." If you fail to prepend the module name (or identifier) to the event name, Mach-II looks for an event with the given event name in the the main application. You'll most likely end up with a "missingEvent" exception as a result. I'm going to cover modules and Mach-II views in more detail in an upcoming post. In the meantime, if you have any questions, comments, or corrections (I'm looking at you, Peter!), please post away!

A Brief Series on Mach-II Modules

Tue, 10 Nov 2009 10:40:00-0400

I've been doing a lot of work with modules in Mach-II in the past couple months and thought I'd blog about some of the stumbling blocks I've encountered. First, a little background: A Mach-II module is an application which runs inside of a parent Mach-II application. A module usually groups together common functionality in to a related package, encapsulates that package nicely within your Mach-II app, and inherits a lot of the base configuration from the parent Mach-II application. Some people build Mach-II modules that are meant to be reused across multiple applications, for multiple sites, while others build open-source modules which are meant to be redistributable and used by anyone, anywhere. My situation is a little different. I'm in the process of re-architecting one of our major applications, getting years of old cruff and rebuilding everything on top of Mach-II 1.8. A large part of this project entails taking some existing Mach-II apps (build under 1.1, 1.5 and 1.6) and integrating them in to the new, main Mach-II 1.8 app. A good amount of the work involves throwing out what's handled by the parent app, adding in new parent-child integration points where needed, and refactoring views to get them to work inside of modules. So that's the context for my work. Your experience may be different, of course, especially if you are looking to build a standalone module that can be integrated in to anyone's Mach-II app, like the super-fantastic Mach-II Dashboard application or Mach Blog. (BTW: If you develop with Mach-II and you're not using the Mach-II Dashboard application, you're wasting time and effort. Single-listener, plugin, filter or config reload is a huge timesaver — and that's only part of what you can do with the Dashboard.) The full introduction to Mach-II modules can be found on the Mach-II wiki. I'm going to assume that you're quite familiar with how Mach-II works and know your way around a Mach-II configuration file. I also want to say that I've not used each and every feature supported by Mach-II modules. I've not had need (yet) for things like the runParent attribute of the <plugin> tag. If you're interested in that topic, please see this thread on the always-useful Mach-II Google group. There's a lot of ground to cover, so I thought I'd break things apart in to a series of posts:

Modules and Mach-II config files
Modules and ColdSpring
Modules and Views
Converting an Existing App to a Module

I'm going to try to get one of these out a week. In the end, if Team Mach-II finds it interesting, useful, and remotely accurate, I'll consolidate some of this to post on the Mach-II wiki.