ColdFusion on Wheels Blog

CFWheels 2.0.0-beta.1 Now Available

June 1st, 2017 by Tom King

It’s been about a year in the making, and well over 1000 commits, but the beta for 2.0 has now arrived! We’re still catching up on the main documentation as there’s so much to cover in this release, so bear with us a bit! In the meantime, please do check it out:

  • Direct Download: Download zip
  • Commandbox quick install : install [email protected] (Just downloads and unzips)
  • Commandbox install wizard via CFWheels CLI (with url rewriting included):  wheels new
    (make sure your version of the CLI is up to date with install cfwheels-cli)

Make sure to check the “Breaking Changes” section below, and please report any bugs.

Need a little help upgrading?

There will be some more posts coming up covering some of the big topics like routing & migrations, but in the meantime:

  • Check out Adam’s upgrade advisor plugin (Commandbox: install upgradeadvisor)
  • Get in touch via the Mailing List, Slack channel etc.

Changelog

Model Enhancements

  • Support for passing in select=false to property() to not include a calculated property by default in SELECT clauses – #122 [Adam Chapman, Per Djurner]
  • Support for setting calculated properties to a specific data type – [Per Djurner]
  • Support for returnIncludedAs and returnIncluded arguments to properties() for returning nested properties – [Adam Chapman]
  • Support for calling updateProperty() with dynamic argument, e.g. updateProperty(firstName="Per") – [Per Djurner]
  • Support for using boolean transaction argument, e.g. update(transaction=false) – #654 [Adam Chapman]
  • Support for MariaDB – #563 [AlexeiCF, Adam Chapman]
  • Model instance isPersisted() and propertyIsBlank() methods – #559 [Chris Peters]
  • Database Migrations (dbmigrate) now available in the core – #664 [Adam Chapman, Tom King, Mike Grogan]
  • Databases can now be automatically migrated to the latest version on application start – #766 [Tom King]
  • New timeStampMode setting ("utc", "local" or "epoch") for the createdAt and updatedAtcolumns – [Andy Bellenie]
  • Allow nested transactions – #732 [Andy Bellenie]
  • The handle argument to finders now set the variable name for the query so it’s easier to find in the debug output – [Per Djurner]
  • Support added for HAVING when using aggregate functions in the where argument – #483 [Per Djurner]
  • Added support for the JSON data type in the MySQL adapter – #759 [Joel Stobart]
  • Corrected mapping for text types in the MySQL adapter – #759 [Joel Stobart]
  • Added global setting, lowerCaseTableNames, to always lower case table names in SQL statements – [Per Djurner]

View Enhancements

  • flashMessages() are now in default layout.cfm – #650 [Tom King]
  • Added ability to override value in textField(), passwordField() and hiddenField() – #633 [Per Djurner, Chris Peters]
  • Support for the method argument in buttonTo() helper – #761 [Adam Chapman]

Controller Enhancements

  • Support for HTTP verbs, scopes, namespaces, and resources in routes (ColdRoute) [Don Humphreys, James Gibson, Tom King]
  • Support for passing in ram:// resources to sendFile() – #566 [Tom King]
  • Extended sendMail() so that it can return the text and/or html content of the email – #122 [Adam Chapman]
  • renderWith() can now set http status codes in header with the status argument – #549 [Tom King]
  • Cross-Site Request Forgery (CSRF) protection – #613 [Chris Peters]
  • Parse JSON body and add to params struct – [Tom King, Per Djurner]

Bug Fixes

  • Fixes skipped model instantiation due to Linux file case sensitivity – #643 [Adam Chapman, Tom King]
  • Added spatial datatypes for MySQL – #660 [Normal Cesar]
  • Made humanize() keep spaces in input – #663 [Per Djurner, Chris Peters]
  • Avoid double redirect error when doing delayed redirects from a verification handler function – [Per Djurner]
  • Fixes attempts to insert nulls for blank strings – #654 [Andy Bellenie, Per Djurner]
  • Fix for using validatePresenceOf() with default on update – [Andy Bellenie]
  • Fixes so paginated finder calls with no records include column names – #722 [Per Djurner]
  • Fixes “invalid data” error when using unsigned integers in MySQL – #768 [Per Djurner]

Plugins

  • Plugins now distributed via forgebox.io [Tom King]
  • Update to the plugin system to allow overriding of the same framework method multiple times – #681 [James Gibson, Tom King]
  • Added ability to turn off incompatible plugin warnings from showing – [Danny Beard]
  • Plugins now have any java lib/class files automatically mapped onApplicationStart 731 [Andy Bellenie, Tom King]
  • Plugins now read version number off their box.json files and are displayed in debug area #68 [Tom King]
  • Plugin meta data as set in box.json now available in application.wheels.pluginMeta scope #68 [Tom King]

Miscellaneous

  • Redirect away after a reload request – [Chris Peters]
  • Support checking IP in http_x_forwarded_for when doing maintenance mode exclusions – [Per Djurner]
  • Support checking user agent string when doing maintenance mode exclusions – [Per Djurner]
  • Added JUnit and JSON format test results – [Adam Chapman]
  • Added empty application test directories – [Chris Peters, Adam Chapman]
  • Added default urlrewrite.xml to support Tuckey URL rewriting with Commandbox #649 – [Tom King]
  • Added beforeAll(), afterAll(), packageSetup(), packageTeardown() methods to test framework #651 – [Adam Chapman]
  • Added errorEmailFromAddress and errorEmailToAddress config settings – #95 [Andy Bellenie, Tony Petruzzi, Per Djurner]
  • Support for passing in any “truthy” value to assert() in tests – [Per Djurner]
  • Added /app/ mapping pointing to the root of the application – [Per Djurner]
  • Added a processRequest() function that simplifies testing controllers – [Per Djurner]
  • Added new embedded documentation viewer/generator for JavaDoc – #734 [Tom King]
  • Removes all references to Railo – #656 (Adam Chapman)
  • Made uncountable and irregular words configurable – #739 [Per Djurner]
  • Removed design mode – [Per Djurner]
  • Removed cacheRoutes setting – [Per Djurner]
  • The cacheFileChecking and cacheImages settings are now turned off in development mode – [Per Djurner]
  • Added includeErrorInEmailSubject setting – [Per Djurner]
  • Environment switching via URL can now be turned off via allowEnvironmentSwitchViaUrl – #766 [Tom King]

Breaking Changes

  • Minimum Lucee version is now 4.5.5.006.
  • Minimum ACF version is now 10.0.23 / 11.0.12.
  • Support for Railo has been dropped.
  • Rewrite and config files for IIS and Apache have been removed and has to be added manually instead.
  • The events/functions.cfm file has been moved to global/functions.cfm.
  • The models/Model.cfc file should extend wheels.Model instead of Wheels (models/Wheels.cfc can be deleted).
  • The controllers/Controller.cfc file should extend wheels.Controller instead of Wheels(controllers/Wheels.cfc can be deleted).
  • The init function of controllers and models should now be named config instead.
  • The global setting modelRequireInit has been renamed to modelRequireConfig.
  • The global setting cacheControllerInitialization has been renamed to cacheControllerConfig.
  • The global setting cacheModelInitialization has been renamed to cacheModelConfig.
  • The global setting clearServerCache has been renamed to clearTemplateCache.
  • The updateProperties() method has been removed, use update() instead.
  • Form labels automatically generated based on foreign key properties will drop the “Id” from the end (e.g., the label for the “userId” property will be “User”, not “User Id”).
  • Routes need to be updated to use the new routing system by calling mapper().
  • JavaScript arguments like confirm and disable have been removed from the link and form helper functions (use the JS Confirm and JS Disable plugins to reinstate the old behaviour).
  • Timestamping (createdAt, updatedAt) is now in UTC by default (set the global timeStampModesetting to local to reinstate the old behaviour).
  • Blank strings in SQL are now converted to null checks (e.g. where="x=''" becomes where="x IS NULL").
  • Tags are now closed in HTML5 style (e.g. <img src="x"> instead of <img src="x" />).
  • The encode argument to mailTo now encodes tag content and attributes instead of outputting JavaScript.
  • Class output is now dasherized (e.g. field-with-errors instead of fieldWithErrors).
  • The renderPage function has been renamed to renderView.

Tags:
Posted in Releases | 2 Comments »

Testing Plugins on CFWheels 2.x and Travis CI via commandbox

May 31st, 2017 by Tom King

One of the nicest things about CFWheels 2.x is the tighter integration with command-line tools such as Commandbox. We can take advantage of the new testing suite JSON return type and the new CFWheels CLI in Commandbox 2.x to easily build a Travis CI test. It’s perhaps easiest to just show the .travis.yml file – this goes in the root of your gitHub plugin repository, and once you’ve turned on testing under Travis.org, will run your test suite on every commit.

In sum, this:

  1. Installs Commandbox
  2. Installs the CFWheels CLI
  3. Installs the master branch of the CFWheels repository
  4. Installs your plugin from your repository (rather than the forgebox version which will be the version behind)
  5. Starts the local server
  6. Runs the test suite, pointing only at your plugin’s unit tests

Naturally, you could do more complex things with this, such as multiple CF Engines, and maybe even multiple CFWheels versions, but for a quick setup it’s a good starting point!

Tags: , ,
Posted in Tips & Tricks, Tutorials | Comments Off on Testing Plugins on CFWheels 2.x and Travis CI via commandbox

Unit Testing your new 2.x app in 2.x beta

May 30th, 2017 by Tom King

Hands up if you’ve ever found a bug in your application..

Upgrades, feature enhancements and bug fixes are all part of the development lifecycle, but quite often with deadlines, it’s difficult to manually test the entire functionality of your application with every change you make. What if there were an automated way of checking if that change you’re making is going to break something?

Enter the CFWheels test framework!

In the past, writing an automated test suite against your application meant downloading, configuring and learning a completely separate framework. To help address this issue, CFWheels includes a small, simple, yet powerful testing framework. Whilst this has been part of the core in 1.x, it’s never been properly documented, and with 2.x, we’ve introduced lots of new features to help test your application.

Here is a simple example of unit testing a helper function that adds two numbers.

The same idea can be applied to just about any function in your application. Here are some of the things you might want to test:

  • Global helper functions return the values expected
  • That custom model validations return error messages when a value is not valid
  • Model callbacks are fired and produce the expected result
  • Controllers produce the expected output
  • Controllers redirect to the correct location

Once you have a comprehensive test suite, you can make code changes with a greater sense of confidence that you have not introduced bugs (regressions) into your application. This gives you the opportunity to implement automated test runners into a continuous integration platform like Jenkins or TravisCI.

Don’t just take our word for it.. well actually, DO take our word for it as CFWheels 2.0 has been developed exclusively against the inbuilt test framework.

For those of you who have been using the testing framework in your CFWheels 1.x applications, the 2.0 framework has a number of improvements around setup, teardown and a super handy processRequest function:

You get lots of handy information back, like the body contents, the status code of the request, and more.

Want to get going? Check the comprehensive tutorial at guides.cfwheels.org

Tags: ,
Posted in Tips & Tricks, Tutorials | Comments Off on Unit Testing your new 2.x app in 2.x beta

Calling all plugin authors! Time for 2.x…

May 18th, 2017 by Tom King

With CFWheels 2.0 beta around the corner, it’s time to have a cold hard look at the CFWheels plugin ecosystem.

With 2.x, we’ve taken the opportunity to modernise how we deal with plugins. If you’re a plugin author who has previously released something for 1.x, you’ll be pleased to hear there aren’t that many changes required to get your plugins playing nicely with 2.x, but it’s definitely a good time to revisit what you’ve got out there.

Introducing Forgebox.io

One of the main problems we had previously was a lack of a centralised repository of CFwheels plugins. The old system relied on a bit too much manual updating, and over time got a little long in the tooth. So now, all plugins should be added to forgebox.io, specifically in the CFWheels Plugins category. If you go and have a look now, you’ll see a few added by the core team as examples. Adding your plugin shouldn’t be too much hard work, but it’s definitely worth setting yourself up properly to publish to forgebox automatically via the commandline. There’s an extensive tutorial over at guides.cfwheels.org which we recommend you follow. In short, you ideally need a properly configured box.json file and for your plugins to use git tagged releases (ideally). If you’ve not installed commandbox and the CFWheels CLI, now is definitely the time to try it!

Easier for other developers too

Once your plugin is in the forgebox system, other CFWheels users can install your plugin with a single CLI command: install slugName; If they’ve got the CFWheels CLI installed, it will automatically create appropriate .zip files with the correct version number (which you’ll have set in box.json) too. They’ll also be able to view all existing plugins with wheels plugins list  making it extra quick to find the plugin they need. Dependencies are then tracked in that user’s box.json file, so they can even distribute an app without your plugin, and then simply run install to go and download the correct version later: they can even update to the latest version of your plugin via the CLI too, or freeze it to a specific version.

Automatic Java Mappings

One of the nice new features of 2.x is the automatic java library mappings which plugins can now take advantage of. Previously, you had to rely on the developer to manually add an entry into this.javaSettings.loadpaths if your plugin required use of a .class or .jar file. Now, we scan the plugin folders on startup, and automatically add any folders which contain .jar or .class files. One less step for configuration! You can see an example of this in the CFWheels bCrypt plugin, which adds a quick wrapper around the bCrypt java class.

Don’t forget your comments!

In a previous post, we talked about the new embedded documentation: plugins can now take advantage of this. For plugin authors, we’re recommending you comment all public functions – here’s a quasi code example below.

The important part is the [section: Plugins] and [category: Plugin Name] part, which will automatically sort your functions in the correct place in the internal documentation. It’s a good habit to get into, and will help other users of your plugin too.

Oh, and unit tests 🙂

Don’t forget to write some unit tests too (hey, don’t we all do TDD?); there’s been some changes to the test suite in 2.x, and writing unit tests is loads easier. More to follow on:

  • New functions for testing in 2.x
  • Running plugin tests via command line,
  • How to add your plugin to Travis CI for continuous integration testing

Tags: ,
Posted in Tips & Tricks, Tutorials | Comments Off on Calling all plugin authors! Time for 2.x…

Internal Documentation in CFWheels 2.0-beta

May 8th, 2017 by Tom King

One of a developer’s biggest time sinks is coming up with and writing accurate and engaging documentation. Even if it’s an internal project with.. well, just you… it’s still incredibly valuable to have: coming back to projects a few months or even years later can often lead to a bit of head scratching and screams of “why?”, especially with your own code.

Whilst we’re not promising that CFWheels will write all your documentation for you, we have put some tools in place to hopefully make the process a little less painful. With a small amount of adjustment in how you document your core functions, documentation doesn’t necessarily have to be such a time consuming process.

Browse the Core API

The first thing to notice is the new ‘[View Docs]’ link in the debug section in the footer:

Following that link leads you to the internal documentation. This is a dynamically created set of documention created via javaDoc commenting in the main CFWheels Core.

The three column layout is designed to allow for quick filtering by section or function name. On the left are the main CFWheels core categories, such as Controller and Model functions, which are then broken down into sub categories, such as Flash and Pagination functions etc. Clicking on a link in the first column will filter the list in the second  and third columns with all the functions which match (including child functions of that category).

Filtering by function name is made simple by a “Filter as you type” search field in the second column, so getting to the right function should be very quick.

The third column contains the main function definition, including tags, parameters and code samples.

How is it generated?

Each function in the core is now appropriately marked up with javaDoc style comments. This, combined with getMetaData() allows us to parse the markup into something useful.

The [section] and [category] tags categorise the function as appropriate, and the @html part describes the function’s parameter. The additional parameter data, such as whether it’s required, type and any defaults are automatically parsed too. This results in a display like:

Documenting your own functions

Any function which is available to Controller.cfc or Model.cfc is automatically included; if there’s no javaDoc comment, then they’ll appear in uncategorized. But of course, there’s nothing stopping you creating your own [section] and [category] tags, which will then automatically appear on the left hand column for filtering: you’re not restricted to what we’ve used in the core.

As an example, if you wanted to document all your filters, you might want to have a [section: Application] tag, with [category: filters].  This way, your application documentation grows as you create it.

Something as simple as a sublime text snippet for a new function which includes the basic javaDoc skeleton can get you in the habit pretty quickly!

Plugins too!

We also introspect plugins for the same markup. We encourage plugin authors to adjust their plugin code to include [section: Plugins] at the very least. We do appreciate it will take a while for the plugin eco-system to catch up with this though. More on plugins later.

Exports & Re-use

You can export the docs via JSON just by changing the URL string:
i.e ?controller=wheels&action=wheels&view=docs&type=core&format=json

You could also include the functions used to create the docs and create your own version (perhaps useful for a CMS or other application where you have internal documentation for authenticated users). Whilst this isn’t officially supported (the main functions may be subject to change!) it is technically possible. The best example is the thing itself – see the main output if you’re interested. Please note that the user interface isn’t available in production mode (for obvious reasons we hope!), so if you wanted to expose this data to an end user, you would probably need to “roll your own” with this approach.

Updating

Note that the CFC introspection doesn’t automatically happen on every request, so you will need to ?reload=true to see changes to your code. Additionally, Adobe ColdFusion is more aggressive in caching CFC metadata, so depending on your settings, you may not see changes until a server restart.

Code samples

Whilst the core has additional code samples which can be loaded from text files, there’s no support for your application functions to take advantage of this yet.

Roadmap

Whilst this API/function explorer is a great first step, you’ll notice your controller and model specific functions aren’t included (only those shared amongst controllers, or in the /global/functions.cfm file. This is because we’re only looking at the main Model.cfc and Controller.cfc and what it can access.

In CFWheels 2.1, we’ll look at adding a full Controller and Model metadata explorer using the same techniques, and map functions like show() to their respective routes too.

 

Tags:
Posted in Documentation, Tutorials | Comments Off on Internal Documentation in CFWheels 2.0-beta

Moving towards 2.x Beta

May 4th, 2017 by Tom King

It’s been a while in the making (probably 9 months or more) but we’re finally rolling towards a 2.0 beta release, with just a few tickets in the queue left before we can set it free on the world.

In the meantime, you may have noticed a few changes in the CFWheels ecosystem, which we’ve needed to do to support CFWheels 2.x properly.

HTTPS baby!

Firstly, all CFWheels domains are now running over https://, which in this day and age, should be a given. No excuses for not doing this now.

guides.cfwheels.org

“docs.cfwheels.org” has been renamed guides.cfwheels.org and is where the main extended documentation and tutorials will live. This system is based on readme.io, and has been great in quickly creating some nice looking docs. We will continue to add to what’s there over the beta launch too.

However, it’s not perfect: the API reference on there is simply not designed to take something of the scope of the CFWheels API. The page can crash mobile browsers and is a little…unwieldy at best. Adding to the extremely odd SEO of the reference section (i.e, it’s not indexed at all), it’s time to move it off.

api.cfwheels.org (alpha)

So as docs.cfwheels.org has been deprecated, we’re going to split out the API reference to a new home, api.cfwheels.org. There’s lots of good reasons for this: With CFWheels 2.x, not only has the entire core (well, almost the entire core) been moved to cfscript, we’ve also commented every single public API function with javadoc style comments.

This means all the core functions you know and love now have been categorized and commented in the source code, so when pull requests come in, we can keep the documentation up to date at the same time.

The 2.x core has a new built in javadoc parser, so now we can just extract a JSON file where we can power api.cfwheels.org. This also has a huge advantage – we can offer offline/built in documentation browsers from within the debug section of your app. It will even read your own functions – so your local documentation reference will be increasingly valuable. More on this in detail soon.

More to come!

Over the next few weeks, we’ll try and get some blog posts out detailing some of the new 2.x beta features in detail. If there’s something in particular you’d like to know about, please ping a comment or find us in slack/mailing list/gitHub.

Tags:
Posted in Documentation, Website | 1 Comment »

CFWheels 1.4.5 maintenance Release

March 30th, 2016 by Tom King

Today sees another maintenance release for the 1.4.x series

Download 1.4.5 today to fix the following:

Bug Fixes

  • Display URL correctly in error email when on HTTPS – [Per Djurner]
  • Added the datetimeoffset data type to the Microsoft SQL Server adapter – [Danny Beard]
  • Fix for test link display in debug footer – #588 [Tom King]
  • Don’t include query string when looking for image on file through imageTag() – [Per Djurner]
  • Format numbers in paginationLinks() – [Per Djurner]
  • Correct plugin filename case on application startup – #586 [Chris Peters]
  • Clear out cached queries on reload – #585 [Andy Bellenie]

Also don’t forget to check the upgrade notes.

Tags:
Posted in Releases | Comments Off on CFWheels 1.4.5 maintenance Release

10 years of CFWheels / Welcome Adam / CFWheels 2.x

March 23rd, 2016 by Tom King

A bit of history:

It’s slightly hard to put an exact date on it, but this year (probably) celebrates 10 years of CFWheels!

Obviously, in the internet age, 10 years is an awfully long time. The first mention I can find if from Pete Freitag’s “Get Wheelin” blog post celebrating CFWheels 0.1 in November 2005. Rob Cameron, the original author moved over to Rails full time a few years later: you can catch up with him at http://ridingtheclutch.com/. Over the years there have been a lot of contributors – whilst our GitHub repo hasn’t quite got that (very) early history, since Jul 23, 2006, we’ve had:

  • 2825 commits (Per Djurner has the dubious claim to fame of the first commit, and at time of writing, the most recent too :))
  • 22 Branches
  • 43 Releases
  • 76 forks
  • 453 issues

Whilst there was a “bit of a break” around 2012/13, Wheels has been going from strength to strength. Contributors have changed and moved on, and so have core team members. Our thanks go out to all of them!

Welcome Adam!
We’re very pleased that Adam Chapman (@chapmandu) has agreed to join the CFWheels core team! He’s been a long-time supporter of wheels, we’re very glad to have him on board. We expect great things AC…. great things. 🙂 You can find Adam’s blog here.

CFWheels 2.x:

Lots of chat at the moment about the next major release of CFWheels – please do get involved on the Google group if you’ve got ideas. At the moment, amongst lots of micro improvements, we’re looking at:

  • integrating the ColdRoute plugin into the core:  ColdRoute allows you to define RESTful resources through new expressive routing helpers and controller conventions. It also allows you to organize controllers and views into subfolders via “namespaces” or “modules.”
  • improving wheels as a true RESTful service provider: you can already return JSON, XML and lots of other good stuff, but we’re looking to improve things like setting custom headers, and really controlling your APIs response
  • improving the plugin architecture, and generally looking a more “modular” way of doing things.
  • dropping CF8/9 support; dropping Railo (as you should all be on Lucee now!!)
  • better Commandbox support: we’ll be looking at CLI type stuff to make getting going with wheels even quicker.

Got an idea? Get on the Google Group and let us know!

Posted in Community | 1 Comment »

CFWheels 1.4.4 maintenance Release

December 10th, 2015 by Tom King

Today sees another maintenance release for the 1.4.x series

Download 1.4.4 today to fix the following:

Bug Fixes

  • Check global “cacheActions” setting – #572 [Andy Bellenie, Per Djurner]
  • Fixed parsing for SQL IN parameters – #564 [Lee Bartelme, Per Djurner]
  • Pass through all arguments properly when using findOrCreateBy – #561 [Per Djurner]
  • Make it possible to disable session management on a per request basis – #493 [Andy Bellenie, Per Djurner]
  • Allow mailParams to be passed through to sendEmail() – #565 [Tom King]
  • Fixed inconsistency in form helpers for nested properties – [Marc Funaro, Per Djurner, Chris Peters]
  • Fixed issue with grouping on associated models – [Song Lin, Per Djurner]
  • Made the pagination() function available globally – #560 [Chris Peters, Per Djurner]

Also don’t forget to check the upgrade notes.

Tags:
Posted in Releases | Comments Off on CFWheels 1.4.4 maintenance Release

CFWheels 1.4.3 maintenance release

October 16th, 2015 by Tom King

Today sees another maintenance release for the 1.4.x series

Download 1.4.3 today to fix the following:

Bug Fixes

  • Fix for using cfscript operators in condition and unless arguments.
  • Added try / catch on getting host name since CreateObject(“java”) can be unavailable for security reasons.
  • Fixed bug with cache keys always changing even though the input was the same.
  • Remove white space character in output.
  • Use correct path info in error email and debug area.
  • Fixed plugin injection issue on start-up.
  • Skip calculated properties that are aggregate SQL functions in the GROUP BY clause.
  • Fixed error when trying to validate uniqueness on blank numeric properties.

Also don’t forget to check the upgrade notes.

Tags:
Posted in Releases | Comments Off on CFWheels 1.4.3 maintenance release