feeds::extension documentation

Index

1. Introduction to feeds::extension

1.1 What is feeds::extension?

feeds::extension is an extension class for Web::class that adds RSS and ATOM feed parsing capabilities to your Lua scripts.

Features:

  • Parses all major versions of RSS and ATOM feeds
  • Uses the excellent SimplePie class to parse feeds (http://www.simplepie.org/)
  • Can parse multiple feeds and aggregate them
  • Caches feed data for more speed

1.2. Architecture

feeds::extension consists of two files:

  • feeds.extension.php: This is the main extension class Web::class will use.
  • simplepie_1.3.1.compiled.php: This is the included compiled version of SimplePie, which feeds::extension uses to do the heavy work of parsing and normalizing feeds.
  • docs/: Directory containing this document and also the API documentation of feeds::extension.

1.3. Installation

So as to install feeds::extension, your server needs to meet the following system requirements:

  • All requirements that apply to Web::class
  • PHP cURL extension
  • PHP PCRE extension
  • PHP XML extension

Once these dependencies are met, you can install feeds::extension.

1. Copy the content of the archive into a "feeds" folder in the extension folder of the user 0 of your Web::class installation, usually users/0/extensions.

  1. Then add the feeds::extension to your Web::class configuration, in config.php, usually:

    // Add here your extension classes
    $this->settings['Extensions'] = array(
                            <-- other extensions here -->
                            'feeds/feeds.extension.php'
    );
    

Now you can start parsing feeds in your Lua scripts!

2. Parsing feeds

2.1. The getfeedelements function

The “getfeedelements” function is the only function provided by this extension. It is used to load one or more feeds and return a multi-dimensional array of feed items. Its two parameters are:

  • $feeds: An array of feeds to parse. You can specify one or more feeds in the array. Feeds will be aggregated by date, so make sure your feeds have dates; otherwise you'll have to use each feed individually.
  • $numposts: The maximum number of items you want to retrieve. It can be set to “0” for unlimited items.

Example

As required, we'll create a new Lua function in our template's Lua file:

-- Get feed data
function getfeeds(args)
        numposts = args[1]
        feeds = {}


        for i = 2, args[1],1 do
                feeds[i] = args[i]
        end

        return getfeedelements(feeds, numposts)
end

It will expect the number of items as the first parameter, and the remaining parameters after that are the feed URLs.

2.2. Using the feed data in your templates

Once we have successfully parsed and cached our feed, we want to display it in your template. We could use a for loop, for example:

{% for item in feeddata %}
        <h1>{{ item.title }}</h1>

        <p>{{ item.description|striptags|slice(0,90)|trim }}...</p>


        <p><a href="{{ item.links[1] }}" onclick="return ! window.open(this.href);">Read more >></a></p>
{% else %}
        <p>- No announcements available -</p>
{% endfor %}

This will display our feed data, and if no feed data is available, it will display “No announcements available”.

Note that in this example, we have stripped all HTML tags from the output (striptags), and limited our output to 90 characters (slice), and trimmed it (trim), but you could do anything you like here.

2.3. The feed item

Each feed item can have the following properties:

  • .title: The title of the post.
  • .description: The summary of the post content. If no summary is present, the full content will be used instead.
  • .content: The post content. If no content is present, the summary will be used instead.
  • .categories: An array of categories this item belongs to.
  • .authors: An array of authors for the item. Each author will have a name, link and email property.
  • .date: The date of the post, in Unix timestamp format.
  • .links: An array of links this item links to. Normally used for permalinks.

2.4. Need help?

Thank you for taking time to read this manual! For assistance, check http://www.relamp.tk!