This document provides guidance on migrating a legacy ColdFusion application to the ColdBox MVC framework. It discusses assessing the current application, reasons to migrate such as improved code organization and developer experience. It warns that a full rewrite should be avoided and recommends a step-by-step refactor. Suggestions are given for converting the Application.cfm file to Application.cfc and adding ColdBox bootstrap code. The document also covers creating a layout, integrating ColdBox aspects, handling URLs, and shortening the feedback loop during the migration process.

1. Integrating MVC into
legacy
There is hope yet

2. The State of Your App
● What does your app look like?
● Using other frameworks?
● Partially converted to Coldbox?
● What are your goals?

3. Reasons to migrate to a modern framework
● Code organization
● Devs are all using the same organization and patterns
● Consolidated functionality like logging, caching, tier
detection
● Regular updates
● Makes your dev shop more attractive to prospective
employees

4. Gotcha’s
● You still have to write code
● Not a silver bullet
● Don’t try a full 100% rewrite
● Baby steps are better than trying everything new at once
● Refactor, refactor, refactor
● The pilot system (write a throwaway test)

5. Legacy/ColdBox App Demo
https://github.com/bdw429s/coldbox-legacy-app-demo
● Clone repo and start server
● Each page tells you how it works
● Half of the demo site runs legacy .cfm files
● Half of the demo site runs ColdBox handlers

6. Install ColdBox
● Environment (tier) detection
● Can use legacy checks for environment
● It’s ok for the ColdBox config to reference old application
variables
● It’s also possible to find/replace legacy code to use
ColdBox settings!

7. Application.cfm -> Application.cfc
● Convert <CFApplication> tag to “this.settings”
<CFApplication
name=”myApp”
sessionManagement=”true”>
this.name=”myApp”;
this.sessionManagement=”true”;

8. Application.cfm -> Application.cfc
● Watch out for transcendent variables scope
○ Use onRequest() if needed
function onRequest( targetPage ) {
variables.mySetting = “myValue”;
include arguments.targetPage;
}

9. Add in ColdBox bootstrap
● ColdBox is always loaded
○ onApplicationStart()
● You get to decide what requests will be
processed by ColdBox
○ onRequestStart()

10. Add in ColdBox bootstrap
● Non ColdBox requests need some magic for
Coldbox to be usable
application.cbController.getModuleService().loadMappings();
● You can manually announce core interception points
for consolidated logic
application.cbController.getInterceptorService().processState("preProcess");

11. Create a Layout
● Convert your main layout
● Reuse as much as possible via includes
● This will let you start converting views
event.setLayout( “main” )

12. Start plugging in ColdBox aspects
● Proactively convert legacy:
○ Logging -> LogBox
○ Caching -> CacheBox
○ CFC creation -> Wirebox
● This can happen outside of ColdBox!
application.wirebox.getInstance( “myService” )

13. Pick a site area to start
● Maybe something simple like login
● Move .cfm pages into a view
○ Implicit view dispatch
○ Swap out build links calls
<a href=”/login.cfm”>Login</a>
<a href=”#event.buildLink(“main.login”)#”>Login</a>

14. Handle external URLs
● Just change them and have people update
bookmarks
● Put in URL rewrites at the web server level
● Put in routing in your Application.cfc to
re-route to ColdBox

15. Shorten your feedback loop
● When you have a part of the app working, test it and RELEASE IT!
● Don’t try to save up and do a huge chunk. You’ll never finish!
● Use this as an opportunity to do script conversion, etc but don’t get
bogged down
● Employ group code reviews to discuss conventions and stay on the
same page
● Make sure you update your product owner so they know about your
progress!