CHAPTER 15

Wrapping Up the Application

At this point, you've thoroughly explored the fundamentals of developing in Cake. With the blog application as your first advanced project, you built custom resources such as controllers, models, and views; and you extended those resources with others such as components, behaviors, DataSources, and helpers. But you are probably aware that the current blog application is not production-ready (you wouldn't make it available to any real users yet).

The blog does already have the main methods that allow you to add posts, tags, and users to the database and other methods that provide visitors with a way to comment on and read posts. Bringing the application into production just requires that you tie up a few loose ends.

In this chapter, I'll explain the final routines to consider when wrapping up a Cake application and making it ready to deploy. I won't go through the code line by line, but I will direct you to common tasks that put the finishing touches on your Cake projects. Consider the routines outlined here as exercises that will help you practice.

Designing the Home Page

Until now, I've pointed you to areas of the application by specifying a direct URL. For instance, when telling you to edit a certain action, I would write the path to that action with the full URL (like http://localhost/blog/posts/view/1). You will need to create a home page that contains all these URLs or at least a page that lists how to navigate to all the features you've built into the blog. Many novices begin with the home page before building the features of the application, which can lead to a cluttered starting point for their visitors. Design considerations aside, Cake, by its architecture and convention, promotes using dynamic methods as much as possible to generate site content. You can take advantage of what you've already built into the blog application to create the links that will direct the user to all other areas of the site.

The first step is to create a starting point. Then, you provide content and navigation that takes the user through the interface from that point to the next. You have two options for creating this starting point, or home page: you can use Cake's built-in Pages controller or choose an action to be the starting point, such as the Posts Index action.

Using the Pages Controller to Produce a Single View

Areas of the application that don't necessarily perform any logic or that assemble various methods from several controllers, like a home page, may need a view only. For your blog application, home needs to include only a couple of posts that link to their full-story view and the categories links you built in Chapter 14 with the Tree behavior. I would normally do this by adding onto the Posts Index action (which I'll describe in a moment) because I want some posts to appear on the home page. But what if I didn't want to display any posts on the home page or if the home page was a simple one with just a few links to the main areas of the site? In that case, it might be easier to write a simple view in static HTML.

The Pages controller is invoked out of the box; it is the method that renders the Cake welcome screen. Notice that in app/config/routes.php the default home page is listed as the top route:

You'll recognize from our discussion in Chapter 10 that this route connects the base path ('/') to the Pages controller's Display action. It also passes the parameter home to the action, thus rendering Cake's default home page, which is the welcome screen. Changing home to another value or creating a view file named home.ctp in the app/views/pages directory will point this base route to your own custom view. The Pages controller is already built into the core, so you do not need to create an app/controllers/pages_controller.php file by hand. Simply pass along the name of the view you want to render and create the corresponding view file (with the .ctp extension), and the Pages controller will automatically render the view for you.

Once you've created your own home.ctp file or created a custom one, you should be able to go to http://localhost/blog, and that view will be displayed. Simply add links in this view file that point to the Posts Index action and other areas of the site, and the user will be able to navigate through the blog just fine. Elsewhere in the site, you'll be able to point back to this home page by using the base path or by using more verbose links, like this:

Making an Action the Starting Point

To make the Posts Index action the home page, simply change the base route in app/config/routes.php. One way you could do this would be with the following route:

Now, when the user comes to the home page, the Posts Index view will be rendered, rather than the Cake welcome screen. Then, in the app/views/posts/index.ctp file, you could provide all the navigation to access other areas of the site. The benefit of using an existing action as the starting point for your application is that the logic needed to pull together various methods is already in place. Creating dynamic content like categories links is possible because the controller and model are already at work fetching that data. I prefer this method for building my home pages, but I have used the other methods in the past for specific reasons relating to the project at hand. Most important, however, is that you provide a home page or starting point that easily provides the necessary navigation and displays from across the application dynamically. Most of the time you won't want to manually update the home page, so the more you can allow the application to do that for you, the better.

Generating Dynamic Navigation

More complex navigation will likely require creating some kind of menu system in the application. The blog is already equipped to handle categories and rendering posts. It's easy to make a menu that is rendered in every view. (Displaying a menu is a good time to use an element instead of a layout or a helper.)

You could create a menu element like I've done with Listing 15-1 and call it in the various views throughout the site. Notice that I've checked the Session component to see whether the user is logged in, changing what links are available to the user accordingly. Of course, the login process would need to be built, preferably with the Auth component, but the element does work well for adjusting the interface to supply the links based on the status of the user's session.

Listing 15-1. The app/views/elements/menu.ctp Element

<div class="menu">
    <ul>
        <?=$html->link('<li>Home</li>','/',null,null,false);?>
        <?=$html->link('<li>Posts</li>',array('controller'=>'posts','action'=>
'index'),null,null,false);?>
        <?=$html->link('<li>Tags</li>',array('controller'=>'tags','action'=>
'index'),null,null,false);?>
        <? if (!$session->check('User')): ?>
            <?=$html->link('<li>Log In</li>',array('controller'=>'users',
'action'=>'login'),null,null,false);?>
        <? else: ?>
            <?=$html->link('<li>Add Post</li>',array('controller'=>'posts',
'action'=>'admin_add'),null,null,false);?>
            <?=$html->link('<li>Edit Posts</li>',array('controller'=>'posts',
'action'=>'admin_index'),null,null,false);?>
            <?=$html->link('<li>Log Out</li>',array('controller'=>'users',
'action'=>'logout'),null,null,false);?>
        <? endif;?>
    </ul>
</div>

Remember to call out your menu element in the view with the $this->element() view function:

Customizing the Overall Design

When preparing the application for production and when improving existing methods in the process, you will likely need to change the design of the views, usually on an individual basis. One important routine when wrapping up the application is to go through each view and interact with the site. Then, adjust the design as needed.

In this book, I stuck with Cake's built-in style sheet and HTML markup as much as possible. You will undoubtedly want to change the design to fit your needs. Most of the time, you'll work with CSS and HTML to tweak the design as you build the application. In the case of your blog application, now is a good time to go in and apply your own CSS and graphics to the design. Maybe you'll want to hire a graphic designer to do this part.

In any Cake project, reviewing the design and improving it where possible is an important routine when wrapping up the application. Sometimes you'll create new layouts, views, elements, and helpers at this stage to better separate the display elements and maintain a consistent structure for the code. Remember, where possible, to make sure that repeatable design elements are saved in a single place in the code. This is the programming principle called DRY—Don't Repeat Yourself. In this way, you're thinking ahead for any possible adjustments you may need to make in the future that will save you time.

Debugging the Application

Let's hope your Cake applications are built without too many errors creeping in. Nevertheless, an important routine when finishing the application is to double-check for any bugs. Testing deeper resources such as models, components, DataSources, and behaviors can be tricky when calling actions in the browser through the controller. Cake comes with a helpful test suite that allows you to run tests on models and components with sample data. You will need to have your app/config/database.php file correctly set to link with a test database and then run unit tests through what Cake calls fixtures. But performing unit tests with sample data can ultimately cut down on the amount of time you spend making your application's models error-free, especially if you build a lot of custom model functions. As you explore ways to work better with Cake, consult the online Cake community for details on running the test suite. Many features are still in development with some promising methods set for later release. (Mariano Iglesias has written an excellent tutorial on model testing with the built-in test suite at http://bakery.cakephp.org/articles/view/testing-models-with-cakephp-1-2-test-suite, which will help you get started working with fixtures; you can check out other test suite articles at http://bakery.cakephp.org/tags/view/test.)

Running the Application on a Remote Host

Once your application is ready for use on the Web, your final routine will be to move the project from your localhost environment to a remote host. If the remote host has the same settings as your localhost, you should be able to upload the parent application folder "as is" to a remote directory, and it should run just fine. You will need to run a MySQL dump file of some kind to mirror the remote and localhost databases.

To secure your application, you should place the Cake libraries and app folder outside the document root on your remote server. This requires that you make a couple of adjustments to the folder structure of the application and that you change a couple of global variables.

The three main folders you can move around on the server are cake, app, and webroot. The main catch when you do change the folder structure of the application is that the webroot folder must be available in a public directory or document root. Let's assume that my remote host is set up with a home folder (outside the document root) and www as the document root, while the domain points to user/home/www. To better secure the application, I place the Cake libraries and the app folder in user/home, and I take webroot out of the app folder and place it in user/home/www. Cake can handle this structure, but I must change some variables in user/home/www/webroot/index.php before it will compile correctly.

I open the webroot/index.php file and scroll to where I see three global constants: ROOT, APP_DIR, and CAKE_CORE_INCLUDE_PATH. Table 15-1 shows the path on the remote host that each constant should be assigned, given my current folder structure.

Table 15-1. Paths for My Remote Setup

Cake uses DS as the directory separator. So, I reassign these constants to their new paths following Table 15-1 and end up with what is shown in Listing 15-2. (Normally, there are a few comment lines in this file; I've omitted them from the listing.)

Summary

This chapter explained some important routines to consider when completing your Cake projects. Remember to provide a starting point in app/config/routes.php and to create navigational methods throughout the application to improve the user experience with the blog and any of your other Cake applications. Also, don't forget to check thoroughly for bugs in the code and to alter the design of the views to fit your methods. When deploying the application to a remote host, be sure to place the Cake libraries outside the document root and to adjust the webroot/index.php file accordingly.