Introduction to CakePHP for Web Designers

CakePHP for web designers, is a series of hands-on tutorials that help new programers and those with a design background understand the basics of CakePHP. There is plenty of theory and API documentation out there on the web; I’d rather spend my time writing about hands-on examples of how you can start using CakePHP today.

CakePHP hits the sweet-spot for many of my projects. The conventions and “baked” in classes are huge productivity boosters. Even if you just intend of working with visual elements on a CakePHP project (views), this series will walk you through hands-on lessons of building a simple task management application with CakePHP.

Installing CakePHP

This series is focused on working with CakePHP, so I don’t want PHP installation interfering with the content of this series. I’ve included installation notes at the bottom of this tutorial to get Apache, PHP, MySQL going. For a full explanation of how to get CakePHP set up properly, see section 3.1, 3.2, 3.3 and 3.4 of the CakePHP book.

In a nutshell, you will download CakePHP’s latest stable version at http://cakephp.org and upload the files somewhere inside the apache document root on your development machine. I’ve installed a fresh version on http://localhost/cakephp-designers/

cakephp_designers_01

What you see in screenshot #1 is the default CakePHP page with info about your environment configuration. Obviously, we don’t want this to be the homepage of our website, but it’s nice to see something when we get CakePHP installed correctly. This page has useful information about your configuration, and potentially, gives you warnings of steps you missed during setup.

CakePHP applications follow the MVC software design pattern which we will tackle later in this series. Learning the MVC software paradigm is essential to using CakePHP, and the payoff is clean code that is more secure and easier to maintain. This post will be focusing on the “V” in MVC, or the View.

Navigate to your project’s app > views folder. Create a folder called “pages” and inside pages, create a file called “about.ctp”. The file extension “.ctp” is CakePHP view files and accepts HTML and PHP code. Lets add a basic placeholder for our about page in about.ctp:

<h1>About</h1>
<p>This is the about page for our application</p>

Navigate to your newly create page by navigating to your project url. Mine is http://localhost/cakephp-designers/pages/about Notice that our page is displaying much more than our simple HTML. View the source and you will see the entire HTML structure of your project. The doctype and other HTML code belong to the layout.

Your Layout

Right now our project is using the built-in CakePHP layout, but we want to work with our own layout. By default, CakePHP looks for default.ctp in app > views > layouts but if you look in your project you will not find default.ctp anywhere. Create default.ctp and throw in the following HTML:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
	<title>Tasks</title>
</head>
<body>
	<?php echo $content_for_layout; ?>
</body>
</html>

Nothing special here except $content_for_layout. This variable is the output of your view. If you browse to your about page now, you will see the new template in action, and and unstyled site.

Create two more pages, in app > views > pages called index.ctp and contact.ctp and paste in the following:

<h1>Contact Us</h1>
<p>Contact info for our application will go here.</p>

and

<h1>Welcome!</h1>
<p>Welcome to my task management site.</p>

Linking

Now we have three separate pages, but no way to navigate between each page. CakePHP has a built-in helper called the HTML Helper that makes navigation links within a CakePHP application a breeze; and you can be certain that your links will always work when you follow conventions, no matter where the application resides.

We could easily create static anchor tags and call it a day, but we would be penalized in the future when we update our routes.php file or if we moved the application to another location. With static HTML links, all links would have to be manually updated each time routes.php was modified with a custom URL pattern.

Lets build the navigation using CakePHP conventions. Open default.ctp and add the navigation to this file so it will always appear in any view using default.ctp:

<div id="navigation">
	<?php echo $html->link('Home', 
            array('controller' => 'pages', 'action' => 'index')); ?> |
	<?php echo $html->link('About', 
            array('controller' => 'pages', 'action' => 'about')); ?> |
	<?php echo $html->link('Contact Us',
            array('controller' => 'pages', 'action' => 'contact')); ?>
</div>

cakephp_designers_02

If you view your project in a web browser, you will notice the magic that CakePHP performed. All the links were generated with the correct url. Unfortunately, if you click on the home link, it goes to the default CakePHP screen. We can fix that with routes.php.

Routes

Routes are an advanced topic, so we will only lightly touch on their power. Routes enable you to do magical things with your URLs and how those URLs relate to your application logic. For now, we only want our index.ctp file to be the homepage our our application. Open routes.php in app > config folder. Around line 34, you should see the default route for the homepage. Lets modify it from this:

Router::connect('/', array('controller' => 'pages', 'action' => 'display', 'home'));

to this:

Router::connect('/', array('controller' => 'pages', 'action' => 'display', 'index'));

Save and close routes.php. Make sure you only modify the above code–this file is critical to CakePHP. The routes.php file now considers index.ctp the homepage of the application, and you will now see your homepage in your web browser.

Styling Your Application

To conclude this tutorial, lets add some basic styles to our application. Your website assets are all located in app > webroot in their respective folders. The Webroot folder is the webroot of your application, so http://localhost/cakephp-designers/css in our project points to app > webroot > css.

Browse to app > webroot > css and create a file called style.css. You will also notice cake.generic.css which is the default css file used on the default homepage.

Add the following CSS rules to style.css:

body {
	background: #ddd;
	font: 12px "Lucida Grande", "Trebuchet Ms", sans-serif;
}
#wrap {
	margin: 20px auto;
	background: #fff;
	width: 800px;
}
#navigation, #footer {
	background: #333;
	padding: 8px 10px;
	color: #fff;
}
#navigation a {
	color: #fff;
	text-decoration: none;
	font-size: 14px;
	margin: 0 15px;
}
#content {
	padding: 5px 20px;
}
#content h2 {
	margin: 0;
}
#footer {
	font-size: 11px;
}

Update default.ctp to match the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
	<title>Tasks</title>
	<?php echo $html->css(array('style.css')); ?>
</head>
<body>
	<div id="wrap">
		<div id="navigation">
			<?php echo $html->link('Home', 
                            array('controller' => 'pages',
                            'action' => 'index')); ?> |
			<?php echo $html->link('About',
                            array('controller' => 'pages',
                            'action' => 'about')); ?> |
			<?php echo $html->link('Contact Us',
                            array('controller' => 'pages',
                            'action' => 'contact')); ?>
		</div>
		<div id="content"><?php echo $content_for_layout; ?></div>
		<div id="footer">
                    Copyright © <?php echo date("Y"); ?>. All Rights Reserved.
                </div>
	</div>
</body>
</html>

cakephp_designers_03

There are some new things in default.ctp that you might have noticed. In the of the document, I used another HTML helper method called “css” which generates a link tag to each css file listed in the array. This method automatically links to our css files in the webroot folder. This requires no additional configuration in the future, and is an important convention in CakePHP. I also threw in a date() function to show off vanilla PHP in our templates =).

Now our application is beginning to look alive, but in a boring, static way. Our next tutorial in this series will fix that, as we cover models and controllers. We must cover both simultaneously as models and controllers work closely together to deliver dynamic data in view files.

Conclusion

We just tapped the surface of the powerful features of CakePHP views. CakePHP has made it easier to create a consistent workflow for designers and developers. As you will begin to understand, following CakePHP and MVC conventions make life easier for future developers working on your applications.

We’ve covered a vast amount in a short span, but most of the learning will come from experimenting and diving into the code. Please feel free to ask questions in the comments or email me directly.

Notes:
CakePHP has a few requirements (http://book.cakephp.org/view/28/Requirements), which will work with pretty much any machine. In a nutshell, you need to configure Apache (enable mod_rewrite), PHP 5, and MySQL to get CakePHP going. CakePHP is flexible and compatible with both PHP 4 and PHP 5. Please use PHP 5. Please? Thank you.

My favorite guide for installing Apache, PHP, and MySQL is contained in PHP Solutions by David Powers. I recommend purchasing this book if you are just learning how to program PHP. David Powers is a wonderful instructor, and the book does a marvelous job of teaching new programmers PHP. Other more simple solutions include MAMP (mac) and PHP on Windows for Windows users. I am assuming Linux users can get LAMP going and don’t need advice :D

Depending on your configuration, you might need to add RewriteBase /path/to/your/cake/files/ to each of your .htaccess files to get CakePHP url rewriting to work properly. If you give up on getting this working, you can open app > config > core.php and uncomment line #57 //Configure::write(‘App.baseUrl’, env(‘SCRIPT_NAME’));. You must also delete all .htaccess files to not use mod_rewrite.

13 thoughts on “Introduction to CakePHP for Web Designers

  1. The blog was really helpful to me.Till now i were very confused about its views.But this article

  2. Been looking for this for a while. Thank you so much, CakePHP is actually not that bad at all…

  3. You’re a life-saver. Thanks so much for this well detailed tutorial.

    :) Will look forward for more CakePHP tuts.

    Have a great day!

  4. great tutorial for beginners! but im just wondering, are there any improvements in new cakephp version since you created this tut? probably new techniques. thanks!

  5. Hi,

    Brilliant tutorial but are you going to update it so it is current with CAKE 2.0?

    I had trouble with getting the nav links to work but that’s because it’s written in CAKE 1.2.

    If anyone else is having problems with the nav links the correct code is…

    Html->link(‘Home’, array(‘controller’ => ‘pages’, ‘action’ => ‘index’)); ?> |
    Html->link(‘About’, array(‘controller’ => ‘pages’, ‘action’ => ‘about’)); ?> |
    Html->link(‘Contact Us’, array(‘controller’ => ‘pages’, ‘action’ => ‘contact’)); ?>

    *****************And change the code on where it gets the content from to the below too **************

    fetch(‘content’); ?>

    ************** Hope that helps :) Going to carry on to pt2 now *************

  6. Just so you know – the helping code I just added hasn’t rendered properly… it’s missing the first bits of (without the spaces of course)

  7. oh wow that hasn’t worked either, sorry – it should show this

    (without the full stops of course)

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>