The sample data is in a MS SQL Server database. The table contains a record ID, title id, author id, genre, type, last check out date, and edit date. It is possible to have duplicate title, author IDs in the table. We need to extract all DISTINCT title IDs, along with the other information listed where the type is not a paperback, and provide a paginated list. I am sure this would be better architected if needed in the real world. Paginate will only get us so far, as this would only show all records.

class BooksController extends AppController {
    var $paginate = array(
        'order'        => array('Book.id' => 'desc'),
        'fields'    => array('Book.id', 'Book.title_id', 'Book.author_id', 'Book.genre_id', 'Book.type', 'Book.check_date', 'Book.edit_date'),
        'limit'        => 15,
    );
    . . .
    function index(){
        $this->set('hardback_books', $this->paginate());
    }
}

We need to use more to build a conditional query so the paginate will query against this. We can use CakePHP’s data source to help in this. Now, we could also just write this query out ourselves, but this is helpful to know so when you have to build sub-queries for other items. All data is in MS SQL Server, and we can use normal SQL expressions, but we need to grab DISTINCT data, which goes by rows, not columns, which means we will need to do 2 sub-queries in addition to the main one. So we first need to grab a list of the TOP 1 items. This will be our inner query.

        SELECT TOP 1 *
        FROM [books] AS [bk_inner]
        WHERE
            [bk_inner].[title_id] = [Book].[title_id]
            AND
            [bk_inner].[type] <> 'paperback' 

Next, we need to encapsulate that query with an outer one that will select all items which match up to the main query ID.

    SELECT * FROM
    (
        SELECT TOP 1 *
        FROM [books] AS [bk_inner]
        WHERE
            [bk_inner].[title_id] = [Book].[title_id]
            AND
            [bk_inner].[type] <> 'paperback'
    ) AS [bk_outer]
    WHERE bk_outer.[title_id] = Book.[title_id] 

So we have the queries, and it needs the main query needs to constrain the results that exists in the sub-queries.

SELECT TOP 15
    [Book].[id],
    [Book].[title_id],
    [Book].[author_id],
    [Book].[genre_id],
    [Book].[type],
    CONVERT(VARCHAR(20), [Book].[check_date], 20)
    CONVERT(VARCHAR(20), [Book].[edit_date], 20)
FROM [books] AS [Book]
WHERE EXISTS
(
    SELECT * FROM
    (
        SELECT TOP 1 *
        FROM [books] AS [bk_inner]
        WHERE
            [bk_inner].[title_id] = [Book].[title_id]
            AND
            [bk_inner].[type] <> 'paperback'
    ) AS [bk_outer]
    WHERE bk_outer.[title_id] = Book.[title_id]
)
ORDER BY [Book].[id] desc

We have the final full query. Now how do we get that? First, we need to invoke the getDataSource() method.

class Book extends AppModel {
    . . .
    function getHardbackBooks(){
        $dbo = $this->getDataSource();

Next we need to use the buildStatement() to build each statement. Since CakePHP will build a sub query with this, we have to do this twice: once for the inner query, and once for the outer query. The “table” for subquery2 will actually be subquery1, so we need to add that as a “table” in the array.

$subquery1 = $dbo->buildStatement(
	array(
		'fields' => array('TOP 1 *'),
        'table' => $dbo->fullTableName($this),
        'alias' => 'bk_inner',
        'limit' => null,
        'offset' => null,
        'joins' => array(),
        'conditions' => 'bk_inner.title_id = Book.title_id AND bk_inner.type <> \'paperback\'',
        'order' => null,
        'group' => null

	),
	$this
);

$subQuery2 = $dbo->buildStatement(
    array(
        'fields' => array('*'),
        'table' => '(' . $subquery1 . ')',
        'alias' => 'bk_outer',
        'limit' => null,
        'offset' => null,
        'joins' => array(),
        'conditions' => 'bk_outer.[title_id] = Book.[title_id]',
        'order' => null,
        'group' => null
    ),
    $this
);

Now, we need to make sure we add an EXISTS:

$subQuery = ' EXISTS (' . $subQuery2 . ') ';
return $subQuery;

Return the data from the model to the controller. In the controller function we need to add a new condition to the paginate. In the conditions, we do not need to use a paired item value to set it, we can use the straight SQL returned from the model.

class BooksController extends AppController {
    var $paginate = array(
        'order'        => array('Book.id' => 'desc'),
        'fields'    => array('Book.id', 'Book.title_id', 'Book.author_id', 'Book.genre_id', 'Book.type', 'Book.check_date', 'Book.edit_date'),
        'limit'        => 15,
    );
    . . .
    function index(){
        $data = $this->Book->getHardbackBooks();
        // Set to the paginate object conditions
        $this->paginate['conditions'] = array($data);
        $this->set('hardback_books', $this->paginate());
    }
}

And it returns the items based on the paginate parameters, ready to use in the view. It provides a DISTINCT list. And yes, I know I used more than 400 words in this one. It was closer to 500 without the code. Oh well, maybe tomorrow will be shorter.

CakePHP

CakePHP provides some functionality for finding the data, this is done using the “find” method. You can read more about this at the Cookbook. Using this, one can grab data from many different tables if needed, or just one table. For this exercise, I am going to use dummy data to show how to find data, using simplistic finds, and using joins, and sub-queries. So first lets examine the data tables. Not all of these are going to be connected. This is a very simplistic, quickly drawn up solution to a lending library

Sample Tables

In the image above, shows some sample tables, and these are just made up, and contain sample rows that may exist in those tables. The BOOKS and AUTHORS tables are a HABTM relationship, with a connecting table. The PUBLISHERS has many BOOKS. And the INVEN_ITEMS contains a multiple list of books that show whether the book is available or not. So we can start grabbing the data.

First we need to get a count for all books.

$total_books = $this->Book->find('count'); 

Now grab all authors, age, bio, book name, total pages, publish date for a single book with the ID of 212:

$details = $this->Book->find('first',
    array(
        'conditions' => array(
            'Book.id' => '212',
        ),
        'fields' =>array(
            'Book.name',
            'Book.pages',
            'Book.publish_date',
            'Author.name',
            'Author.age',
            'Author.bio',
        ),
        'recursive' => 0,
    )
);

This will create a query statement to grab the data for the set fields, and only for the book id that equals 212. Recursive is set to 0 so it will grab all related data. Remember that this is a HABTM item, so CakePHP will take that into account and grab all authors for the book. We can leave off the recursive, I just find it is best practice to put this in in order to make the query more readable by someone who did not develop the application.

Find all Publishers:

$publishers = $this->Publisher->find('all'); 

Now three example of using the find technique in a basic way. More examples are available in the cookbook. Now what if we need to grab all the detailed information on the inventory items, and the tables are not connected in a CakePHP relationship? Without using a framework, the query statement would need to contain JOIN statements to get all the data we need. So the following is an example of this, again getting detailed info for the Book ID of 212:

$details = $this->find('first',
    array(
        'joins' =>array(
            array(
                'table' => 'books',
                'alias' => 'Book',
                'type' => 'LEFT',
                'conditions' => array(
                    'Book.id = Inven_item.book_id',
                ),
                'recursive' => -1
            ),
            array(
                'table' => 'books_authors',
                'alias' => 'BookAuthor',
                'type' => 'LEFT',
                'conditions' => array(
                    'BookAuthor.book_id = Book.id',
                ),
                'recursive' => -1
            ),
            array(
                'table' => 'authors',
                'alias' => 'Author',
                'type' => 'LEFT',
                'conditions' => array(
                    'Author.id = BookAuthor.author_id',
                ),
                'recursive' => -1
            ),
            array(
                'table' => 'publishers',
                'alias' => 'Publisher',
                'type' => 'LEFT',
                'conditions' => array(
                    'Publisher.id = Book.publisher_id',
                ),
                'recursive' => -1
            ),
        ),
        'conditions' => array(
            'InvenItem.book_id' => '212',
        ),
        'fields' =>array(
            'Book.name',
            'Book.pages',
            'Book.publish_date',
            'Book.quick_overview',
            'Author.name',
            'Author.age',
            'Author.bio',
            'Author.country',
            'Publisher.name',
            'Publisher.location',
            'Publisher.state',
            'Publisher.country',
            'InvenItem.isbn',
            'InvenItem.available',
        ),
        'recursive' => -1
    )
);

For whatever reason, the Inventory was not connected to the other tables, and so we force a join on the query. In the JOINS, we set this to a -1 recursive so it does not pull in all the other data. Now this is only one solution to put an example of a JOIN on a query. We have the tables, joined in tables, conditions, and recursive set. Once you get the data, then it will show all inventory items, details for the book, and whether or not the copy is available at the present time.

Now this may not be the best way to grab the data, and this is just for example purposes as well. Next week I will go further into detail about setting multiple conditions using ‘OR’ instead of ‘AND’, creating a simple search on possible conditional search terms and areas, and I may even create a quick little app to demonstrate this in real life.

The data we need for this application includes some basic information: movie title, genre(s), stars, directors, writers, story information, rating, release year, rent price. We can include a lot more data if we really needed to, but for the purpose of this, we will keep it a little simple. A possible way of modeling this data is to create a table that stores all of this information, and have one table in the database. But now when we need to add something else, we have to add columns to the table. For example, in a few months the company decided to add related titles, sequels and sets, etc. It would require a refactor of the data in order to handle this, as well as refactor of the code. So lets split this out.

In the image below, I divided the content based on a few things: Title data, Talent Data, Genre Data, Rating Data

Starting the data model design

I now have the four main tables, but we need to figure out how these are related. First lets tackle the Rating Data, as that will be a simple design. I am linking to the IMDB so you can look at the data. The ratings available in the United States, at least the ones we will include, are: G (General Audiences), PG (Parental Guidance suggested), PG-13 (Parents strongly cautioned) and R (Restricted, no one under 17 allowed without a parent, or as I call it, PG-17). So each rating will be housed in this table. We will need an identifier, the rating, the explanation, and some data to track creation and modification. We do not need those last two, but it is just good practice to include those if there is ever going to modification on data. Using our example film, it is rated “R”. And since any film title object (Titles) will ever only have one rating (for the sake of this example) there is an easy relation of a hasOne relation to the Ratings table. We need to add a foreign key to the Titles table and connect these.

Title hasOne Rating

Easy to connect those. Now, we need to tackle the Genres. This is a little more complicated, but we can get through this. The Genres table will house the genres we need to display. This list can be as big or small as needed. Our example movie is in the “Drama” genre according to IMDB. However, in our application, the business has decided the movie is classified as Drama and Action. So now a title is going to have many genres. And a genre can belong to many titles. The “Drama” genre may belong to multiple titles. So we can not just add a new column to the Titles table, as that will not satisfy the requirements. We need to add a connecting table, and according to the naming convention of CakePHP, the name of the connector table is the alphabetical order of the two tables it is connecting.

So we need to add a table titled “Genre_Titles”. It will have an ID, and foreign keys to both tables.

Connecting the Genre and Title tables

Now we are almost done with the HABTM set up. We made it through one of them, and that was a good thing. See it was not so difficult. Now, we need to finish this up, and connect the talent table to the title. Talent can be anything. Since the company wants to display the stars of the show, the directors and writers, we need to be able to connect these. And again, this will require a a HABTM relationship. An actor can be in many titles, just like Clint Eastwood, as he was not just in Gran Torino. So he may be listed in many titles. And, with this movie, he not only stars in it, he directed it. So now we not only need to match up this talent, we have to identify it correctly. So this adds a little complexity to this, but we can do this.

As you know from the previous example, we need to create a connecting table. The name would be “Talent_Titles”. But that still will not solve the issue of identifying Clint Eastwood as an actor and director in the title. We can add a new table “Talent_Types”. This will be a “lookup table” that houses Star, Director, Writer as values. We can then connect that to the connecting table. This relationship will be a hasMany to Talent_Titles, as a star may have many entries in the Talent_Title table.

HABTM Talent and Title

And that is the HABTM design. Using the Bake method, you can now bake this up, and set up the model. The thing to remember about the HABTM, it is not something to fear. Usually, if a connecting table is needed, you have a HABTM design. Remember to think in human terms when examining the data model. What does this belong to, what does it have. In this, the Title will have many actors, directors, etc. And the actors, directors, etc will belong to many titles.

I still think the idea of the resume integrated with the API is a good one to show an example, but I am finding myself with less time to do a full blown app for it. And I figure, if I do a small example, that should be enough, and there is always the documentation available at Facebook for this. So if you have been following the Graph API integration, it still will happen, just in a different form.

If you Baked each object, and used the Bake methods to create the model, and associations, as well as the controllers an views, you will have some code ready to use and ready to go. After you have Baked these items, the sample code that is created is ok to begin with. However, we want to take advantage of a very important technique, and the is the centralization of code, and prevent code duplication. There is one other thing that gets to me, and this is more of an OCD thing for me in code, and that is the way that Cake does the edit check in the controller. In the base created code, it creates a section of code that checks for an ID. If it is not passed, then it redirects the page elsewhere. Like so:

function edit($id = null) {
    if (!$id && empty($this->data)) {
        $this->Session->setFlash(__('Invalid resume', true));
        $this->redirect(array('action' => 'index'));
    }
    . . . .
}

So in this code segment, if one gets to the edit form, and an ID is passed, and the form is not filled in, then it will display the actual form. And if the ID is not passed in, then it redirects to the Index page. For examples, if the site name was test.com:
www.test.com/resume/edit/2 – will result in the form being shown
www.test.com/resume/edit – will result in a redirect and the error message

Now here is where my OCD kicks in a little. . . .

If the table is housing 3 resumes, IDs of 1,2, and 3 and you go to the edit page for those resumes, it will display the resume content. But, for kicks and giggles, what if we passed in this as the URL:
www.test.com/resume/edit/350

This will display a blank form and even allow one to input data, fill it out, and submit it. Now granted, the processing of it alone will provide a new resume. However, that is why we have an “Add” function. Why not create some logic to check to see if the ID is valid to begin with? This will help on both the edit, and view methods in the controller. (as the View function will behave the same way as the edit function on display). And it is not just for this controller, but it will likely be an issue in all controllers. What I did in this case, is provide a function in the App Model code so that it can check those. Here is one way to solve this. And there can be multiple ways to resolve this issue, this is just one method I have done.
In the app/app_model.php code:

function ifExists($model = null, $id){
    if ( ($model == null) || ($model == '') ||(is_null($id)) ||($id == '') ){
        return 0;
    }
    $check = $this->find('count', array('conditions' => array($model . "." . strtolower($model) . '_id' => $id)));

    return $check;
}

The way I set up my models for the primary key is tableName_id. So for the resume table, the primary key is “resume_id”, and for the skills table it is “skill_id” and so forth. You can always modify this to use whatever naming convention you use. In this function, it checks to see if the model is passed. If it is not, returns a false. If a model is passed, then it runs a quick find query to see if that ID exists in the table. If it finds anything, then it returns a “1″ (or true), if not, then a “0″ (or false). By sticking this in the app_model.php file, it is now accessible by all models. To use this, in the edit function, for example, in the resume controller:

function edit($id = null) {
    if ( ((!$id) || (!$this->Resume->ifExists('Resume', $id))) && empty($this->data)) {
        $this->Session->setFlash(__('That Resume does not seem to exist, please try this again.', true));
        $this->redirect(array('action' => 'index'));
    }
    . . .
}

This will check for an ID, checks to see if that resume exists, and that the form is not filled in yet. If the ID does not exist in the table, then it redirects to the Index page, with a customized message. I could also redirect to the add page with no message, and this is entirely up to you on how you want to do this.

For the View function, it is very similar:

function view($id = null) {
    if ( (!$id) || (!$this->Resume->ifExists('Resume', $id)) ) {
        $this->Session->setFlash(__('That Resume ID does not seem to exist. Please try again', true));
        $this->redirect(array('action' => 'index'));
    }
    . . .
}

Again, check for an ID, and then make sure it exists in the table. If not, then redirect. A small bit of code to help keep the application from having odd behavior and keep it clean.

Next is to process the forms. By using Bake, it creates two functions, add and edit. Both process the forms as needed. Which there is nothing we can do to clean that up. However, some basic pre-commit tasks are still to be done. One thing I am highly in favor of is sanitizing the data. If there is some basic checks we need to do on the data, then we must also do that as well. For this we, will use the jobs controller/model for the example.

In each row of the job, we have a start date and an end date. In the model, we will validate these fields to be a “date”. We also need to validate these dates in another way. The end date can not be earlier than the start date. It is quite impossible to end a job three months before you even start it. So we want to keep that in check as well. And let’s say we want to do that in the controller. So now we need to sanitize the data, and check the dates. This can be redundant in the code, as it will exist in the edit and add functions. And if we need to make a change to the logic, it will cause an issue in two places. So, we can take that and put this in its own function. First we start with the sanitation of the data. At the top of the file, place

App::import('Sanitize');

Then create a new function and place the sanitation in this function:

function validateForm($data){
    $san = new Sanitize();
    // Clean the data
    $this->data = $san->clean($this->data);
    $this->data['Job']['company_name'] = $san->paranoid($this->data['Job']['company_name'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
    $this->data['Job']['via_company']  = $san->paranoid($this->data['Job']['via_company'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
    $this->data['Job']['location']     = $san->paranoid($this->data['Job']['location'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
     . . .
}

In this, I am cleaning the Company Name, the Via Company (in case it was a contract job), and Location. The next thing we need to do is create the logic to test the dates.I am just going to create a simple number using the fields from the form. Then I will compare the 2 numbers, and if the end is less than the start, then it is an error. So the entire function is:

function validateForm($data){
    $san = new Sanitize();
    // Clean the data
    $this->data = $san->clean($this->data);
    $this->data['Job']['company_name'] = $san->paranoid($this->data['Job']['company_name'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
    $this->data['Job']['via_company']  = $san->paranoid($this->data['Job']['via_company'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
    $this->data['Job']['location']     = $san->paranoid($this->data['Job']['location'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
     . . .   

    $errors = array();

    // Set the dates in a usuable format
    $start = $data['Job']['start_date']['year'] . $data['Job']['start_date']['month'] . $data['Job']['start_date']['day'];
    $end   = $data['Job']['end_date']['year'] . $data['Job']['end_date']['month'] . $data['Job']['end_date']['day'];
    $today = date('Ymd'); 

    // Check to make sure the start date is not later than the end date
    if ( $start >= $end ){
        // $this->Job->invalidate('start_date', "The Start Date must be earlier than then End Date");
        $error['err']['field'] = 'start_date';
        $error['err']['messg'] = 'The Start Date must be earlier than then End Date';
    }

    // Check to see whether or not to include the end date as part of the insert
    if ( $end == $today ){
        $error['end'] = 0;
    } else {
        $error['end'] = 1;
    }
    $data[error] = $error;
    return $data;
}

Now we need to be able to use that in the actual form. And we need to invoke an error in case there is an issue. If an error is found, we need to invalidate the field and provide the error message. That could be done in the following way:

function edit($id = null) {
    . . .
    if (!empty($this->data)) {
        $check = $this->validateForm($this->data);
        // Check to make sure the start date is not later than the end date
        if ( isset($check['Error']['err']) ){
            $this->Job->invalidate($check['Error']['err']['field'], $check['Error']['err']['messg']);
        }

        // Set the data to the model now
        $this->Job->set( $check['Job'] );

        if ( $this->Job->validates() ) {
            // Do the normal process/save stuff
            . . .
        }
         . . .
    }
    . . .
}

In this example, it shows how to find ways to cut down code repetition. Now I am sure we could even set this validation in the model as well. I am just giving an example of what we can do. Now using this, we can set up all the different functionality of the resume application.

In the next post, I will go through how to secure the Resume so only parts are seen by the world, and which parts you would have to log in for, and why. I will also go into a centralized query for all resume elements and be able to display.

1. The model is Topic, with a table in the DB labeled “topics”
2. Only the admin has access to add or edit the topics
3. All comments on this topic will be done through the Facebook API/Social Plugin Comments
4. Topics will have a title that will also double as the Unique ID (to be explained later)
5. Topic titles, or themes, will not be allowed to be edited, to be explained why later
6. Administration of the comments will be done by the Facebook Application admins, which differs from the site admins
7. Start Dates will determine if the topic is allowed to be visible yet
8. End dates are optional, and will be built upon later with more advanced FBML/FB JS libraries

And there it is, some basic ideas behind the whole idea. So now lets get into some of the items called out in Numbers 4 and 5

With the Facebook Comments, you can get a base idea behind what this entails at the following location:
http://developers.facebook.com/docs/reference/plugins/comments
This will give you the basic comment box to add to the site. The important part of this comment box is the “Unique ID”. This will add all the comments to the basic page. However, it must be Unique and not change. In my requirements above, I am listing the topic title as the Unique ID. I could easily generate a number for this and add a couple of letters to it to make it truly unique and allow the title to change. In this example, I want to emphasize certain elements, so that is why I chose to do it this way. You can easily do this differently and still have it work. But this leads to Number 5.

The Unique ID should not change for the page, topic, area, etc. If the ID changes, all previous comments vanish and you basically are starting over. So it is important that the IDs are unique and do not change. This way the element of participation is intact. It will always stay in your site.

Another note. This example is showing how to include Facebook API in a CakePHP application. You can follow these same techniques for just about any site, no matter what framework. Just apply the same inclusion techniques in the proper location for the different framework/php site.

Creating the base elements and DB table

So, let’s get this thing going. First you should have a CakePHP site going and ready, connecting to a DB somewhere. Bake the Model, Controller and Views for this one. The SQL for the Topics that I am using is below:

CREATE TABLE IF NOT EXISTS `topics` (
  `topic_id` int(11) NOT NULL auto_increment,
  `topic_slug` varchar(255) NOT NULL COMMENT 'Slug for use in the Facebook comments',
  `question` text NOT NULL COMMENT 'Question that is created for the different topics',
  `start_date` date NOT NULL COMMENT 'Start date for the question',
  `end_date` date default NULL COMMENT 'End date for the question',
  `created` datetime NOT NULL,
  `modified` datetime NOT NULL,
  PRIMARY KEY  (`topic_id`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8 COMMENT='Topics for discussions and other items' AUTO_INCREMENT=1012 ;

I baked this using the basic CRUD for the views and Controller, no Admin hooks, and the Model validation is as follows:

class Topic extends AppModel {
    var $name = 'Topic';
    var $primaryKey = 'topic_id';
    var $displayField = 'topic_slug';
    var $validate = array(
        'topic_slug' => array(
            'minlength' => array(
                'rule' => array('minlength', 3),
                'message' => 'The Topic Identifier should be longer than 3 characters',
            ),
            'maxlength' => array(
                'rule' => array('maxlength', 50),
                'message' => 'The Topic Identifier should be no longer than 50 characters',
            ),
        ),
        'question' => array(
            'minlength' => array(
                'rule' => array('minlength', 3),
                'message' => 'You need to have a question at least 3 characters long',
            ),
        ),
        'start_date' => array(
            'date' => array(
                'rule' => array('date'),
                'message' => 'Please set a valid start date for this question',
            ),
        ),
    );
}

Controller work for the Index

I removed all the links to Add, Edit and Delete from the views and kept those hidden except for the Admin. Now comes the controller. This is the important part of this, as we need to include the Facebook items, and based on the last post, we put those in the Vendors, so we need to include this. I am also using Sanitize, Auth and few others (Security and Email), along with the helpers of HTML and FORM.

<?php
App::import('Sanitize');
App::import('Vendor', 'facebook');
class TopicsController extends AppController {

    var $name = 'Topics';
    var $helpers = array('Html', 'Form');
    var $components = array('Security', 'Auth', 'Email');

it is important to import the Facebook library. I will not go over the Auth in this example, or the beforeFilter or isAuthorized functions. The first action we need to deal with is the index() function. Originally, it looks like:

function index() {
        $this->Topic->recursive = 0;
        $this->set('topics', $this->paginate());
    }

For our purposes, we want to limit the amount of posts shown to only those that have a start date that is equal to or less than today’s date. I have three examples in my DB, and you can create as many as you want for the example. Just make sure at least one is in the future. Right now when we look at the Index page, it is showing all topics. So we need to set different items in the call for paginate. To only grab those that are equal to or less than to today’s date, we will alter the call to paginate as follows:

$today = date('Y-m-d');
$cond = array('Topic.start_date <=' => $today);
$this->set('topics', $this->paginate('Topic', $cond));

This will limit all the posts to display to everyone to only those with a current (or past) start date. All those with a start date in the future will not be available until that date. But we also need to set a variable for the Admin to see all those topics waiting for the future.

$future_topics = $this->Topic->find( 'all', array('conditions' => array('Topic.start_date >' => $today)) );
$this->set('futop', $future_topics);

We now have 2 variables to work with in the view. You can do it a whole slew of different ways, and that is fine, this is just the method I prefer to do it. Now we need to get the view going. This is going to a little different, I have a few things to show Admin stuff just to admins, and show the future topics just to admins.

The Add and Edit functions

That does it for the view, now we need to do the Add and Edit functions. Remember we baked this, and let all the default take place. But, I need to get a valid Unique ID, and do not want any spaces in it. So we will alter the Add function to do this. And for the Edit function, we want to prevent any editing of the slug area.

function add() {
        if (!empty($this->data)) {
            $san = new Sanitize();

            $this->data['Topic']['topic_slug'] = $san->paranoid($this->data['Topic']['topic_slug'], array(' '));

            $this->Topic->create();
            // Slug the topic title before saving
            $this->data['Topic']['topic_slug'] = preg_replace('/ /', '_', $this->data['Topic']['topic_slug']);
            if ($this->Topic->save($this->data)) {
                $this->Session->setFlash(__('The new Topic has been saved and will be put in queue', true));
                $this->redirect(array('action' => 'index'));
            } else {
                $this->Session->setFlash(__('The Topic could not be saved. Please, try again.', true));
            }
        }
    }

I am sanitizing the data for the slug, and trusting myself for the topic details. In real life, we would apply a sanitizing effect to this field as well. I then erase all non alphanumeric characters, and replace spaces with an underscore “_”. Then save it up. I am basically leaving the “add.ctp” alone with what was baked. I removed the fields that I really do not care about.

So now we move to the edit. We want to prevent any changes to the topic_slug, so in the form, we will remove this from the form and make sure we remove the underscores when showing it. The controller is:

function edit($id = null) {
        if ( ((!$id) || (!$this->Topic->ifExists('Topic', $id))) && empty($this->data) ) {
            $this->Session->setFlash(__('The Topic you selected does not exist, please try again.', true));
            $this->redirect(array('action' => 'index'));
        }
        if (!empty($this->data)) {
            if ($this->Topic->save($this->data)) {
                $this->Session->setFlash(__('The topic has been saved', true));
                $this->redirect(array('action' => 'index'));
            } else {
                $this->Session->setFlash(__('The topic could not be saved. Please, try again.', true));
            }
        }
        if (empty($this->data)) {
            $this->data = $this->Topic->read(null, $id);
        }
    }

One quick thing to call out in this function. I added a new function to the parent app_model.php to make sure that the ID we are trying to edit exists and is valid. The basic baked function only checks for an ID, if one exists, it goes thru to the form, even if the ID does not exist in the DB. On the edit.ctp view, I removed the form element for the topic_slug and added this:

$topic_title = preg_replace('/_/', ' ', $this->data['Topic']['topic_slug']);
echo "<b>Topic Title</b>:   <h4>" . ucwords($topic_title) . "</h4>";

And now the edit form works, keeps the underscore in and saves the form. Again, in the real world, you would want to do a little more on the back end to ensure there is no changes being made. But now we get to the view area and where the Facebook API/Social Plugin comes in.

Creating the Detail View and adding in Facebook API/Social Plugin

So here is where we get to the meat of the post. All other areas were in preparing to get here. Now, all you need to do is create a few different topics to work with. We want to alter the view in such a way it will display only the items we need, and will only display the topic to an admin if it is a future topic. Otherwise return the user to the index for topics with a message saying that the topic does not exist or is not yet available. So the view function is simple:

function view($id = null) {
        if ( (!$id) || (!$this->Topic->ifExists('Topic', $id)) ) {
            $this->Session->setFlash(__('The requested topic does not exist. Please try again.', true));
            $this->redirect(array('action' => 'index'));
        }
        // Make sure this is a valid ID as well
        $topic = $this->Topic->read(null, $id);
        $topic_title = $topic['Topic']['topic_slug'];
        // Set the title without the slug
        $topic_title = preg_replace('/_/', ' ', $topic['Topic']['topic_slug']);
        $topic['Topic']['topic_title'] = ucwords($topic_title);

        // make sure this topic is valid
        if ( ($topic['Topic']['start_date'] > date('Y-m-d')) && (!$this->is_admin) ){
            $this->Session->setFlash(__('The requested topic does not seem to be available at the present moment. Try again later.', true));
            $this->redirect(array('action' => 'index'));
        }
        $this->set('topic', $topic);
    }

Again, I used the app_model.php function to make sure the topic ID exists as well as being valid. If not, a message will be displayed to the end user. It sets the topic, and now we are ready for the view.

So what I did, was wipe all the data for the list, and added my own. I set the title to the H2 element. I set the question to a paragraph tag, and added the new FBML comment tag. The information for this tag can be found at:
http://developers.facebook.com/docs/reference/fbml/comments_%28XFBML%29

Pay close attention to the different parameters you can set and how you can format this to fit your style on your site. I have set the following elements and values:
xid = $topic['Topic']['topic_slug']
width = 600
title = $topic['Topic']['topic_title']
publish_feed = false

And so the actual markup added to the page is the following, including the FBML script and div tag:

<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js#appId=APP_ID&xfbml=1"></script>
<fb:comments xid="<?php echo $topic['Topic']['topic_slug']; ?>" width="600" title="<?php echo $topic['Topic']['topic_title']; ?>" publish_feed="false"></fb:comments>

And if you go to the page you will now see the comments section, but we are missing a very important item in the comments, and that is administration. The way to add this, we will need to add the correct element to the page. This consists of adding the correct JS API to the site.

According to the documentation, you have to be listed as a developer for the application to be able to administer comments. The way we have it set up right now, we can have comments, but there is no way we can administer those. The key to this is very simple and easily overlooked. In the FBML markup that we added to the view, you will notice a specific section:

http://connect.facebook.net/en_US/all.js#appId=APP_ID&xfbml=1

You must input your application ID to this markup. Once you do that, and if you are listed as a developer, then you are able to now administer comments on your site.

See, that was easy. There is a lot of text on this post, and most of it has to do with setting up CakePHP to do this. Once we got to the Facebook API/Social Plugin section, it was very simple. With the next post, we will expand on the comments section a little further and see what else is possible.

You can see this all in action at the following:
www.stephenhird.com

So lets go ahead and dive into it. If you do not have the application ID for your Facebook application, you can get it at the following:

http://www.facebook.com/developers/apps.php

The next thing is to grab the API and code from Facebook. This can be found at the following page:

http://developers.facebook.com/docs/

This is the main page, and you will need to scroll to the bottom of the page. This will list different APIs that are available. I am going to be using the PHP and JavaScript SDKs. This will provide the back end that I will want, and will also provide a positive user experience on the front end. So be sure to download both SDKs.

After that, now we need to start getting some stuff set up. In this post, I am just going to explain how to get this set up, and working right now. It is important that we get the correct items working, and so we will be working with the “pages” area for the JS SDK, and creating a very simple controller for the PHP SDK so we can get set up and running. I am just using, for right now, the base CakePHP CSS styles and layouts. All we need is a page to display some of the basic items to ensure that we have installed the SDKs in the proper locations. So lets go.

Step 1: Download the SDK and move them to the following locations:
A. PHP SDK (facebook.php)
I put this at the following location:
./app/vendors/facebook.php
This will be used in the controllers and be imported by the controllers

B. JavaScript SDK
I put the entire “src” directory in the following location:
./app/webroot/js/src

Step 2: Create a “test” page where we can see the Facebook JS SDK to make sure it works
I just created a new file:
./app/views/pages/facebook.ctp
This will be visible at the following: http:///pages/facebook

Step 3: Copy the example in the jQuery folder, alter your default layout
Reformat the example after you copy it to the ./app/views/pages/facebook.ctp to take out the header stuff. We only need the body, and make sure you put the header stuff in the default layout. Below is the code to add to the default layout:

<!doctype html>
<html xmlns:fb="http://www.facebook.com/2008/fbml" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <?php echo $this->Html->charset(); ?>
    <title>
        <?php __('CakePHP: the rapid development php framework:'); ?>
        <?php echo $title_for_layout; ?>
    </title>
    <?php echo $this->Html->css('cake.generic'); ?>
    <?php echo $scripts_for_layout; ?>
    <style>
        body {
            font-family: 'Lucida Grande', Verdana, Arial, sans-serif;
        }
        h1 a {
            text-decoration: none;
            color: #3b5998;
        }
        h1 a:hover {
            text-decoration: underline;
        }
    </style>
</head>
<body>

Simple code to put in to test the JS API:

<h1>Connect JavaScript - jQuery Login Example</h1>
    <div>
      <button id="login">Login</button>
      <button id="logout">Logout</button>
      <button id="disconnect">Disconnect</button>
    </div>
    <div id="user-info" style="display: none;"></div>

    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>

    <div id="fb-root"></div>
    <script src="http://connect.facebook.net/en_US/all.js"></script>
    <script>
      // initialize the library with the API key
      FB.init({ apiKey: 'YOUR API KEY WOULD GO HERE' });

      // fetch the status on load
      FB.getLoginStatus(handleSessionResponse);

      $('#login').bind('click', function() {
        FB.login(handleSessionResponse);
      });

      $('#logout').bind('click', function() {
        FB.logout(handleSessionResponse);
      });

      $('#disconnect').bind('click', function() {
        FB.api({ method: 'Auth.revokeAuthorization' }, function(response) {
          clearDisplay();
        });
      });

      // no user, clear display
      function clearDisplay() {
        $('#user-info').hide('fast');
      }

      // handle a session response from any of the auth related calls
      function handleSessionResponse(response) {
        // if we dont have a session, just hide the user info
        if (!response.session) {
          clearDisplay();
          return;
        }

        // if we have a session, query for the user's profile picture and name
        FB.api(
          {
            method: 'fql.query',
            query: 'SELECT name, pic FROM profile WHERE id=' + FB.getSession().uid
          },
          function(response) {
            var user = response[0];
            $('#user-info').html('<img src="' + user.pic + '"><br />' + user.name).show('fast');
          }
        );
      }
    </script>

Now, you should be able to go to your page and see a login button, a logout button, and disconnect. If you are already logged in to Facebook, you should see your own profile image (if you allowed it). If not, click the login button, and if you have the Facebook application set up correctly, and the API correct, you should be able to log in.

Step 4: Check the PHP API
Now that we can see the JS API is working fine, we need to set up something so we can create a test for the PHP API. This is actually easier than it appears.

I first create a new layout just for the Facebook app, which I call facebook.ctp. It basically just erases all Cake icons, other special icons, and any kind of SQL output. Rename the title to “Facebook Testing:” (or whatever you want). Then create a new controller with no model. Use the App::importstatement to include the facebook.php file. Now create an index function, and copy and paste the PHP area from the example included in the PHP SDK into the “index” function. It may be similar to this:

<?php
App::import('Vendor', 'facebook');
class FbsController extends AppController {
	var $name = 'Fbs';
	var $uses = null;	

	function index() {
	    // Set the layout
        $this->layout = 'facebook';        

        // Create our Application instance (replace this with your appId and secret).
        $facebook = new Facebook(array(
            'appId'  => 'YOUR APPLICATION ID WOULD GO HERE',
            'secret' => 'YOUR SECRET KEY HERE - DO NOT DISPLAY THIS TO ANYONE',
            'cookie' => true,
        ));

        $session = $facebook->getSession();
        $appID   = $facebook->getAppId();
        $uid     = '';
        $me = null;
        // Session based API call.
        if ( $session ) {
            try {
                $uid = $facebook->getUser();
                $me = $facebook->api('/me');
            } catch (FacebookApiException $e) {
                error_log($e);
            }
        }

        $logoutUrl = '';
        $loginUrl  = '';

        // login or logout url will be needed depending on current user state.
        if ( $me ) {
            $logoutUrl = $facebook->getLogoutUrl();
        } else {
            $loginUrl = $facebook->getLoginUrl();
        }
        // Set the variables to use in the view
        $this->set(array(
            'facebook'  => $facebook,
            'session'   => $session,
            'me'        => $me,
            'logoutUrl' => $logoutUrl,
            'loginUrl'  => $loginUrl,
            'appID'     => $appID,
            'uid'       => $uid,
        ));
	}
}
?>

In this controller, we are setting the basics we need for the application. Using the SDK to see if they are logged in, getting our app id, and setting the proper variables to be used later. We set the login or logout URLs to display the proper links. Finally, we are setting the variables to be used in the view.

Now we need to create a new directory in the views area named “fbs” and a file in that directory named “index.ctp”. This view will house the base items for displaying the example. You can copy the HTML parts from the example.php and use them in this view. I modified it a little to alter what is shown.

<h2>Test Facebook File</h2>
<div id="fb-root"></div>
    <script>
      window.fbAsyncInit = function() {
        FB.init({
          appId   : '<?php echo $appID ?>',
          session : <?php echo json_encode($session); ?>, // don't refetch the session when PHP already has it
          status  : true, // check login status
          cookie  : true, // enable cookies to allow the server to access the session
          xfbml   : true // parse XFBML
        });

        // whenever the user logs in, we refresh the page
        FB.Event.subscribe('auth.login', function() {
          window.location.reload();
        });
      };

      (function() {
        var e = document.createElement('script');
        e.src = document.location.protocol + '//connect.facebook.net/en_US/all.js';
        e.async = true;
        document.getElementById('fb-root').appendChild(e);
      }());
    </script>

    <?php if ($me): ?>
        <a href="<?php echo $logoutUrl; ?>">
          <img src="http://static.ak.fbcdn.net/rsrc.php/z2Y31/hash/cxrz4k7j.gif">
        </a>
    <?php else: ?>
        <div>
          Using JavaScript & XFBML:
          <br />
          <fb:login-button></fb:login-button>
          <br /><br />
        </div>
        <div>
          Without using JavaScript & XFBML:<br />
          <a href="<?php echo $loginUrl; ?>">
            <img src="http://static.ak.fbcdn.net/rsrc.php/zB6N8/hash/4li2k73z.gif">
          </a>
        </div>
    <?php endif ?>

    <h3>Session</h3>
    <?php if ($me): ?>
        <pre><?php
        echo "session.base_domain - " .
            $session['base_domain'] . "<br />session.expires - " .
            $session['expires'] . "<br />";
        ?></pre>

        <h3>You</h3>
        <img src="https://graph.facebook.com/<?php echo $uid; ?>/picture?type=large" />
        <br />
        <?php echo $me['name']; ?>

        <h3>Your User Object</h3>
        <pre><?php print_r($me); ?></pre>
    <?php else: ?>
        <strong><em>You are not Connected.</em></strong>
    <?php endif ?>

The login button examples will show two different ways to authenticate the user to the application. The JS example will open a new window and will log them in, post it back to the page and show the login. The non JS example will take the user to the page and give them the Facebook page to log in. Once they log in, it then redirects back to the calling page.

The information on the page shows the Session info, and below that, it shows a large profile image of the person logged in, and then an array of data of all public accessible information. If the person has set their profile to be private, then it will not show a lot of information.

These two examples can be seen at the following, with screenshots below:
The JS SDK example
http://www.stephenhird.com/pages/facebook

JavaScript SDK prelogin

JavaScript SDK post-login

The PHP SDK example
http://www.stephenhird.com/fbs/

PHP SDK example pre login

PHP SDK example post login

In the next post, we will work on getting a good discussion going, which is really, really simple, we will tie it to a DB saved question that can be entered thru an admin form, and then we will examine the moderation of the Facebook comments on the discussion.

First I need to figure out what I want to have on my site. Since it is my name that is on the URL, I will need to create a way that this site will be an online portfolio, biography and information repository. When doing this for any site, it is important to remember your brand. Even for individual sites like this, it is important for branding, because this is who I am, I do not want it to be a classic case of slop on the web. This site before was mainly just a testing ground and now will need to be more.

A side note here, my name is the same spelling as a famous photographer based in London. His site is well put together with good descriptive links and a great example of combining minimalist ideas with styled presentation. He keeps his brand on the pages and the site does not confuse or mislead with extra peripheral items, or overuse of Flash or other heavy web technologies loading down the page. His site is located at: http://www.stephenhird.co.uk/

OK, now on to the planning and setting up the Facebook Application.

First I will list out my goals with the site, and why put it in a Facebook application. I am choosing to do this myself, however, these may not really warrant a full blown Facebook application with every site/web application.

1. Describe who I am
2. Display samples of my work, all work: code, art, etc
3. Provide a theme/question for comments and research
4. Provide contact information
5. Online Resume with ability for download (never hurts to have a resume handy)
6. Share my images from different travels and experiences
7. A place where I can see where I have been, where I am going and how to get there

This is the base ideas behind my site. This is for a more personal reflection tying into the other interests in my life.

I am planning on building the base in CakePHP, and adding the Facebook API in to the application. Which means this will also generate more posts on CakePHP application development. The back end will be a DB driven application, with all frontend interaction via Facebook login. All Admin functionality of the site will be outside of the Facebook authentication.

Now since I already have the site up, I need to create the application side in Facebook.

1. Log in to Facebook, or go to this URL: http://www.facebook.com/developers/apps.php
2. New policies for Facebook insist that you either enter a mobile number or a credit card to validate you are a real person. The phone number is what I would suggest to use.
3. After you enter the confirmation code, return to the main window to enter the name of the application and agree to terms
4. Put in the security check code
5. This will take you to the first part of the form

Now the form, it is a quick and easy form to fill out. There are four tabs and I will highlight each and a few items on each that I usually do:

1. About
   • Enter the application name, upload images, icons, etc.
   • Enter the support email or page, and put in a privacy page, very important if you want to have this application take off.
2. Web Site
   • Site url would be the site you are creating to work with the API
   • Domain is important if you want subdomains (for things like mobile domains, etc) to be authenticated using the same key
3. Facebook Integration
   • Canvas will determine how you want the page top appear inside Facebook.
   • This is also where you decide to do a FBML (their markup) or an iFrame. I usually choose iFrame mainly because in my applications the bulk of interactivity is done on the domain and not Facebook. However, you can always do FBML to keep everything in Facebook.
   • Profile tabs will enable new tabs on the app page that can be added/used on individual profile pages
4. Mobile and Devices
   • If you are developing for mobile users, enter the type of core markup to use, and the id for the iTunes app store. Important to read here if you plan on making a mobile app
5. Advanced>
   • Each section in this page holds a very important piece that may affect your application.
   • Authentication holds the sandbox keys, and where Facebook looks if a user takes your app off
   • Migrations holds the areas for callbacks, empty strings and OAuth
   • Security will allow you to enable only a few select IP addresses to access your application on the Facebook platform
   • Advertising and Advanced can do different things for ads, preloading, etc.

Above all else, read the side information if you get stuck, that is why it is there.

Once you are done, click the “Save Changes” button and it will save your data and create your application.

There, you have now just created a shell application on the Facebook platform and ready to enable the client side application.

In order to submit this application, Facebook posts this:
“Your application must have at least 5 total users or 10 monthly active users before you can submit it to the Application Directory. We cannot showcase any applications that are under construction or do not utilize the Facebook Platform.”

So do not expect to create an application and then suddenly have it spread like wildfire. It has to provide useful or entertaining “stuff”, it has to work, and it has to be used. Once it is, then it can be submitted. So we have accomplished step one of the integration. Next up is to get the API on the site, and start developing the site.

First off, here is the issue. I needed to be able to export a group of records from the database to an excel spreadsheet. I have tried to use the Excel Spreadsheet add in that is listed on the Bakery. It works nice, and I had to do some modification for 1.2, but it worked. But not the way I wanted it. I have used the PEAR library Spreadsheet_Excel_Writer before and I like the type of control that I wanted, over the cells, the formatting, the merging, etc etc etc. It provides the type of control that I wanted. So here is what I did to get this to work with the CakePHP framework.

First, I have to download the PEAR library and the Spreadsheet_Excel_Writer libraries to use. Since I use a local system to help develop, I could download these libraries to the local system and transport these over to the CakePHP application. So I went to PEAR site to get the libraries. To download these I ran the following commands:

pear install PEAR-1.8.1
pear install OLE-1.0.0RC1
pear install Spreadsheet_Excel_Writer-0.9.1

URL’s are listed below:

http://pear.php.net/package/PEAR/download

http://pear.php.net/package/Spreadsheet_Excel_Writer/download

http://pear.php.net/package/OLE/download

These downloaded the to local drives and I copied them over to the CakePHP area. Here is where it gets a little tricky. And I thank “brian” who helped me on the Cake Google group to get past this when I got into a problem. So here we go, diving in to this.

First off, the PEAR libraries need to be put in the vendors directory. If you look at the directory structure for Cake, it appears like this:
/app
/cake
/vendors

Inside of the /app directory, there is another vendors directory. This is where I put the PEAR libraries. This causes problems, because in the /cake/config/paths.php file, there is a path defined for VENDORS, and for PEAR:

if (!defined('VENDORS')) {
	define('VENDORS', CAKE_CORE_INCLUDE_PATH.DS.'vendors'.DS);
}

define('PEAR', VENDORS.'Pear'.DS);

Now, I have put the PEAR libraries in the top level vendor directory. If you choose to put it in the app/vendors directory, then you may need to change a core file, which is not advisable, because you would need to change the path above to

if (!defined('VENDORS')) {
	define('VENDORS', CAKE_CORE_INCLUDE_PATH.DS.'app/vendors'.DS);
}

So back to the PEAR libraries. Here is what I needed to do. I moved the PEAR directories to the /vendors directory. So here is what that directory looks like:

/vendors
    /css
    /js
   /Pear   <--- Look at this, case sensitive based on those paths above
        /OLE
        /OS
        /PEAR
        /scripts
        /Spreadsheet
        INSTALL
        LICENSE
        OLE.php
        package.dtd
        PEAR.php
        PEAR5.php
        README
        System.php
        template.spec
    /shells

This is part of the PEAR install we need to do. Now we need to update the paths in some of these files so that CakePHP can find them and include them.

**** ORIGINAL ENTRY THAT HAS BEEN EDITED/DEPRECATED ********************
**** EDIT: Based on the original post this is the method I originally used. This way works, but requires a
**** little too much overhead and editing the files in the PEAR libraries which is never really a good idea
**** and should only be used sparingly. To see the way that it should be done, please see below this
**** section.
****
**** In the file /vendors/Pear/Spreadsheet/Excel/Writer.php there is 2 requires
**** require_once 'PEAR.php';
**** require_once 'Spreadsheet/Excel/Writer/Workbook.php';
****
**** In order for the Cake App to see these, at least in my set up, I needed to change these to the
**** following:
**** require_once 'PEAR.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Workbook.php';
****
**** I needed to add "PEAR . " to the require_once call. Now I needed to add this to the following files:
**** /vendors/Pear/Spreadsheet/Excel/Writer.php
**** require_once 'PEAR.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Workbook.php';
****
**** /vendors/Pear/Spreadsheet/Excel/Writer/Workbook.php
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Format.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/BIFFwriter.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Worksheet.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Parser.php';
**** require_once PEAR . 'OLE/PPS/Root.php';
**** require_once PEAR . 'OLE/PPS/File.php';
****
**** /vendors/Pear/OLE/PPS.php
**** require_once 'PEAR.php';
**** require_once PEAR . 'OLE.php';
****
**** This had helped the application find my PEAR libraries when trying to do this
**** END ORIGINAL ENTRY ***********************************************

Now, a word about the edit. The above method works, but is not a preferred method. The best method for this, so there is no need to edit PEAR library files is the following. And a big thanks to Daniel Hofstetter for pointing this out.

I put this at the top of my controller file. I am sure there is better places for this, probably even the app_controller file so that all controllers get the needed include path set. Here is what I did.

I needed to append the include path so that the new PEAR path would be found. After the php opening, I added this line:

ini_set("include_path", PEAR . PATH_SEPARATOR . ini_get("include_path"));

I am going to go over this just a little. First off, the ini_set is called to set the include_path. But we do not want to destroy any other include paths that are set up as well. So when we add the PEAR path, we need to also include the other paths as well. So the initial include_path was as follows (given in example form only, where the directory "test" is where I have CakePHP installed)
ini_get("include_path") =

/www/htdocs/html/test:/www/htdocs/html/test/app/:.:/usr/local/php5/lib/php

Since CakePHP already defines the variable for the PEAR path as "PEAR", we can use that to add to the include path, like shown above. After setting the path using ini_set(), we run ini_get("include_path") it would =

/www/htdocs/html/test/vendors/Pear/:/www/htdocs/html/test:/www/htdocs/html/test/app/:.:/usr/local/php5/lib/php

By doing it this way, there is no need to edit the PEAR library files, and we can add new PEAR libraries without having to worry about editing those files as well.

Now, I needed to make the controller aware of the vendor library. In my controller file I added this line before the class declaration:

App::import('vendor', 'Spreadsheet_Excel_Writer', array('file' => '../vendors/Pear/Spreadsheet/Excel/Writer.php'));

In Cake 1.2, this is how the vendor's are imported. The vendor() declaration has been deprecated. This imports a vendor, gives the class a name (I choose the base one that it is usually called), and the location of the of the file. In my set up, I needed to add the "../", you may not have to.

In the function, (I called "export"), I did not want to have a "view" page for it. The first thing I did was grab the information I needed. For this example, I needed all users that signed up for a conference. So I grabbed that information and put it in an array $registrations.

function export ($id = null){
       // I only want to get a specific conference, not all of them
	if ( $id == 'all' ){
		$this->Session->setFlash('Please select a specific conference to export the registrations.');
		$this->redirect(array('action' => 'index'));
	}

	// Now get the registrations for the conference
	$registrations = $this->Registration->find('all',
		array(
			'conditions' => array('conference_id' => $id),
			'fields' => array('*'),
			'recursive' => '-1',
			'order' => array('Registration.created'),
		)
	);

Now comes the fun part, building the column heading array, and then instantiating the writer

	// Set up the header array
	$titles = array(
		'Name' => 15,
		'Address' => 20,
		'City' => 20,
		'State' => 7,
		'Zip Code' => 10,
		'Email' => 20,
		'Phone' => 13,
	);

	$rn = 0; // row number
	// Build the XLS file using PEAR
	$xlsBook = new Spreadsheet_Excel_Writer();
	$xlsBook->send("registrations.xls");
	$xls =& $xlsBook->addWorksheet('Registrations');

Everything else is now just as the same as it would be with the Spreadsheet-Excel_writer. Create the formats as you would like, for text, numerics, specialized strings, colors, etc. Write the sheet headings, if you so desire

	/* Create styles for the spreadsheet */
	$format_bold =& $xlsBook->addFormat();
	$format_bold->setBold();

	$main =& $xlsBook->addFormat(
		array('Size' => 14,
			'Align' => 'center',
			'Color' => 'black',
			'Bold' => 'true'
		));
	$main->setBold();

	$formatText =& $xlsBook->addFormat(array('Size' => 11));

	$cn = 0;
	$xls->write($rn, 0, "CONFERENCE REGISTRATIONS", $main);
	$xls->mergeCells($rn,0,$rn,11);
	$rn++;

As you can see, just use the writer calls to write the data, format it, and do what you need. To get more information on this, please check the PEAR documentation for this library.

Finish up the column headings by doing a quick little loop

	// Set up the headings of the columns
	foreach ( $titles as $t => $val){
		$xls->setColumn($cn, $cn, $val);
		$xls->write($rn, $cn++, $t, $format_bold);
	}
	$rn++;
	// reset the column num
	$cn = 0;

Now you can do the actual rows in a loop:

	foreach ( $registrations as $r ){
		$xls->write($rn, $cn++, $r['Registration']['name'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['address'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['city'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['state'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['zip_code'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['email'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['contact_phone1'], $formatText);
	    // cycle to the next row
	    $rn++;
	    // Reset the column
	    $cn = 0;
	}

	$xlsBook->close();
	exit();
} // end of function

Now, this does the work for me on my code. To call it in the view, I have a page that shows all registrations on the page, the function name is "registrations". I set a variable in this function for the ID number to be passed to the view. In the view for this function, I have put the following:

if ( $param != 'all') {
	echo "<p><br />&nbsp; &nbsp; &nbsp; - - <b>";
	echo $html->link(__('EXPORT DATA', true), array('action' => 'export', $param) );
	echo "</b> - - <br /><br /></p>";
}

So I want a specific conference. If there is not one, and they are viewing all registrations for all conferences, then it does not show the link. But if it is a specific id, then it shows the link to export with the corresponding parameter for the ID.

And there it is. Using the Spreadsheet_Excel_Writer PEAR library with CakePHP 1.2.

Again, this works for me, and there may be a better way of doing things, and if so, please feel free to tell me. I am always looking for new things to learn.

This is a very useful tool, and if you look at the PHP manual for ereg(), it states that the function “preg_match” is a faster alternative to “ereg()”. Now while I am not going to get into the details of the speed and response times for both functions, as there will always be someone with a different opinion or case that shows how their way is better, and that is fine. What most people have a hard time dealing with is getting the actual match to do what is needed. There are times when It is just easier to do a Google search and get some code that someone else has already done and plug it in. But the real power is knowing what you are doing first, that way you can build your own.

For this example, we can take a look at CakePHP’s own little validation object. When you set up a model and add some validation to it, it calls this object. Based on the data that this going into the tables, it will call one of these functions. The way these functions work is by checking the input for a specific character list/set that should be contained in the text. If the entry does not match up, then it is not validated. The way CakePHp does this is by using the preg_match() function.

If you are new to regular expressions, then seeing something like this:

define('VALID_EMAIL', "/^[a-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+\/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+(?:[a-z]{2,4}|museum|travel)$/i");

may be a little scary. But never fear, this is not as bad as it seems. It just looks real scary. And besides, even Cake made it a little better.

So let’s look at this function:

function email($check, $deep = false, $regex = null) {
. . .
	if (is_null($_this->regex)) {
		$_this->regex = '/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)*@' . $_this->__pattern['hostname'] . '$/i';
	}
	$return = $_this->_check();
. . .
}

function _check() {
. . .
	if (preg_match($_this->regex, $_this->check)) {
		$_this->error[] = false;
		return true;
	} else {
		$_this->error[] = true;
		return false;
	}
}

If you would like to know more about the function, then please browse to the CakePHP manual to get more info about that function, since all this is going to do is point out the regex part of it.

First off, the function called is “email”. In this function, there is a regex match set that is the following:
‘/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)*@’ . $_this->__pattern['hostname'] . ‘$/i’

It passes that to the _check() function, which puts this regex pattern to the email address that is entered to see if there is a match. So to jump ahead if someone were to put in an email address of:
– flavio@nothing.com
It would pass that function. (NOTE: this does not mean it is a valid email address that can recieve emails, it just means that the characters in the email address are in the valid format of (address_name)@(hostname).(Extension) )

But this also means that someone could put in the email address:
– flavio@nothing.show
And that would pass as well, while the following email addresses:
– flavio
– flavio@nothing
– flavioATnothingDOTcom
would fail.

But now that we know that, how did we get there?

Let’s break down the match.

The first thing, we are looking for a pattern, so we need to ad the following:
/ /
around the pattern. This is a Perl syntax that is followed for finding patterns. Now the bookends come, with the caret ( ^) and the dollar sign ( $ ). The caret means to search the beginning of the string for the pattern, and the dollar sign matches the end of the string. In this example, the caret matches the first part of the email address entered, and the dollar sign matches the end.

'/^[ ]$/'

So we are off to a good start. but there since we are looking for a pattern that does not need to be case sensitive, as we do not care if there are uppercase letters or not, we need to add an “i” at the end.

'/^[ ]$/i'

Now we are ready to start looking at the beginning of the string. We are going to put this in a bracket to group the characters, or create a class. We want to get any valid characters for an email address. This would include any letters, numbers and some special characters. We will need to escape some of these (using the “\” to escape)

'/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]$/i'

This will now look for the address name, sort of. As long as there are no periods in the address account name, it will work, but there are addresses out there that have a “.” in it:
– flavio.elguappo@nothing.com
would not pass the validation as of yet (given that we would have also added the domain by the time it is checked).

So we need to add that match set in to the expression. CakePHP does this by using an atomic grouping. Using the parenthesis usually means that a “backreference” should be done. You can escape this by using “?:”. The question mark-colon combo after the first parenthesis signifies that what is coming is not a backreference. Now, to get the addresses that have a period in the account name we add this:
(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)

As you can see, this is almost the same pattern as before. We want to check the same things again after any appearance of a period. So now it looks like:

'/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)$/i'

Last things here, we need to account for the @ symbol in the address, and add the domain name. Since CakePHP already takes care of that, they have there own addition:

'/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)*@' . $_this->__pattern['hostname'] . '$/i'

And the final php code would be as follows:

$checked = preg_match('/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)*@' . $_this->__pattern['hostname'] . '$/i', $email_address_to_check);

return $checked;

Now I am sure I glossed over some regex rules and explanations. I will never claim to be an expert on regex, as I am still learning as much as I can about this. Now this is not the only way to check an email address. If you do not use CakePHP and the real nifty built in helper, then you can use this one:

"/^[^0-9][A-z0-9_]+([.][A-z0-9_]+)*[@][A-z0-9_]+([.][A-z0-9_]+)*[.][A-z]{2,4}$/"

This one is similar, check the account name for valid characters, see if it has any periods in the name, check the @ symbol and then check the domain name, and then the domain extension, allowing for 2-4 characters in the extension.

And if you want to get some real good info on other regex info, here are a couple of links I found useful:
http://www.webcheatsheet.com/php/regular_expressions.php
http://www.regular-expressions.info/tutorial.html
http://us3.php.net/manual/en/function.preg-match.php
(Make sure you read the comments as they have some good info)