Recently I did a webinar on Refactoring Legacy Code and the question came up about whether or not it was possible to use Coldbox with existing code without converting everything to a Coldbox module or making changes to the existing codebase. In the first installation in this series, we took a tour of the various elements which make up ColdBox. In this second installation, we are looking at creating layouts, views, and routes in the main site.
In the first installation of this post, we took a quick tour of ColdBox and defined the eight parts of ColdBox:
- Routes
- Layouts
- Views
- Handlers
- Models
- Interceptors
- Modules
- Tasks
- Scheduled Tasks
In this installation, we’re going to start looking at how a ColdBox site is constructed. Please see the first installment details about the forgebox project located at https://www.forgebox.io/view/coldbox-existing-code-blog.
After installing the myco module and starting the server in the /coldboxsite folder, visit http://myco.local/myco to see some configuration items and links to the examples here.
Creating / Adapting our layout
A layout is the template for your page. It might consist of the <html>, <head> and <body> tags as well as any styling which was universal to the site. By convention, ColdBox uses /layouts/main.cfm as the layout but you can change this.
Step 1: Duplicate /layouts/main.cfm and call it mycomain.cfm. Make some changes to mycomain.cfm so you can see that it a different file (Change something that says Ortus to myco or something.)
Step 2: Open the /config/coldbox.cfc and find the entry for configure() method. In that method, there will be the line:
layoutSettings = { defaultLayout : "", defaultView : "" };
If it isn’t changed already, change that to
layoutSettings = { defaultLayout : "mycomain", defaultView : "" };
Since this changes the ColdBox configuration, you will need to reinit the framework by using ?fwreinit=1.
Open the browser to http://myco.local/ (?fwreinit=1 if needed) and you should see your changes to the layout.
Creating our First View
If you look in /layouts/mycomain.cfm you will find the code renderView(). This will take the assigned view and display it inside the layout. By convention, ColdBox will use “/views/main/index.cfm” as the default view but you can change this several ways. The first is to change the layoutSettings.defaultView setting in /config/coldbox.cfc like we did for the layout above.
Step 1: Create the file mycotest.cfm in the /views folder. It can say anything you want (such as “This is mycotest!”).
Step 2: Assuming you’ve already started the server in the /coldboxsite folder, open your browser to http://myco.local/mycotest. If you get an error, add ?fwreinit=1 to the end of the URL and reload. This forces the ColdBox framework to re-initialize so new or edited routes, modules, handlers etc can be loaded. Even though there is no route defined for /mycotest, ColdBox can associate that URL with a view of the same name. However, we don’t want to always leave our sites up to simple conventions so next we are going to explicitly define a route for a view.
Creating our first Route
Open the Router.cfc file in the /config folder at the root of the ColdBox site. Even though this is a router, it is just a CFC which has a function called configure. The framework looks for this Router.cfc and runs configure() as part of its initialization when it starts up. If the file isn’t there, it’s skipped.
In configure() you’ll see several calls to route() which is where you, probably obviously, define and configure your routes.
Step 1: Create another view called mycotest2.cfm and put some text in there so you can identify it.
Step 2: Add route(“/mycotest2”,”mycotest2”) to the /config/Router.cfc in config(). Place it above this code, around line 29.
route("/mycotest2","mycotest2");
// Conventions based routing
route( ":handler/:action?" ).end();
Open the browser to http://myco.local/mycotest2. You should see your view inside of your layout.
Creating Our First handler
We don’t always want to have our URLs, views etc simply follow convention and sometimes they will need some pre-work before they can effectively display anything. The next step in our complexity ladder is to create a handler.
Step 1: Add route(“/mycoHandler”,”Myco.firstHandler”) to /config/Router.cfc in config()
Step 2: Create a CFC in the /handlers/ folder called Myco.cfc.
Step 3: Create the following method in /handlers/Myco.cfc:
function firsthandler(){
event.setView("main/steve");
}
Step 4: Create the file /views/main/steve.cfm and put some text in there to identify it.
Open the browser to http://myco.local/mycoHandler. You should see your layout with the view, steve.cfm inside of it. Notice how in this case, steve.cfm is in a subfolder of /views called /views/main/ and that is reflected in the handler.
Conclusion
We’ve looked at several aspects of ColdBox and how they work. However, we haven’t tied it into our existing code yet. That is happening in installation 3. Promise!!!
Did you miss the June Webinar - Getting started with the Legacy Migration with Dan Card
We will look at the process of converting legacy .cfm based sites into a more modern coding design which has less overall code, is easier to maintain and manage, mistakes and errors can more readily and speedily identified and fixed, and is easier to read.
Legacy Migration Follow Up: Using Coldbox with an Existing Code Base with Dan Card
July 29th 2022: Time 11:00 AM Central Time ( US and Canada )
Dan Card will be presenting a follow up to his June webinar: Getting started with the Legacy Migration. Dan received some good questions, so July's Webinar: Legacy Migration Follow Up: Using Coldbox with an Existing Code Base with Dan Card. If you have a more traditional / legacy codebase, and are wanting to modernize with ColdBox, but don't know where to start, this webinar is just for you!
Register now: https://us02web.zoom.us/meeting/register/tZArde-srjgiGtUVIWhhVRmMpSgang6yqCzA
Find out more about Dan Card's workshop at Into the Box - Legacy Code Conversion to the Modern World
This one-day workshop will focus on converting legacy .cfm based sites into a more modern coding design that has less overall code, is easier to maintain and manage, mistakes and errors can be more readily and speedily identified and fixed, and is easier to read.
Add Your Comment
(1)
Jul 23, 2022 01:58:57 UTC
by Derek
Thanks for this Dan!