What's New in Mach II 1.8

A Quickstart for Current Mach-II Developers

Table of Contents

1. The Ethos of Mach-II 1.8
2. Mach-II 1.8 Goals
3. Mach-II 1.8 Feature Overview
4. Mach-II 1.8 Features in Depth
   • Form Tag Library with Data Binding
   • Enhanced event-bean Command
   • View Tag Library
   • Environment Property
   • HTML Helper Property
   • View-Loaders
   • Call-Method Command
   • Enhanced Redirect Functionality
   • Individual Object Reload
   • Toolkit Enhancements
   • Improvements to BuildUrl and the addition of SES URL Routes
   • Improved Whitespace Suppression
   • Miscellaneous Addition or Changes
   • Fixed Defects from Previous Versions
5. Mach-II Simplicity on Google App Engine
   • Known Issues
   • Differences in Behavior
6. Special Thanks
7. What You Can Do To Help
8. The Road Ahead

The Ethos of Mach-II 1.8

Things should be made as simple as possible, but not simpler. (Albert Einstein, 1879–1955)

Mach-II 1.8 Goals

In addition to the introduction of new features that Mach-II developers have requested, we had several other goals during the development of Mach-II 1.8.

• Maintain backwards compatibility. Mach-II 1.8 is 100% compatible with existing Mach-II applications currently running on earlier versions of Mach-II.
• Build new features that not only provide a great value to framework users, but are simple, powerful and elegant to use.
• Refine and expand features introduced is previous versions of the framework.
• Set the stage for future version of Mach-II (1.9 and 2.0). We made several behind-the-scenes changes that will enable functionality we have planned for Mach-II 1.9, which we are currently targeting for late Q2 / early Q3 2010.

Mach-II 1.8 Feature Overview

Although in terms of version numbering Mach-II 1.8 is only a "2 point release" over Mach-II 1.6, numerous new features are introduced in Mach-II 1.8. In addition to bug fixes and general performance improvements, the new features in Mach-II 1.8 are as follows:

• Form Tag Library with Data Binding
• Enhanced event-bean Command
• View Tag Library
• Environment Property
• HTML Helper Property
• View-Loaders
• Call-Method Command
• Enhanced Redirect Functionality
• Individual Object Reload (via the new dashboard)
• Toolkit Enhancements (Assert, ANTPathMatcher, SimpleMatcher)
• Vastly improved whitespace suppression reduces whitespace produced in output by framework files

Mach-II 1.8 Features in Depth

Form Tag Library with Data Binding

The Mach-II form tag library is a comprehensive set of data binding aware custom CFML tags that produce HTML form elements. Each tag supports all corresponding HTML form element attributes in a familiar and intuitive to use manner. The generated output of each tag is HTML 4.01/XHTML 1.0 compliant.

The big difference between other form tag libraries and the Mach-II form tag library is that our library is integrated with Mach-II. This gives our library access to Mach-II related functionality. As you will see in the following examples, the form tag library makes developing views with forms easier to develop, maintain and ultimately read when editing code. In the future, this library will integrate with our planned validation framework (which will be Mach-II MVC independent) and will provide seamless integration between client and server side validation. View the full spec.

Enhanced event-bean Command

We have enhanced the event-bean command with nested inner-bean and field tags. This allows you to populate nested beans (beans of composition) and directly integrates with the form tag library. Check out Event-Beans for more information. The event-bean enhancement was developed from a concept submitted by a community member through our call for features program. This just proves that at Mach-II - we're community driven.

View Tag Library

The Mach-II view tag library is a comprehensive set of CFML tags that reduce writing mundane or complex code within your views.

The a Tag

The a tag is a quick way to create a HTML <a> tag with built-in functionality to build a URL or route. Ever since buildUrl() was introduced back in Mach-II 1.5, many users have been asking for an easier way of passing in parameters instead of name / value pairs. Tags are more flexible than method calls are when it comes to passing in unknown attributes or arguments.

HTMLHelperProperty Integration

We have integrated the usage of the !HTMLHelperProperty methods into convenient tags. We support img, meta, script, style and link tags.

Other Tags

Other compelling tags are the flip tag. View the full spec.

Environment Property

The Environment Property is a pre-built Mach-II property which helps you easily define and manage environment specific properties within your .xml configuration file. While property offers the ability to configure as many environments as you wish, many developers only utilize development and production environments. If you do not need to use a particular environment, simply do not define it in your configuration file. The environment property allows for an unlimited number of environments to be setup. Each environment can be named anything except for a short list of reserved names as they conflict with other parameter names used by environment property. View the full spec.

HTML Helper Property

The HTML Helper Property is a pre-built Mach-II property which helps you cut down on redundant HTML tasks like including JavaScript and CSS files within your views. As Web developers, we are readily aware that each request in our application has a number of responsibilities. In a Mach-II application, for example, each request may need to process a login filter, notify a listener to retrieve a required data set, and execute a subroutine to build a composite view. In addition to these necessary tasks, most requests have more redundant responsibilities such as including necessary JavaScript files, CSS files, adding meta information, links such as RSS or icons and specifying the doctype for a request.

These redundant tasks collectively fall outside the scope of custom CFML application development, and instead are necessary parts of constructing a relatively basic HTML request. The Mach-II HtmlHelperProperty provides an easy way to alleviate the headache often associated with these types of tasks by managing them in an organized way. View the full spec.

View-Loaders

One of the Mach-II XML configuration file sections that can become rather unruly is the <page-views> section. A smart developer will use some sort of convention when structuring views and page-view names. However, this becomes rather tedious over time as the size of the application grows because you have to manually add each <page-view> in XML. It can be prone to error because it's easy to forget to add a new <page-view>. View loaders are a CFC that would allow a developer to load views based on convention such as using an ANT-style path matching pattern.

Using the pattern view loader, each directory and file name would be translated into a page-view name using a configurable delimiter. For example if a view with the path of /aboutUs/index.cfm was found, it would be translated into a page-view name of aboutUs.index. The translation starts with directories and the file name that start after the ANT-style pattern end. Therefore, a deeply nested directory may require a prefix.

The addition of view loaders would allow developers to auto-register page-views by convention thus reducing a normally tedious task of registering views. Also, developers could define multiple view-loaders in the page-views section or create their own loader by extending a particular Mach-II CFC. View the full spec.

Call-Method Command

Often when writing Mach II applications the developer is required to create a method in a listener that simply calls a method in the application's service layer with out any additional logic. This requires the developer to write extra listener methods that don't really serve any purpose. Mach II should make this easier by providing a command that can be used in the Mach II configuration file to allow the framework to call a method in the service layer and optionally put the result in an event argument. Simple argument passing should be allowed via the use of the new expression syntax for access elements in the event or properties objects. View the full spec.

Enhanced Redirect Functionality

Enhanced redirect functionality will allow redirects to be issued from within Mach-II filters, plugins, and listeners with the new redirectEvent() and redirectEventInModule() methods. These redirects will still support complex argument persistence and will allow flow information to be abstracted from listeners through the built-in support of event-mappings. View the full spec.

Individual Object Reload

The new Mach-II dashboard allows developers to cut down on development time by reloading individual objects when necessary rather than reloading an entire application. This is all controlled from a convenient user interface.

Toolkit Enhancements

View full spec.

Making Simple Developer Assertions with Assert.cfc

This new utility CFC provides assertion methods to aid in the basic validation of arguments. An assertion in this case is an expectation or assumption that something must be true at run time for the code to continue to work. A typical location to do an assertion is to check configure-time parameters in a Mach-II filter at runtime in an effort to "assert" they are valid and to thrown an exception if an assertion fails. A major advantage of doing run-time checking of parameters that when an assertion fail does occur it is detected immediately rather than later through its often obscure side-effects. It is easy to pin-point the error without time consuming debugging because if an assertion fails the developer receives an exception message (and optional details) along with the location of the failed assertion.

The Assert.cfc that comes bundled with Mach-II offers several different types of basic assertion methods that we will look at later. However, it should be noted that the assertion utility is not designed to be used for user input validation (such as form validation), but as a utility to aid developers in performing simple checking of incoming arguments or parameters.

Wildcard "*" Pattern Matching with SimplePatternMatcher.cfc

The MachII.util.SimplePatternMatcher is a new utility introduced in Mach-II 1.8 that makes matches with a simple * wildcard. This allows you to check a string against a pattern using the * wildcard. For complex pattern matching when a path separator is being used such as a file path (/ or \) or url (/) use the AntPathMatcher.cfc.

Advanced Path Matching via Patterns with AntPathMatcher.cfc

The MachII.util.AntPathMatcher is a new utility that was introduced back in Mach-II 1.6 that makes matches against a path with a pattern using ANT-style wildcards. These wildcards look like regular expressions - however they really denote directives. This utility is the major algorithm that drives the view-loader functionality (load views by conventions) that was introduced in Mach-II 1.8.

One of the more common uses for the utility is to see if a file path matches a certain pattern. This is useful for loading files on convention. For example, we use the utility for the new pattern view-loader in Mach-II 1.8 which loads all views that match a certain pattern. By default, the pattern used for the view-loader is /views/**/*.cfm which will match all .cfm files (the *.cfm part of the pattern) in the /views directory (the /views/ part of the pattern) and any directory below that (the **/ part of the pattern and without this part the matched paths would be to .cfm files that are in the /views/ directory only).

Improvements to BuildUrl and the addition of SES URL Routes

Several members of the Mach II community have requested enhancements to the buildURL functionality that was introduced in Mach II 1.5 as part of our support for search engine friendly URLs. In addition to these enhancements the Team Mach II added a new feature to make it easier to setup special search engine friendly URL schemes known as "routes". View full spec.

Improved Whitespace Suppression

We've vastly reduced the amount of whitespace that the core framework files produce. We've virtually eliminated the majority of the whitespace produced.

Miscellaneous Addition or Changes

• Vastly improved whitespace suppression reduces whitespace produced in output by framework files
• CopyToScope() helper method in views
• Full email configuration support for EmailLogger with additional parameters for username, password, charset, spoolenable and timeout.
• EmailLogger only sends emails when a specific log level is tripped
• EmailLogger's default email template now includes a dump of the Event object and additional information such as user agent, timestamp, current service name, remote ip address, etc.
• Event-arg command accepts complex XML values (struct / array)
• Added buildUnescapedUrl() and buildUnescapedUrlToModule() to ViewContext to be used with javascript
• Logging package now uses a LoggerManager
• Improved exception handling logic when loading Mach-II extended components
• Improved log message when logging data from cftry/cfcatch blocks
• Many small performance improvements such as removed repeated method calls to resources and conditionals that evaluated the same in loop iterations and changed some Java objects to be more "static" in nature instead of being instantiated in each method body repeatedly.
• Remove generation of cfcs for method injection for ColdSpring "depends" integration. Test case showed 9,500% performance improvement. See ticket (trac-wiki) #456 "enhancement: Remove generation of cfcs for method injection for ColdSpring depends ... (closed: fixed)") for more information.

Fixed Defects from Previous Versions

Publish command does not bubble exceptions properly

Publish command does not bubble exceptions properly in multithreaded mode which causes problems when a publish command encounters an exception inside a cache block. The exception event is handled correctly on the first request, but caused the cache handler to erroneously cache data. Subsequent requests were served bad data from the cache in which depending on the usage of the cache and nested commands caused a white screen of death.

This defect is an edge case defect that was undiscovered for approximately 9 months that affected releases of Mach-II 1.6.0 and 1.6.1. It has been fixed in the 1.8 release. Special thanks to Shaun at Net Grow for discovering this defect. For more information see ticket (trac-wiki) #422 "defect: Publish command does not bubble exceptions properly in multithreaded mode (closed: fixed)").

Includes loaded in module override XML were loaded incorrectly

If the same include file is included in the override XML section in two or more modules, Mach-II would throw an exception saying the include was alreadyincluded. The incorrect RegEx was being used to search for the includes in the override XML causing the includes to be picked up by the parent non-override include parsing code.

This defect is an edge case defect that was undiscovered for approximately 18 months and affected Mach-II 1.5.0 and 1.6.0 and 1.6.1. It has been fixed in the 1.8 release. Special thanks to Jason York at The Lampo Group, Inc. for discovering this defect. For more information see ticket (trac-wiki) #413 "defect: Providing same include within two different module nodes (closed: fixed)").

SES Urls fail to be parsed

SES Urls fail to be parsed when the urlDelimiters property is set to non-query string parameters. This is because the urlParseSES is also required to be set to true, but by default is set to false. This was fixed by setting the value of urlParseSES to true if the property is not defined and when the urlDelimiters is set to something other than ?|&|= (i.e. non-query string urls).

This defect is an extreme edge case defect and affected Mach-II 1.5.0, 1.6.0 and 1.6.1. It has been fixed in the 1.8 release. This was discovered by Team Mach-II. For more information see ticket (trac-wiki) #417 "defect: SES Urls fail to be parsed when the urlDelimiters are set to non-query ... (closed: fixed)").

Disabled cfthread in security sandbox can cause exceptions

Some CFML engines are configured to disable threading via cfhread even though the engine has threading implemented. This ticket adds in a check to see if threading is not only implemented, but available for use on the target system in which the application is deployed.

This defect affected Mach-II 1.6.0 and 1.6.1. It has been fixed in the 1.8 release. Special thanks to Derrick Jackson at the United States Senate - Sergeant at Arms for discovering this edge case defect. For more information see ticket (trac-wiki) #411 "defect: SubRoutines/Caching/CFThread (closed: fixed)").

Local cachingEnabled is not respected when set to false

The local cachingEnabled parameter for caching strategies was not being respected and was overrided by the global setting.

This defect affected Mach-II 1.6.0 and 1.6.1. It has been fixed in the 1.8 release. A special thanks to Doug Smith at The Lampo Group, Inc. for discovering this defect. For more information see ticket (trac-wiki) #388 "defect: cachingEnabled is not respected when set to false (closed: fixed)").

Calls to non-Mach-II URLs throw exceptions when sessions timeout

Direct calls to .cfm files in directories below the directory that contains your Application.cfc throw an exception when a session timeouts.

This edge case defect affected Mach-II 1.5, 1.6.0 and 1.6.1. It has been fixed in the 1.8 release. A special thanks to Brandon Culpepper at Direct Solutions International, Inc. for discovering this defect and working with Team Mach-II to provide us with a sample test application that illustrated the issue. Without his efforts, this defect would have been much more time intensive to track down. For more information see ticket (trac-wiki) #373 "defect: Calls to URLs That Are Not Events Throw Error When Session Times Out (closed: fixed)").

Module does not reload when MACHII_CONFIG_MODE = 0

Special thanks to Phil Thomas at The Lampo Group, Inc. for tracking down this defect and providing us a patch. For more information see ticket (trac-wiki) #317 "defect: Module does not reload on module mach-ii.xml file change when ... (closed: fixed)")

HTMLHeadElement and HTTPHeader callbacks failed to be removed from EventContext

This defect can cause strange problems when using nested cache blocks such as an event-handler with a cache block that calls a subroutine with a cache block. This defect affected Mach-II 1.6.0 and 1.6.1. It has been fixed in the 1.8 release. For more information see ticket (trac-wiki) #305 "defect: HTMLHeadElement and HTTPHeader Callbacks fail to be removed from ... (closed: fixed)").

Method checking fails when extending a logger due to failure to walk inheritance tree

For more information see ticket (trac-wiki) #303 "defect: Method checking fails when extending a logger due to failure to walk ... (closed: fixed)").

View context throws an ambiguous exception appending view content on to a complex event-arg

We now assert the target contentArg/Key is a simple value and throw a friendly exception if it is not. For more information see ticket (trac-wiki) #263 "defect: View context throws an ambiguous exception appending view content on to a ... (closed: fixed)").

BuildUrl() and related methods orders args randomly

Fixed so all args are ordered alpha-numeric which provides consistent URLs for search engines. This is especially important for SES URLs. For more information see ticket (trac-wiki) #264 "defect: BuildUrl() and related methods orders args randomly (closed: fixed)").

Mach-II Simplicity on Google App Engine

At this time, Mach-II Simplicity runs on Google App Engine (GAE) using Open BlueDragon GAE edition. Support for this version of Mach-II is not officially supported because OpenBD is still in beta and we are working with the OpenBD team to resolve any issues with the GAE edition.

The first production site running OpenBD GAE and Mach-II Simplicity is:

http://www.legatowheels.com

Known Issues

cfdirectory with action="list" gives incorrect results

This defect on !OpenBD GAE affects the new PatternViewLoader. This issue can be tracked by following OpenBD issue 170. A temporary "hack" fix for the PatternViewLoader is available from Team Mach-II until this issue is resolved in !OpenBD GAE edition. This has been fixed in the nightly builds or official releases after December 9th, 2009.

Differences in Behavior

Auto-dimensions in the HtmlHelperProperty is not supported

The auto-dimensions for images in the HtmlHelperProperty is not supported because the Java java.awt.* package is a restricted package on Google App Engine. Any image without width or height attributes that normally would get auto-dimensions is just ignored and no width or height is appended to the HTML img tag.

Special Thanks

Team Mach-II would like to send a special thanks to the following individuals that helped us produce Mach-II Simplicity by providing feedback, testing nightly / release candidate builds, test cases / application or finding defects (in no particular order):

• Doug Smith (The Lampo Group, Inc.)
• Eli Tapolcsanyi (The Lampo Group, Inc.)
• Ty Delong (The Lampo Group, Inc.)
• Phil Thomas (The Lampo Group, Inc.)
• Brandon Culpepper (Direct Solutions International, Inc.)
• Derrick Jackson (The United States Senate - Sergeant at Arms)
• Joel Cox (Goodyear Tire and Rubber Company)
• Chris Irwin (WolfNet Technologies)
• Adrian Scott (Allura Direct)
• Brian Klaas (Johns Hopkins University - Bloomberg School of Public Health)
• Brian Pickens (Forum Communications Company)
• Jonah (Creori)
• Shaun (Net Grow)
• Mike Rogers
• Dave Shuck
• Dan Skaggs
• Jorge Loyo
• Zack Pitts
• Joseph FitzGerald
• Jayel (no last name given)

We hope that the above list shows how great of a community we have for Mach-II and that it inspires more people to become involved. Just a few minutes of your time saves hours for others. Think about contributing today.

This list is by no means a complete list of people Team Mach-II would like to thank. If you participated by filing a defect, patch, enhancement and have been inadvertently left of this list, we're so sorry we forgot you. You're efforts have not been forgotten and please consider yourself thanked!

What You Can Do To Help

First and foremost, thank you for using Mach-II! We continue to strive to make Mach-II the best MVC framework for CFML development, and your use of and feedback about Mach-II is a vital part of our development process.

If you'd like to help further, there are many ways to do so:

• Write an FAQ or other documentation on the wiki
• Report a bug
• Request a new feature
• Add your site/company to the "Who's Using Mach-II" page on mach-ii.com (coming soon!)
• Contact us to set up an interview or case study that we can publish on mach-ii.com
• Tell your friends and colleagues about Mach-II

In terms of helping us, a little goes a long way. If everyone using Mach-II spent even 10 minutes helping out with documentation, that translates into a massive number of man hours contributed to the project.

The Road Ahead

After we recover from the 1.8 release, we're going to dive right into Mach-II 1.9, which we're targeting for release in the late Q1 / early Q2 2010.