Feeding Entries with LG Data Matrix

by Brandon Kelly

Editors Note: I’d like to welcome web developer Brandon Kelly as a guest author on EE Insider. Brandon is active in the EE developer community, having released five EE Add-ons, including the popular extension Playa.

As an extension developer, I want to make it as easy as possible for people to track updates to my extensions. I tend to promote major updates on the EE Extensions Forum and Twitter, and LG Addon Updater carries a lot of weight as well. Recently I decided to open up a new avenue for tracking updates: Change Log feeds. A lot of people use feed readers to subscribe to the websites they enjoy, so why not use them to track extension updates as well?

The normal way to create a website feed is pretty simple: you loop through an {exp:weblog:entries} tag, spitting out the entry data in either RSS or Atom format. But for the Change Log feeds, I wanted to give each entry its own feed. Out of the box, the only way to do that would have been to create a new Change Log weblog for each of my extensions, and link my extension entries to their Change Log weblogs through some kind of naming convention.

That sounded messy, so instead I turned to LG Data Matrix, an extension that adds a new custom field type which stores tabular data.

At the time, LG Data Matrix only supported three cell types: text, textarea, and select. Although I technically could have gotten away with using nothing but text cells, it wouldn’t have been pretty. So I decided to get my hands dirty and give myself a couple more options: date and checkbox. They’ve been included in the latest release of the extension (version 1.1), so go ahead and download yourself a copy if you plan to follow along.

Configuring the field

With LG Data Matrix 1.1 installed, let’s create our new custom field. I gave mine the Field Name “changelog”, and the Field Label “Change Log”. Choose “LG Data Matrix” from the Field Type drop-down. Off to the right, a big textarea will appear, pre-filled with a few sample column definitions. Go ahead and replace its entire contents with this:

title = Version
short_name = changelog_version
type = textwidth = 10

title = Changes
short_name = changelog_changes
type = textarea

title = Release Date
short_name = changelog_date
type = date
width = 20

That gives us three columns to work with: Version, Changes, and Release Date. Version is a simple text field that will define the feed entries’ titles, Changes is a multi-line text area that will define the feed entries’ content, and we’ll use Release Date to define the feed entries’ dates.

Save the field now, and create a new entry in a weblog that uses your Change Log field. You should see something like this:   

Composing the feed template

If you’ve used LG Data Matrix before, everything we’ve done thus far should be familiar territory. But your time has not been spent in vain, because now we get to the fun part: the feed template.

There are two popular feed formats: RSS and Atom. Nobody actually knows the difference between the two, so we tend to just offer up both formats and let our users decide. For this tutorial, I went the Atom route because I think “Atom” sounds cooler than “RSS”. But the general approach will work just as well with RSS, should you be on that side of the fence.

I have a “feeds” template group on my website, and in it, I created a new template called “changelog.atom”. I used a fairly generic Atom feed as a starting point. But from there, I took it in a very different direction than your average ExpressionEngine feed template: I wrapped the entire feed inside an {exp:weblog:entries} tag pair, rather than just the <entry> node. That gives you access to your entry-specific attributes, like Title and Date, right at the outset. Then, I wrapped the <entry> node with my LG Data Matrix tag.

Without further ado, here’s the entire template:

{exp:weblog:entries weblog="ee" url_title="{segment_3}"
limit="1" disable="categories|category_fields|
member_data|pagination|trackbacks"}

{exp:rss:feed weblog="{weblog_short_name}"}

{assign_variable:feed_title="{title}"}

{assign_variable:feed_description="Change Log"}

{assign_variable:feed_alt_link="http://eeinsider.com/
apps/{url_title}"}

{assign_variable:feed_link="http://eeinsider.com/
feeds/changelog.atom/{url_title}"}

<?xml version="1.0" encoding="{encoding}"?>
<feed xmlns="http://www.w3.org/2005/Atom"
xml:lang="{weblog_language}">

  <title type="text">{exp:xml_encode}{feed_title} »
  {/exp:xml_encode}</title>
  <subtitle type="text">{exp:xml_encode}{feed_description} »
  {/exp:xml_encode}</subtitle>
  <link rel="alternate" type="text/html" »
  href="{feed_alt_link}" />
  <link rel="self" type="application/atom+xml" »
  href="{feed_link}" />
  <updated>{edit_date format="%Y-%m-%dT%H:%i:%sZ"}</updated>
  <rights>Copyright (c) {gmt_date format="%Y"},
  {author}</rights>
  <generator uri="http://expressionengine.com/" »
  version="2.6.1">ExpressionEngine</generator>
  <id>tag:{trimmed_url},{gmt_date format="%Y:%m:%d"}</id>
  {changelog limit="10" flip="y"}	

  {rows}
   <entry>
    <title>{exp:xml_encode}{title}{changelog_version} »
    {/exp:xml_encode}</title>
    <link rel="alternate" type="text/html"
    href="http://brandon-kelly.com/apps/{url_title}" />
    <id>brandonkelly/apps/{url_title}/changelog/
    {changelog_version}</id> 
    <published>{changelog_date »
    format="%Y-%m-%dT%H:%i:%sZ"}
    </published>
    <updated>{changelog_date format="%Y-%m-%dT%H:%i:%sZ"}
    </updated>
    <author>
     <name>{author}</name>
     { if url}<uri>{url}</uri>{ /if }
    </author>
    <category term="{exp:xml_encode}{weblog_name} »
    {/exp:xml_encode}" label="{exp:xml_encode}{weblog_name} »
    {/exp:xml_encode}" />
    <content type="html">
     <![CDATA[
      {changelog_changes}
     ]]>
    </content>
   </entry>
  {/rows}
{/changelog}
</feed>
{/exp:rss:feed}
{/exp:weblog:entries} 

As you can gather, LG Data Matrix will loop through the {rows} tag pair for each row in your Change Log field, generating very similar HTML output as a normal feed would generate.

The end result is a normal, valid Atom feed that anyone can subscribe to, and which you can maintain directly from the entry’s Edit form. You can see it in action by viewing any of my extensions’ Change Log feeds: Editor, Gypsy, Playa, Snitch, and Sarge.

How might you use it?

Although this article is geared toward how I used the technique on my own website, there are dozens of scenarios where this could come in handy. If you can think of a way you’re going to use it, let us know in the comments!