Daniel Marino

Calendar Events in TextPattern

I’ve done two or three websites driven by TextPattern where the client wanted to show calendar events. I’ve never been happy that TXP doesn’t have a built-in solution for this, and it seems like every time I try to implement this feature it feels ultra-hacked and not very user-friendly for entering calender events. I recently came across the zem-event plugin and gave it a whirl, but I never really got it working properly and there was very little documentation for it. Not to mention, it seemed more complicated to use and even more hacked than any of the other solutions I came up with.

I recently came up with a somewhat decent solution for implementing calendar events. All it requires is a little PHP and the use of TXP Global variables.

A List of Demands

First, here is my list of requirements for implementing calendar events:

• The events must be able to be displayed in any date-format of our choosing
• They need to be displayed in order of their occurrence, whether it be descending or ascending
• They can be entered into TXP in any order, without effecting the order they will be displayed
• I don’t want to create multiple custom fields, or using existing fields not intended for their purpose
• Most importantly, it must be easy for the client to create a calendar event

Putting It All Together

I’d like to mention that the focus of this article is not about HTML or common TXP tags, and I will not go into detail about them. There are plenty of free resources and examples available on the web (I also highly recommend the book TextPattern Solutions).

Let’s get started by creating the custom field in TXP. Go to Admin > Preferences > Advanced, and scroll down the page until you come to the Custom Field section. Enter the name you wish to call the custom field in the first available spot. I named mine event_date.

Next, go to Content > Write and create a few events so that we have something to work with. Since the title field is mandatory, we’ll use that for the event name. In the body section, you may want to enter in some details for the event, such as time or location. Over in the left column you’ll see the new custom field we created. Enter the event date, but it’s imperative you use the following format: YYYYMMDD. I use this because its a single number that’s easy to break apart and allows for easy sorting in order of its occurrence. This way calendar events (or technically, articles) can be created out of order, and will still sort properly.

I want to display my calendar events using a table where each event has its own row. On the page where the calendar events are going to be displayed, I’ll use the following code:

<table cellspacing="0" cellpadding="0" border="0">
  <thead>
    <tr>
      <td>Date</td>
      <td>Event</td>
      <td>Details</td>
    </tr>
  </thead>
  <tbody>
    <txp:article_custom sort="custom_1 asc" section="calendar" form="display_events" limit="5" />
  </tbody>
</table>

I’m telling TXP to sort the calendar events in ascending order using the custom field we created. Note that you actually use custom_ and field number—not the name of the custom field. Also, you could just as easily have the calender events sort descending by changing asc to desc. I’ve talked more about sorting articles by custom fields in a previous article. Next we’ll create the form that the above code references, display_events which will format the calendar events:

<tr>
  <td><txp:php>echo convert_date($GLOBALS['thisarticle']['event_date']);</txp:php></td>
  <td><txp:title /></td>
  <td><txp:body /></td>
</tr>

This code is calling the convert_date function (which hasn’t been created yet), and is passing the data from the custom field event_date into the function so that it can be manipulated. Normally when you want to display data from a TXP custom field, you use <txp:custom_field name="event_date" />. However, because we’re writing this code between PHP tags, TXP will not recognize any of it’s own tags. This is why we’re using $GLOBALS['thisarticle']['event_date'] — this is how TXP accesses global variables via PHP. When it’s all said and done, this code is going to pass the YYYYMMDD formatted event_date to the function convert_date. To learn more about accessing global variables in TXP, I highly recommend reading this article written by Matt Harris.

Now we need to create the PHP function, which we’ll store in a separate file:

<?php

 function convert_date($num) {

  $month = substr($num, 4, 2);
  $day = substr($num, 6, 2);
  $year = substr($num, 0, 4);

  switch ($month) {
    case "01": $month_name = "January"; break;
    case "02": $month_name = "February"; break;
    case "03": $month_name = "March"; break;
    case "04": $month_name = "April"; break;
    case "05": $month_name = "May"; break;
    case "06": $month_name = "June"; break;
    case "07": $month_name = "July"; break;	
    case "08": $month_name = "August"; break;
    case "09": $month_name = "September"; break;
    case "10": $month_name = "October"; break;
    case "11": $month_name = "November"; break;
    case "12": $month_name = "December"; break;
    }

  $converted_date = $month_name . " " . $day . ", " . $year;

  return $converted_date;

}

?>

This function takes the event date from the custom field and returns the event date in any format of our choosing. In this case I’m returning the date in the following format: Month DD, YYYY. I’ll break the function down piece by piece:

$month = substr($num, 4, 2);
$day = substr($num, 6, 2);
$year = substr($num, 0, 4);

These lines of code takes in the number passed into the function and breaks it apart into three variables: $month, $day, and $year. The substr() function is a very useful tool. I’ll use the $month variable as an example: It’s looking at the number stored in the variable $num, and starting directly after the fourth number, it is extracting the fifth and sixth number. I’m using the same method to extract the variables for $day and $year.

switch ($month) {
    case "01": $month_name = "January"; break;
    case "02": $month_name = "February"; break;
    ...
    }

Using the switch method is an efficient alternative to having to use multiple if... elseif statements. This block of code is using the switch statement to look at the two-digit value stored in $month variable and assigning the written-out month.

  $converted_date = $month_name . " " . $day . ", " . $year;

  return $converted_date;

And this last little bit is stringing together all the variables and returning the date to be displayed. Now we’ll save this PHP file and name it “functions.php”.

One last step and this will be good to go. We need to include the PHP file that has the above function, convert_date, in it. I saved “functions.php” in a folder, “_php”. Note that your file location may be different.

<txp:php>
require_once($_SERVER['DOCUMENT_ROOT'] . "/_php/functions.php");
</txp:php>

We Made It

That’s it! I’ve found this method of incorporating calendar events with TextPattern to be quite useful. It’s effective and simple-to-implement. In the meantime, I’ll keep dreaming about that future release of TXP with calendar functionality built-in.