WordPress has the wonderful capability of allowing specific pages to have custom templates. In the initial version of Muse’s Success, we exploited this capability along with custom fields to generate the listing directory and listing detail pages.

Firstly, I would like you to make a copy of your default pages template. This file is usually named page.php, and located in /wp-content/themes/[name of your theme]/ directory of WordPress installation. Name this copy, table_of_contents.php, and open it in your favourite text editor.

Add the following to line 1 of your table_of_contents.php. It needs to be the first thing in your file.

1
2

<?php /* Template Name: Table of Contents
*/ ?>

Find:

1

<?php the_content('<p class="serif">Read the rest of this page &raquo;</p>'); ?>

This line may be slightly different, your basically looking for an instance of <?php the_content(‘…’). ?> Don’t worry about what the single parameter, if any.

Immediately after add:

This is the basic code to output post titles in chronological order. You can make slight variations of this, and it in general depends on how you’ve been naming your posts. In my experience, most authors are placing the chapter number and title in their WordPress post titles, so this example is geared towards these authors, but I will show some alternatives at the end of this tutorial.

1
2
3
4
5
6
7
8
9

<?php
global $post;
$post_save = $post;
$category_id = get_post_meta($post->ID, 'toc_category_id', true);
$toc = get_posts('numberposts=-1&category='.$category_id.'&order=ASC&orderby=date');
foreach($toc as $post) :
?>
<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a><br />
<?php endforeach; $post = $post_save; ?>

Create the Page

Now, we have to create a WordPress page. You can do this by selecting Pages -> Add New in your WordPress Dashboard Menu. It’s up to you what you name your page, and what you write in the content area, but I would recommend the title is that of your book, and your content area contains a short introduction to your story (like what you would have on the blurb of a print book).

Select the Custom Template

Before you publish your page, we have a few special things we need to do to make the table of contents appear. You’ll need to select the Table of Contents template in the Attributes section (lower right) of the Add Page page as depicted.

Set the Custom Field

Next, we have to add a custom field. Custom fields can be added below the page content area. Name your custom field “toc_category_id” and set the value to the ID number of the category containing your posts. You can find the ID out by going to the Edit Categories (Dashboard menu -> Posts -> Categories) page, and clicking Edit under the category containing the posts that comprise your story. On the Edit Category page, take a look at your address bar, and you’ll see the text &cat_ID=. The number after the equals sign is your category ID.

Click Add Custom Field, and then Publish, and you’re done. If all went well, when you view the page you just created, you should see your new table of contents.

Using an ordered list instead

Earlier, I mentioned that there are other variations of the code that are suited to different post naming schemes. The one I showed earlier was a basic one title after another list using linebreaks.

If you are one who names their posts solely the name of your chapter with no number, you might like to use an ordered list to automatically add the chapter number for you.

1
2
3
4
5
6
7
8
9
10
11

<ol>
<?php
global $post;
$post_save = $post;
$category_id = get_post_meta($post->ID, 'toc_category_id', true);
$toc = get_posts('numberposts=-1&category='.$category_id.'&order=ASC&orderby=date');
foreach($toc as $post) :
?>
<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
<?php endforeach; $post = $post_save; ?>
</ol>

Those knowing CSS (and respecting semantics) but naming their chapters with number and name might also want to use the above code, but use CSS to hide the numbers in visual browsers.

Instead of going through and telling you to download Apache, PHP, phpMyAdmin and MySQL individually, I’m going to instruct you to go and download a software package called WampServer. You will need to download the installer from the WampServer webpage. WAMP stands for Windows, Apache, MySQL and PHP meaning the software will install all these at once. This software will install like a normal Windows program, it is safe to just click Next until you reach the end of the installer. The installer will place a shortcut in your Start Menu and on your Desktop called Start WampServer. To start your PHP-enabled web server, all you need to do is double click this icon (in Vista, User Account Control will prompt you, it is safe to click Allow).

To check that your server is working, point your web browser to http://localhost/. If you see a page with server information, your server is working. If you don’t, post in the comments and I will help you troubleshoot.

WampServer will add a new icon to your taskbar’s notification area which you can left click and control the various aspects of your new server.

You can use the various options in this menu to configure your server. You will probably be most interested in the PHP submenu where you can easily enable and disable PHP extensions and features without having to deal with configuration files. The option to make changes to PHP using php.ini is still there if you want it though, and it won’t break the ability of WAMP to automatically make changes using the menu.

If you went with the default configuration in the installer, the folder in which you place your files will be located in the following location:

C:\wamp\www

Files and Folders that you place in this folder will be accessible at the following URL:

http://localhost/

It is important to note that this location will only be available on your computer. You can’t go giving this URL to your friends. It isn’t complicated to allow that to happen (with a different URL specific to your PC), but it is beyond the scope of the article.

Congratulations, by just downloading one installer, you now have a fully functional local development server which you can use as a sandbox to learn PHP.

If there is significant interest in a manual installation and configuration process of the individual programs, I will also post a tutorial of that method. In most cases though, for development purposes on Windows, you won’t need to do this.  I should note that I personally use WAMP to quickly get myself setup with a server for development.

In this tutorial, we are going to take our previous Hello World script, and store the date in a database. We will then add the last access time to our original script. We are going to use MySQL in this tutorial. I will assume that you already have MySQL and phpMyAdmin (or equivalent) installed.

The state of our script at the end of the last tutorial was as follows:

1
2
3
4
5

<?php
 
echo 'Hello World. Today\'s date is ',date('d/m/Y'),'.';
 
?>

Our database table will consist of two fields, `ID`, and `current_timestamp`. Both will be of type, integer (INT). You should make `ID` a primary key, and auto_increment. `current_timestamp` can be left with the default options.

For your convenience, I will provide a SQL query to create the table.

1
2
3
4

CREATE TABLE `last_access` (
`ID` INT NOT NULL AUTO_INCREMENT PRIMARY KEY ,
`current_timestamp` INT NOT NULL
) ENGINE = InnoDB

You can run the above query in the SQL section of phpMyAdmin when viewing your database.

To connect to our database, we use two functions, mysql_connect, and mysql_select_db.

The first function, mysql_connect takes three parameters or arguments. These parameters are the host name (most of the time, localhost), and a username and password. These should have been provided by your web host. If you installed a server on your own computer, it is likely that username is root, with no password. We are going to place the mysql_connect function in a variable called $connection (be sure to change the parameters to suite your own specific situation):

1

$connection = mysql_connect('localhost', 'USERNAME', 'PASSWORD');

Next, we need to use mysql_select_db to access our specific database. I’ve called mine date, but you may have called it something different. If you have, change as appropriate. mysql_select_db takes two parameters. These are the $connection variable we just set and the name of your database.

1

mysql_select_db('date', $connection);

You can go ahead and place these functions at the top of our Hello World script.

Next, we are going to use the mysql_query function to insert the current time into our new database table. mysql_query only takes one parameter and this is an SQL statement. SQL stands for structured query language and is how we interact with our database within our applications. I won’t go into detail about SQL at this time, but for now, W3Schools offers a decent introduction.

Within our query, we will also use PHP’s time function. This function takes no parameters. It returns the current UNIX time stamp which is the number of seconds since the start of 1970.

Place the following in your script after the connection functions, and run it.

1

mysql_query('INSERT INTO `last_access` SET `current_timestamp` = \''.time().'\'');

Now, we are going to use the mysql_query function again to retrieve the last access time. This time we will place the mysql_query function into a variable, so we can access the results.

1

$result = mysql_query('SELECT `current_timestamp` FROM `last_access` ORDER BY `current_timestamp` DESC LIMIT 1');

Now, we want to be able to retrieve the data our SELECT query is retrieving. We can do this with, mysql_fetch_assoc. It takes one parameter, and this is our query variable which we named $result. Like mysql_query, we will also place this into a variable.

1

$row = mysql_fetch_array($result);

Place the SELECT query before the INSERT query but after the connection information.

Now, all the pieces are in place to put our final script together.

Your script should look like this at this point:

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php
 
$connection = mysql_connect('localhost', 'USERNAME', 'PASSWORD');
mysql_select_db('date', $connection);
 
$result = mysql_query('SELECT `current_timestamp` FROM `last_access` ORDER BY `current_timestamp` DESC LIMIT 1');
$row = mysql_fetch_array($result);
 
mysql_query('INSERT INTO `last_access` SET `current_timestamp` = \''.time().'\'');
 
echo 'Hello World. Today\'s date is ',date('d/m/Y'),'.';
 
?>

Now, we are going to add the current hour, minute and second to our date function in our echo language construct. The letters for these are h (hour), i (i since m is reserved for month, the current minute) and s (seconds).

1

echo 'Hello World. Today\'s date is ',date('d/m/Y h:i:s'),'.';

Next, we want to display the last access date. To do this, we are going to add another echo language construct. Since row only returned one piece of data due to LIMIT 1, we can use it just like we would an array (we will discuss arrays in a later tutorial). For now, all you need to know is that they are used like variables but can store more then one piece of information.

1

echo ' This script was last accessed at  ',date('d/m/Y h:i:s', $row['current_timestamp']),'';

You will notice this date function is taking a second parameter. This changes the output of date from the current time/date to the time and date which it was when the timestamp was recorded.

Our final script looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?php
 
$connection = mysql_connect('localhost', 'USERNAME', 'PASSWORD');
mysql_select_db('date', $connection);
 
$result = mysql_query('SELECT `current_timestamp` FROM `last_access` ORDER BY `current_timestamp` DESC LIMIT 1');
$row = mysql_fetch_array($result);
 
mysql_query('INSERT INTO `last_access` SET `current_timestamp` = \''.time().'\'');
 
echo 'Hello World. Today\'s date is ',date('d/m/Y h:i:s'),'.';
echo ' This script was last accessed at  ',date('d/m/Y h:i:s', $row['current_timestamp']),'';
 
?>

So that concludes this tutorial. As usual, comments, suggestions and most importantly, questions, are welcome.

To start, let’s output the text “Hello World” to the screen.

1
2
3
4
5

<?php
 
echo 'Hello World.';
 
?>

Any text placed within the quotes will be outputted to your screen when you access the script in your web browser.

Now, we are going to display the current date in addition to our greeting. We can get the current date using the date function which in this example takes one parameter, but usually takes two. We will discuss that in a future tutorial, but the other parameter is a standard Unix timestamp – the number of seconds since 00:00:00 UTC on January 1, 1970. We do not need to specify it here since the date function will assume I am after today’s date by default.

1
2
3
4
5

<?php
 
echo date('d/m/Y');
 
?>

The above will output the current date to the screen. The one parameter taken is what defines the format in which our date is returned. The page for date() in the PHP manual has all you need to know about the various ways in which you can format the date.

Now that we have learned how to output some text of our choice, and retrieve today’s date, let’s combine the two.

1
2
3
4
5

<?php
 
echo 'Hello World. Today\'s date is ',date('d/m/Y'),'.';
 
?>

You should notice the backslash preceding the single quote in “Today’s”. This is called escaping and tells PHP to ignore the character and continue on. It will be discussed in much more detail in a tutorial later in this series.

NOTE: These tutorials may seem like they are assuming too much knowledge at this point, but you will eventually see that this is by design, and that anything not covered and assumed will be covered in tutorials yet to be written or published. The goal is to have a series of related and dependant tutorials, but at this point I am not writing them in order. The tutorial page will always have the tutorials listed in the intended reading order.

The include statement is used to insert the contents of one file into the contents of another.

Usage:

1
2
3

<?php
include "/path/to/file.php";
?>

The included file is essentially merged with the file in which the include takes place, and the result in effect is one file containing the contents of both.

For example, we have two files. One is called “functions.php”, and the other, “display.php”. We are going to include “functions.php” in to “display.php”.

The contents of each script will be as follows.

functions.php:

1
2
3
4
5
6
7
8

<?php
 
function nice_date($timestamp)
{
return date('d/m/y', $timestamp);
}
 
?>

display.php:

1
2
3
4
5
6
7

<?php
 
include 'functions.php';
 
echo 'Today\'s Date is: ',nice_date(time());
 
?>

Essentially, what we are saying is that the contents of display.php should actually be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<?php
 
/* including functions.php */
?>
<?php
 
function nice_date($timestamp)
{
return date('d/m/y', $timestamp);
}
 
?>
<?php
/* finished including functions.php */
 
echo 'Today\'s Date is: ',nice_date(time());
 
?>

and the output is as so:

Today’s Date is 11/06/09.

You will notice that the PHP opening and closing tags (<?php and ?>) were maintained.PHP automatically closes its tags before and opens them after the inclusion has taken place. This is because PHP does not assume that the file included only contained PHP, for example it may only contain HTML or CSS.

The code within “functions.php” was executed just as if it had been in the PHP file containing the include statement in the first place. “display.php” has access to any methods/functions, variables and other things defined in “functions.php”, and “functions.php” has access to any of those which are specified in “display.php” or other files it might include prior to “functions.php” inclusion.

How does the require statement differ from the include statement?

With include, if the file does not exist, your PHP script will not halt, and will continue to execute until it reaches the end. In the case of require, the script will cease execution and a fatal error will occur if the file cannot be found. You should use require to include any file you absolutely depend on like a “config.php” file containing your database access information.

In usage, require only differs in the text used. It is otherwise identical to include.

1
2
3

<?php
require "/path/to/file.php";
?>

What about require_once and include_once? How are they different?

Appending _once to either require or include will only allow the file to be included once. Future include statements referencing said file will not get included again.

That is the conclusion of my first tutorial – an introduction to PHP includes. If you have any questions, corrections, suggestions for tutorials, or general comments, please feel free to comment.