.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ============= 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: EXT: RSS feed ============= Extension Key: **ecorss** Copyright 2006-2008, Fabien Udriot, 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: 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: Introduction ------------ .. _What-does-it-do: 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: No screenshots necessary! ^^^^^^^^^^^^^^^^^^^^^^^^^ @see rather the TypoScript example in the next section. .. _Installation: 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: 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: How to Build a Feed, TypoScript Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Very Important: this extension won't work until you properly complete the installation section. .. _Express-Installation: 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: 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: Plugin Global Configuration """"""""""""""""""""""""""" .. ### BEGIN~OF~TABLE ### .. _num: num ~~~ .. container:: table-row Property num Data type int (mandatory) Description the type of the page like index.php?id=1&type=126 Default null .. _title: title ~~~~~ .. container:: table-row Property title Data type string Description the title of the feed Default .. _feed: feed ~~~~ .. container:: table-row 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: - `http://en.wikipedia.org/wiki/Atom\_(standard `_ ) - `http://en.wikipedia.org/wiki/RSS\_(file\_format `_ ) Default atom .. ###### END~OF~TABLE ###### **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: Feed Configuration """""""""""""""""" .. ### BEGIN~OF~TABLE ### .. _title: title ~~~~~ .. container:: table-row Property title Data type string Description the title of the feed Default atom .. _subtitle: subtitle ~~~~~~~~ .. container:: table-row Property subtitle Data type string Description the subtile of the feed Default .. _lang: lang ~~~~ .. container:: table-row Property lang Data type string Description the character encoding: fr-FR ; de-DE ; en-US Default en-GB .. _host: host ~~~~ .. container:: table-row 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: encoding ~~~~~~~~ .. container:: table-row Property encoding Data type string Description Default utf-8 .. _numberItems: numberItems ~~~~~~~~~~~ .. container:: table-row Property numberItems Data type string Description number of elements in the feed Default 10 .. _feed: feed ~~~~ .. container:: table-row 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: - `http://en.wikipedia.org/wiki/Atom\_(standard `_ ) - `http://en.wikipedia.org/wiki/RSS\_(file\_format `_ ) Default atom .. _author-name: author.name ~~~~~~~~~~~ .. container:: table-row 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: author.email ~~~~~~~~~~~~ .. container:: table-row 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: cache\_period ~~~~~~~~~~~~~ .. container:: table-row Property cache\_period Data type int Description How long should the feed be hold in cache. Unit in second Default 3600 .. _no-anchor: no\_anchor ~~~~~~~~~~ .. container:: table-row 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: pidRootline ~~~~~~~~~~~ .. container:: table-row 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: sysLanguageUid ~~~~~~~~~~~~~~ .. container:: table-row 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: profileAjaxType ~~~~~~~~~~~~~~~ .. container:: table-row 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: hook ~~~~ .. container:: table-row 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: tidy ~~~~ .. container:: table-row Property tidy Data type int Description Launch the tidy command Default 0 .. _tidy-path: tidy\_path ~~~~~~~~~~ .. container:: table-row Property tidy\_path Data type string Description Configuration parameters given to tidy Default tidy -i -utf8 -xml .. ###### END~OF~TABLE ###### .. _Elements-of-the-Feed-Configuration-select: Elements of the Feed Configuration (select.) """""""""""""""""""""""""""""""""""""""""""" .. ### BEGIN~OF~TABLE ### .. _title: title ~~~~~ .. container:: table-row 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: titleXPath ~~~~~~~~~~ .. container:: table-row 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: summary ~~~~~~~ .. container:: table-row 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: summaryXPath ~~~~~~~~~~~~ .. container:: table-row 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: published ~~~~~~~~~ .. container:: table-row 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: updated ~~~~~~~ .. container:: table-row 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: uid ~~~ .. container:: table-row Property uid Data type string Description the uid field name of the database Default uid .. _pid: pid ~~~ .. container:: table-row Property pid Data type string Description the page id's field name of the database Default pid .. _filterField: filterField ~~~~~~~~~~~ .. container:: table-row 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: filterInclude ~~~~~~~~~~~~~ .. container:: table-row 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: filterExclude ~~~~~~~~~~~~~ .. container:: table-row 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: table ~~~~~ .. container:: table-row Property table Data type string Description which table contains the element of the feed Default tt\_content .. _debug: debug ~~~~~ .. container:: table-row Property debug Data type true/false Description output the request in the RSS feed. Maybe useful to debug the request. Default false .. _linkItem: linkItem ~~~~~~~~ .. container:: table-row 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: defaultText ~~~~~~~~~~~ .. container:: table-row Property defaultText Data type string Description should the element contain a default value. Useful for administrative feed. Default null .. _single-page-pid: single\_page.pid ~~~~~~~~~~~~~~~~ .. container:: table-row 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: single\_page.linkParamUid ~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row 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]= Default null .. _orderBy: orderBy ~~~~~~~ .. container:: table-row Property orderBy Data type string Description defines the order of the feed. Default tstamp DESC .. _where: where ~~~~~ .. container:: table-row Property where Data type string Description defines additional conditions ( where = AND myField = 'myValue') Default null .. _truncate: truncate ~~~~~~~~ .. container:: table-row Property truncate Data type int Description defines how many character the summary should be shorten up. Default null .. _author: author ~~~~~~ .. container:: table-row 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: extraFields ~~~~~~~~~~~ .. container:: table-row Property extraFields Data type string Description additionnal fields extraFields = datefrom, dateto Default empty .. _additionalSQL: additionalSQL ~~~~~~~~~~~~~ .. container:: table-row 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: additionalPids ~~~~~~~~~~~~~~ .. container:: table-row 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: baseUrl ~~~~~~~ .. container:: table-row 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 .. ###### END~OF~TABLE ###### .. _Feed-Configuration-Examples: Feed Configuration Examples --------------------------- .. _Generating-a-RSS-or-ATOM-feed: 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: 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: 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: 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: 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: 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: 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: 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: Available Hooks --------------- One single hook, namely PostProcessingProc, is available and let you post-process each feed entry before displaying / caching it. .. _Configuration: 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: Class Example ^^^^^^^^^^^^^ This example shows how to create a post-processing method which prepends “Hello - “ to the feed title. :: .. _TypoScript-Configuration: 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: Administration -------------- .. _Clear-the-cache: 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: Known problems -------------- Please report the problem you might meet to `fabien.udriot@ecodev.ch `_ .. _To-Do-list: To-Do list ---------- Manage the tag in RSS feed (depending on the demand) .. _Acknowledgments: Acknowledgments --------------- .. _Changelog: **Changelog** ------------- Please refer to the Changelog.txt in the extension itself. EXT: RSS feed - 9 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 67 .. :id: graphics1 .. :name: graphics1 .. :width: 479 .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :height: 179 .. :id: graphics3 .. :name: graphics3 .. :width: 571