DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: RSS feed

Author:Fabien Udriot
Created:2002-11-01T00:32:00
Changed by:Fabien Udriot
Changed:2009-12-10T09:07:18
Keywords:RSS feed
Email:fabien.udriot@ecodev.ch
Info 2:
Info 3:
Info 4:
Author:Fabien Udriot

EXT: RSS feed

Extension Key: ecorss

Copyright 2006-2008, Fabien Udriot, <fabien.udriot@ecodev.ch>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.com

Table of Contents

EXT: RSS feed 1

Introduction 1

What does it do? 1

No screenshots necessary! 2

Installation 2

User guide 2

How to Build a Feed, TypoScript Example 2

Feed Configuration Examples 5

Generating a RSS or ATOM feed 5

Filtering Content based on Page Language 6

Filtering Records from Table tt_content 6

Including and Excluding Field's Value 6

Selecting Content from a Flexform 7

Combining Content from a Flexform and From Another Table 7

tt_news example 8

Available Hooks 8

Configuration 9

Class Example 9

TypoScript Configuration 9

Administration 9

Clear the cache 9

Known problems 9

To-Do list 9

Acknowledgments 9

Changelog 9

Introduction

What does it do?

This extension is designed to set up quickly and easily one or many rss feeds from any tables of the database. Copy / paste a few TypoScript lines in your template setup and that's it! You can follow the latest content of your website – keep an eye on the latest frontend user, etc.

Features

  • Choose whether ATOM or RSS feed is displayed:
  • http://en.wikipedia.org/wiki/Atom_(standard )
  • http://en.wikipedia.org/wiki/RSS_(file_format )
  • Extract value from flexform (requires MySQL 5.2). Some values can be stored in flexform data. This information is not very practical to extract. However with MySQL 5.2, it is now possible to build XPath requests and fetch data within the XML structures.
  • Hide / show several different feeds on the same pages. RSS feeds are very practical to follow the life of a website. You can imagine a feed that inform you whether a new page is created, a backend user's profile has been updated or a content element has been updated. Such administrative feeds are not necessarily shown in the frontend but are given only for administrators.
  • A lot of possible data combination and configurations...

Further documentation of RSS: http://www.rssboard.org/rss- specification

No screenshots necessary!

@see rather the TypoScript example in the next section.

Installation

Download and install the extension as normal. No database update necessary.

Update your "Static Include" from extension by editing the main template (module Web > List) as follows:

img-1

img-2

User guide

A backend user can exclude a content element from the feed. A checkbox is available after the field "hidden".

How to Build a Feed, TypoScript Example

Very Important: this extension won't work until you properly complete the installation section.

Express Installation

Copy / paste these lines into a template > setup. Beware of the cache period. The feed is regenerating every 3600 seconds. To change this value, check parameter "cache_period".

###############################
# GENERATE THE FEED
###############################
feed = PAGE
feed {
  typeNum = 103
  10 >
  10 = USER
  10.userFunc = tx_ecorss_controllers_feed->display
  10.lang = fr-FR
  # CHANGE THIS:
  10.title = title of the feed
  # CHANGE THIS:
  10.subtitle = subtitle of the feed
  config{
    disableAllHeaderCode = 1
    disableCharsetHeader = 1
    additionalHeaders = Content-type:text/xml
    no_cache = 1
    xhtml_cleaning = 0
    admPanel = 0
  }
}

###############################
# DECLARE FEED IN THE FRONTEND(ATOM)
###############################
page.headerData.12 = USER
page.headerData.12.userFunc = tx_ecorss_controllers_feed->add
page.headerData.12.feed{
  typeNum = 103
  title < feed.10.title
}
More Details: Declaring a RSS or ATOM Feed in the Frontend

Declaring two different feeds onto the frontend

Copy paste these lines in a template > setup.

page = PAGE
page.headerData.12 = USER
page.headerData.12.userFunc = tx_ecorss_controllers_feed->add
page.headerData.12.feed1{
  title = Here comes the title of the feed 1
  typeNum = 103
  feed = atom
}
page.headerData.12.feed2{
  title = Here comes the title of the feed 2
  typeNum = 100
  feed = rss
}
Plugin Global Configuration
num

Property

num

Data type

int (mandatory)

Description

the type of the page like index.php?id=1&type=126

Default

null

title

Property

title

Data type

string

Description

the title of the feed

Default

feed

Property

feed

Data type

string

Description

2 possibles values: atom – rss

have a look at the following links to know the difference of the formats:

Default

atom

Important Remark

In case you have several feeds, you might want define constants to avoid repeating things.

In the constant editor:

plugin.tx_ecorss.title = Here comes the *title* for every feeds
plugin.tx_ecorss.subtitle = Here comes the *subtitle* for every feeds
...
Feed Configuration
title

Property

title

Data type

string

Description

the title of the feed

Default

atom

subtitle

Property

subtitle

Data type

string

Description

the subtile of the feed

Default

lang

Property

lang

Data type

string

Description

the character encoding: fr-FR ; de-DE ; en-US

Default

en-GB

host

Property

host

Data type

string

Description

define an other host name t if not the same as t3lib_div::getIndpEnv('TYPO3_SITE_URL'). If protocol (http:// or https://) is not specified, then http:// will be prefixed.

Default

t3lib_div::getIndpEnv('TYPO3_SITE_URL')

encoding

Property

encoding

Data type

string

Description

Default

utf-8

numberItems

Property

numberItems

Data type

string

Description

number of elements in the feed

Default

10

feed

Property

feed

Data type

string

Description

2 possibles values: atom ; rss

have a look at the following links to know the difference of the formats:

Default

atom

author.name

Property

author.name

Data type

string

Description

the author of the feed's (Atom feed).

Remark: If you want to save this value automatically in the database, have a look at the extension “fhm_author”.

Default

Page's author name

author.email

Property

author.email

Data type

string

Description

the email of the author (Atom feed). Beware: default Atom template does not write the email, you have to modify file templates/atom.php)

Remark: If you want to save this value automatically in the database, have a look at the extension “fhm_author”.

Default

Page's author email

cache_period

Property

cache_period

Data type

int

Description

How long should the feed be hold in cache. Unit in second

Default

3600

no_anchor

Property

no_anchor

Data type

int

Description

Define if the URL will contain an anchor like this :

http://mydomaine.tld/index.php?id=123#c343

Default

0

pidRootline

Property

pidRootline

Data type

int

Description

which page id define the first page of the Site (update on this page will be included too in the feed). It is useful with multi domain websites or to create feeds related to sections in the website

Default

null

sysLanguageUid

Property

sysLanguageUid

Data type

int

Description

which language (L parameter in multilingual sites) should be used to filter updated content. If left unconfigured, return all content in all languages

Default

null

profileAjaxType

Property

profileAjaxType

Data type

int

Description

which page type should be used to include website content in the feed (useful to change the page type to use a stripped down layout – e.g., w/o menu – when reading the news in a newsreader such as Thunderbird)

Default

0

hook

Property

hook

Data type

user defined

Description

If you create a hook for post-processing feed entries, you may configure it as you wish using this section. See section “Available Hooks” for more information.

Default

null

tidy

Property

tidy

Data type

int

Description

Launch the tidy command

Default

0

tidy_path

Property

tidy_path

Data type

string

Description

Configuration parameters given to tidy

Default

tidy -i -utf8 -xml

Elements of the Feed Configuration (select.)
title

Property

title

Data type

string

Description

the field of the database that corresponds to the "title" of an element in the feed. Most of the time, it will be tt_content.header

Default

header

titleXPath

Property

titleXPath

Data type

string

Description

the field where the flexform is stored. Most of the time, it will be content.pi_flexform

Default

pi_flexform

summary

Property

summary

Data type

string

Description

the field of the database that corresponds to the "body of an element in the feed. Most of the time, it will be tt_content.bodytext

Default

bodytext

summaryXPath

Property

summaryXPath

Data type

string

Description

the field of the database that corresponds to the "body of an element in the feed. Most of the time, it will be tt_content.bodytext

Default

utf-8

published

Property

published

Data type

string

Description

the field of the database that corresponds to the time stamp when the element is published

Default

tstamp

updated

Property

updated

Data type

string

Description

the field of the database that corresponds to the time stamp when the element is updated

Default

tstamp

uid

Property

uid

Data type

string

Description

the uid field name of the database

Default

uid

pid

Property

pid

Data type

string

Description

the page id's field name of the database

Default

pid

filterField

Property

filterField

Data type

string

Description

define which field will be used to filter elements. Will be transform in a SQL statement like field = value => list_type = some_plugin

Default

null

filterInclude

Property

filterInclude

Data type

comma separated string

Description

define which value willbe used to filter elements. Will be transform in a SQL statement like field = value => list_type = some_plugin

Default

null

filterExclude

Property

filterExclude

Data type

comma separated string

Description

define which value will NOT be used. Will be transform in a SQL statement like list_type != some_plugin

Default

table

Property

table

Data type

string

Description

which table contains the element of the feed

Default

tt_content

debug

Property

debug

Data type

true/false

Description

output the request in the RSS feed. Maybe useful to debug the request.

Default

false

linkItem

Property

linkItem

Data type

true/false

Description

wrap the title with a link. It is not always the case since in can be a administrative feed telling that a new user has been created for example.

Default

true

defaultText

Property

defaultText

Data type

string

Description

should the element contain a default value. Useful for administrative feed.

Default

null

single_page.pid

Property

single_page.pid

Data type

int

Description

page id containg the plugin to display a single record as defined in “select” configuration element.

Default

null

single_page.linkParamUid

Property

single_page.linkParamUid

Data type

string

Description

parameter to the url to choose the record to be shown. E.g. if you use the extension mininews, you will have to set this to “tx_mininews_pi1[showUid]” as the URL to show a single news is the URL of the page containing the news plugin and the parameter &tx_mininews_pi1[showUid]=<uid>

Default

null

orderBy

Property

orderBy

Data type

string

Description

defines the order of the feed.

Default

tstamp DESC

where

Property

where

Data type

string

Description

defines additional conditions ( where = AND myField = 'myValue')

Default

null

truncate

Property

truncate

Data type

int

Description

defines how many character the summary should be shorten up.

Default

null

author

Property

author

Data type

string

Description

the field of the database that corresponds to the "author". If not defined, retrieves the author from the page.

Default

empty

extraFields

Property

extraFields

Data type

string

Description

additionnal fields

extraFields = datefrom, dateto

Default

empty

additionalSQL

Property

additionalSQL

Data type

string

Description

example: adding categories management for tt_news

AND tt_news.uid IN (SELECT tt_news_cat_mm.uid_local FROM tt_news_cat_mm WHERE tt_news_cat_mm.uid_foreign = 5)

Default

empty

additionalPids

Property

additionalPids

Data type

string

Description

comma separated string. Defines additional pid to include in the request. Useful for adding external sysfolder of the root page.

Default

empty

baseUrl

Property

baseUrl

Data type

string

Description

Ecorss tries to guess the domain according to the pid of the record but in some cases it can't succeed as the record may be outside the tree (e.g. tt_news). So gives ecorss a little hand by giving the base URL.

Example of value:

baseUrl = http://replace.tld

Default

empty

Feed Configuration Examples

Generating a RSS or ATOM feed

The minimum configuration to build a feed. Copy paste these lines in a template > setup.It will display the latest updated content from table tt_content with 10 items.

feed2 = PAGE
feed2 {
  typeNum = 103
  10 >
  10 = USER
  10.userFunc = tx_ecorss_controllers_feed->display
  10.title = title of the feed
  10.subtitle = subtitle of the feed
  10.lang = fr-FR
  config {
    disableAllHeaderCode = 1
    disableCharsetHeader = 1
    additionalHeaders = Content-type:text/xml
    no_cache = 1
    xhtml_cleaning = 0
    admPanel = 0
  }
}
Generating a RSS or ATOM feed (more configuration)

It will provide exactly the same output as "feed2" but with more configuration

feed3 = PAGE
feed3 {
  typeNum = 103
  10 >
  10 = USER
  10.userFunc = tx_ecorss_controllers_feed->display
  10.title = title of the feed
  10.subtitle = subtitle of the feed
  10.lang = fr-FR
  10.cache_period = 3600
  10.numberItems = 10
  10.feed = atom
  10.select {
    01 {
      table = tt_content
      title = header
      summary = bodytext
      published = tstamp
      updated = tstamp
      debug = 0
    }
  }
  config {
    disableAllHeaderCode = 1
    disableCharsetHeader = 1
    additionalHeaders = Content-type:text/xml
    no_cache = 1
    xhtml_cleaning = 0
    admPanel = 0
  }
}

Filtering Content based on Page Language

Only return entries for the language associated to L=1 (e.g., English).

feed4 = PAGE
feed4 {
  typeNum = 103
  10 >
  10 = USER
  10.userFunc = tx_ecorss_controllers_feed->display
  10.title = title of the feed
  10.subtitle = subtitle of the feed
  10.lang = en-GB
  10.sys_language_uid = 1
  config {
    disableAllHeaderCode = 1
    disableCharsetHeader = 1
    additionalHeaders = Content-type:text/xml
    no_cache = 1
    xhtml_cleaning = 0
    admPanel = 0
  }
}

Filtering Records from Table tt_content

feed5 = PAGE
feed5 {
  typeNum = 103
  10 >
  10 = USER
  10.userFunc = tx_ecorss_controllers_feed->display
  10.title = title of the feed
  10.subtitle = subtitle of the feed
  10.lang = fr-FR

  10.select {
    01 {
      table = tt_content
      # it will be transformed in SQL e.g. list_type=tx_ecobox_controllers_content
      filterField = list_type
      # comma separated value
      filterInclude = tx_ecobox_controllers_content , tx_ecobox_controllers_box
    }
  }
  config {
    disableAllHeaderCode = 1
    disableCharsetHeader = 1
    additionalHeaders = Content-type:text/xml
    no_cache = 1
    xhtml_cleaning = 0
    admPanel = 0
  }
}

Including and Excluding Field's Value

Include and exclude field's value in a more verbose configuration.

feed6 = PAGE
feed6 {
  typeNum = 103
  10 >
  10 = USER
  10.userFunc = tx_ecorss_controllers_feed->display
  10.title = title of the feed
  10.subtitle = subtitle of the feed
  10.lang = fr-FR
  10.cache_period = 3600
  10.numberItems = 10
  10.feed = atom
  10.select {
    01 {
      table = tt_content
      filterField = list_type
      filterInclude = text, textpic
      filterExclude = list, mailform
      # the value corresponds to a field (title of the enty)
      title = header
      # the value corresponds to a field (body of the enty)
      summary = bodytext
      debug = 0
    }
  }
  config {
    disableAllHeaderCode = 1
    disableCharsetHeader = 1
    additionalHeaders = Content-type:text/xml
    no_cache = 1
    xhtml_cleaning = 0
    admPanel = 0
  }
}

Selecting Content from a Flexform

Requires MySQL >= 5.2.

feed7 = PAGE
feed7 {
  typeNum = 103
  10 >
  10 = USER
  10.userFunc = tx_ecorss_controllers_feed->display
  10.title = title of the feed
  10.subtitle = subtitle of the feed
  10.lang = fr-FR
  10.cache_period = 3600
  10.numberItems = 10
  10.feed = rss
  10.select{
    01{
      table = tt_content
      filterField = list_type
      filterInclude = tx_ecobox_controllers_content
      # this option is not mandatory
      summary = pi_flexform
      summaryXPath = /T3FlexForms/data/sheet[@index="sSummary"]/language/field/value[text()]
    }
  }
  config{
    disableAllHeaderCode = 1
    disableCharsetHeader = 1
    additionalHeaders = Content-type:text/xml
    no_cache = 1
    xhtml_cleaning = 0
    admPanel = 0
  }
}

Combining Content from a Flexform and From Another Table

Select content from a Flexform (require MySQL 5.2) AND combine with an other feed from an other table (tx_mininews_news) associated to extension mininews.

feed8 = PAGE
feed8 {
  typeNum = 103
  10 >
  10 = USER
  10.userFunc = tx_ecorss_controllers_feed->display
  10.title = title of the feed
  10.subtitle = subtitle of the feed
  10.lang = fr-FR
  10.cache_period = 3600
  10.numberItems = 10
  10.select {
    01 {
      table = tt_content
      filterField = list_type
      filterInclude = tx_ecobox_controllers_content
      summaryXPath = /T3FlexForms/data/sheet[@index="sSummary"]/language/field/value[text()]
    }
    02 {
      table = tx_mininews_news
      title = title
      summary = teaser
      published = tstamp
      updated = tstamp
      debug = 0

      single_page {
        pid = 87
        linkParamUid = tx_mininews_pi1[showUid]
      }
    }
  }
  config {
    disableAllHeaderCode = 1
    disableCharsetHeader = 1
    additionalHeaders = Content-type:text/xml
    no_cache = 1
    xhtml_cleaning = 0
    admPanel = 0
  }
}

tt_news example

feed = PAGE
feed {
  typeNum = 103
  10 = USER
  10 {
  userFunc = tx_ecorss_controllers_feed->display
  lang = fr-FR
  10.title = REPLACE
  10.subtitle = REPLACE
    pidRootline = REPLACE
    tidy = 1
    numberItems = 10
    select {
      01 {
        table = tt_news
        title = title
        summary = short
        published = crdate
        updated = tstamp
        debug = 0
        additionalSQL = AND tt_news.uid IN (SELECT tt_news_cat_mm.uid_local FROM tt_news_cat_mm WHERE tt_news_cat_mm.uid_foreign = 5)
        additionalPids = 27

        single_page {
          pid = 483
          linkParamUid = tx_ttnews[tt_news]
        }
      }
    }
  }

  config{
    disableAllHeaderCode = 1
    disableCharsetHeader = 1
    additionalHeaders = Content-type:text/xml
    no_cache = 1
    xhtml_cleaning = 0
    admPanel = 0
  }
}

Available Hooks

One single hook, namely PostProcessingProc, is available and let you post-process each feed entry before displaying / caching it.

Configuration

Create a PHP class containing your own processing method (see section “Class Example” below) and reference it in localconf.php:

include(dirname(__FILE__).'/../fileadmin/class.user_ecorss.inc');
$TYPO3_CONF_VARS['EXTCONF']['ecorss']['PostProcessingProc'][] = 'user_ecorss->proc';

Remark

This configuration example uses a file class.user_ecorss.inc which is stored in fileadmin. You may change it as you wish to fit your needs!

Class Example

This example shows how to create a post-processing method which prepends “Hello - “ to the feed title.

<?php
class user_ecorss {
  public function proc($feed, $cObj) {
    $feed['entry']['title'] = 'HELLO - ' . $feed['entry']['title'];
  }
}
?>

TypoScript Configuration

If you need to parameterize the post processing function, you may extend the feed configuration with any parameter in the hook block:

feed1.10.hook {
  myPrefix = Hello World ::
}

And then in your class:

$feed['entry']['title'] = $feed['config']['myPrefix'] . $feed['entry']['title'];

Administration

Clear the cache

Add parameter ecorss[clear_cache]=1in order to clear the cache and regenerate the content of the feed.

Exemple URL: http://quart- monde.ch/index.php?type=103&ecorss[clear_cache]=1

Known problems

Please report the problem you might meet to fabien.udriot@ecodev.ch

To-Do list

Manage the <keyword> tag in RSS feed (depending on the demand)

Acknowledgments

Changelog

Please refer to the Changelog.txt in the extension itself.

EXT: RSS feed - 9