Setting Up An ExpressionEngine Site In Freeway

Before we open Freeway we need to change something in our ExpressionEngine control panel. We'll need to login to our Control Panel, click on the Templates tab, and then select Global Template Preferences, and then near the bottom of the list we will need to change the radio button to Yes for Allow Templates to be Saved as Files. This is a necessary step to getting our site working properly.

Also in this window we'll need to set the basepath for our template files to be saved in as file versions. In the next step we're going to be creating the folder for it, so let's go ahead in this step and enter the folder name of site_files into the template basepath.

What we want to do next is to create a folder in our htdocs folder that we just set as our basepath to our template file directory in the previous step.

Open up Freeway 5 Pro and we'll want to create a new document and before we click OK we need to make sure that Common Resources Folder is selected and then we can click OK.

The next step is setting the Web Address to where the ExpressionEngine site will be accessed including the http:// prefix. We can set that by going to File then choosing Document Setup and then under the Upload tab is the field Web Address. If the site will be at a top root level folder, it will be at http://localhost:8888 address. If the site is planned to be in a subfolder then the Web Address would http://localhost:8888/sub-folder name depending on the name of the subfolder. In this instance we'll be using the http://localhost:8888 address provided by MAMP. Once we've finished entering our address, click OK.

NOTE: If you're not using MAMP then you'd change it to your domain name and/or domain subfolder.

The next step is creating a folder structure in our Site Panel in Freeway. We need to have it mirror the ExpressionEngine folder we previously setup in our htdocs folder. In Freeway our top level folder, usually called Site Folder, should be the folder that gets its contents uploaded to the location we just put in the Web Address field in the previous step. So we'll then need to create a folder called site_files to match the name used in the third step.

Any page that gets developed for ExpressionEngine must have a published filename that ends with an extension of .php. We'll need to make sure throughout our design process that our published pages end with this extension or else ExpressionEngine will not recognize them as a template. With that said, a quirk starting out with using ExpressionEngine with Freeway is that you cannot publish the site folder in Freeway without a page existing at the root level. So, what I do is rename that first page under the site folder to be blank.php. This page requires no content and is simply there to enable Freeway to publish without error.

Before we get past this and move onto more Freeway based things, let me explain to you how the templating system in ExpressionEngine works. We'll be creating template groups which are folders of individual templates that are organized for various purposes. For instance you could create a site template group that would house templates related to the site itself and then you could create a search template group that would house templates related to search capabilities on your site. You can have an unlimited amount of templates within a template group, but I'd encourage you to stay organized.

Now that we understand how ExpressionEngine works, let's go ahead and create one new folder, which essentially will be a single template group, named site. This folder that we just created (and a rule for all newly created template group folders) can only be one deep from the site_files folder we created earlier. This means that your template group can't have sub-template groups: only one deep. We're also going to go ahead and create a new page in our site template group and name it index.php. In your Site Panel, your folder structure should now look like the image above.

Next we'll apply the folder action EE Resources to the site_files folder. You can also apply the EE Resources action to individual template pages if necessary. To apply the folder action you'll need to have your site_files folder highlighted and go to Page (1), hover over Folder Actions (2) and then choose EE Resources (3).

In your Actions palette you'll receive some options to choose from. I am going to take the liberty here and take an excerpt from Joe's existing manual on what each option does.

The first option, “Links to templates to path variables,” when checked, converts links between your Freeway pages to EE path variables, allowing EE to handle the redirection from one template page to another. This is the primary function of the Action and you will want to leave this checked.

The second option, “Leave template_group out of path,” when checked, makes the path variable only refer to the template page. This is useful when you are using an .htaccess file to rewrite your site’s URLs for a “cleaner” look. In most cases, you will want to leave this option unchecked.

The third option, “Alert when links won’t get modified,” when checked, will let you know that you have a link on a page that does not appear to be a link to another template page in a folder inside the “template_files” folder. While this link appears to be a link internal to your Freeway document, it may be an external link that is not complete, such as “apple.com/logicpro” If you are intentionally creating a lot of these links, you may want to uncheck this option to avoid multiple warnings. However, it can be a useful safety feature if you don’t think you will be creating these links and want to be warned if you do.

The fourth option, “Absolute path to resources,” when checked, with convert all the paths to Freeway resources such as images and style sheets to absolute links. This is necessary because EE hides the actual locations of the template files and thus these resources. In order to use these resources, these paths need to be converted.

The fifth option, “Use / instead of full URL,” when checked, creates a relative path to Freeway resources and style sheets. If you have the fourth option checked and this one unchecked, the links to the resources will be converted to something similar to “http://localhost:8888/Resources/theimage.gif”. If you have this option checked as well, this link instead will be “/Resources/theimage.gif”.

When you have completed choosing the action options, you'll need to copy your files to the htdocs folder. To do so, since we're using this locally with MAMP, we'll use Freeway's upload option of File Copy. To do so go to File and choose Upload. Then from the drop-down at the top change it to File Copy and then select the htdocs folder using the Finder window. Once you've done that, click OK.

Now we need to set up ExpressionEngine so that it recognizes our template group and published file. Go ahead and login to the ExpressionEngine Control Panel. We will then click on the Templates tab. If there are existing template groups created, and this is your first time, you can go ahead and delete those groups by selecting each group individually in the left box (site and search should be there by default) and choosing Delete Group from the middle box. You'll then agree to delete the group in the next screen and then the system will automatically return to the Templates tab. Then we'll want to create a template group in ExpressionEngine for the template group (folder) we made in Freeway called site. We'll need to make sure that we also check the box for Make the index template in this group your site's home page? since this template group is going to house our index.php we created earlier. By doing this we're telling ExpressionEngine that this page should be used as the home page for our site. As you create more template groups and templates you won't need to check this box. Once you have made the necessary changes, click Submit.

For each template that we make from now on we'll need to make sure that inside each individual template group (folder in Freeway) that there are no matching file names. We'll also have to click on each template in their individual groups and once we do so we'll have to check the box that says Save Template as File at the bottom of the screen. You will receive an error at the top that says Unable to save your template as a text file and this error is normal so you can go ahead and ignore it.

Once you have done these steps you will be able to update your templates in Freeway and then upload them without having to edit them by hand in ExpressionEngine. You have to remember to create new templates and template groups in ExpressionEngine using the steps above for any new templates. That's it, your Freeway document is setup to be used in ExpressionEngine.