[[Dashboard|<< Back to Dashboard]]
[[Category:level-advanced]]
{|align="right"
| __TOC__
|}

[[Category:setup]]

= Refactoring ColdBox =
{{{Messagebox message="Covers up to version 3.5.0" type="info"}}}

== Introduction ==
This guide will show you how to refactor the ColdBox codebase in order for you to embed it in a distributable application or just install in another non-standard installation.  In order to proceed with this guide you will need the following:

* Latest ColdBox [http://www.coldbox.org/download source code]
* [http://www.cfeclipse.org/ CFEclipse], [http://www.adobe.com/products/coldfusion-builder.html Adobe ColdFusion Builder], or any IDE that supports FIND/REPLACE 
* [http://ant.apache.org Apache ANT]

== Guide 1: ANT via Eclipse ==

The ColdBox installation folder contains a file called '''refactor.xml'''. This file is an ANT task for use in refactoring the ColdBox source code.  You should have a directory layout like the one shown below after downloading and extracting the latest ColdBox release:


<div align="center"><img src="/imagelibrary/refactoring_installfolder.png" style="border: 1px outset #eaeaea" /></div>

In this sample, ColdBox has been downloaded and extracted onto the desktop, in a directory called '''coldbox'''.  Once you have the '''coldbox''' folder, it's time to fire up [http://www.eclipse.org/ Eclipse] and create a new project. To do so, click on '''File > New > Project > CFEclipse > CFML Project'''

<div align="center"><img src="/imagelibrary/refactoring_newproject.png" style="border: 1px outset #eaeaea" /></div>

After selecting the CFML Project, choose a name for the project; in this sample it will be called '''ColdBoxRefactoring'''. Then select the location of the '''coldbox''' directory (on the desktop) and click on '''Finish'''.

<div align="center"><img src="/imagelibrary/refactoring_newproject2.png" style="border: 1px outset #eaeaea" /></div>


The project is created and you can see it in your project explorer. The next step is to open the '''refactor.xml''' file and refer to the following screenshot, which describes two properties: 

* '''coldbox.system_path''' : The location of the '''system''' folder
* '''coldbox.destination''' : Where to place the refactored code


<div align="center"><img src="/imagelibrary/refactoring_changingxml_step1.png" style="border: 1px outset #eaeaea" /></div>


Now, you will need to change the properties to your liking. I mostly just change the '''coldbox.system_path''' to: '''${basedir}\system''' which matches what you downloaded. You should have something similar to the screenshot below:


<div align="center"><img src="/imagelibrary/refactoring_changingxml_step2.png" style="border: 1px outset #eaeaea" /></div>


The next step is to actually execute the '''refactoring.xml''' ANT Task. To do this, open the install folder and right click on the '''refactor.xml''' file. A context menu will appear with tons of options, look for the one called '''Run As > Ant Build''' Look below:



<div align="center"><img src="/imagelibrary/refactoring_runtask.png" style="border: 1px outset #eaeaea" /></div>


Once you click on the '''Ant Build''', the task will execute and you will get a popup similar to the one below. In this popup, fill out the new prefix of the ColdBox path. The default one is '''coldbox.system''', and lets say that I want the new location of the framework to be on a folder called frameworks off my root and in a directory called '''coldbox_2_0'''.  Then I would type: '''frameworks.coldbox_2_0''' 
 

<div class="mynotes">
Do not add a final <b>.</b> this is appended automatically.
</div>




<div align="center"><img src="/imagelibrary/refactoring_task_step1.png" style="border: 1px outset #eaeaea" /></div>


After you click ok, then you will be asked for the absolute path of the new location. In my case I enter: '''/frameworks/coldbox_3_0'''


<div align="center"><img src="/imagelibrary/refactoring_task_step2.png" style="border: 1px outset #eaeaea" /></div>



Once you click the final OK, the ant task will execute and you will see the following output on the eclipse console:


<div align="center"><img src="/imagelibrary/refactoring_antconsole.png" style="border: 1px outset #eaeaea" /></div>


This means the task executed correctly and you are ready to use the refactored code. The final screenshot below shows you the refactored system folder in the install directory and a code snapshot of some changes. ENJOY


<div align="center"><img src="/imagelibrary/refactoring_final.png" style="border: 1px outset #eaeaea" /></div>




== Guide 2: Search and Replace ==

This guide is just a basic use of search and replace features of your favorite IDE, either Eclipse, Dreamweaver, or whatever.  All you need to do is the following:

# Search for '''coldbox.system''' and replace it with '''{Your Prefix}.coldbox.system'''
# Search for '''/coldbox/system''' and replace it with '''/{Your Prefix}/coldbox/system'''

Enjoy your refactored ColdBox recipe!