TWiki/HeadlinesPlugin.mdwn

   1 # <a name="Headlines Plugin"></a><a name=" Headlines Plugin"></a> Headlines Plugin
   2
   3 <div>
   4   <ul>
   5     <li><a href="#Description"> Description</a></li>
   6     <li><a href="#Syntax Rules"> Syntax Rules</a><ul>
   7         <li><a href="#Rendering the <code>dc</code> namespace"> Rendering the dc namespace</a></li>
   8         <li><a href="#Rendering the <code>image</code> namespace"> Rendering the image namespace</a></li>
   9         <li><a href="#Rendering the <code>content</code> namespac"> Rendering the content namespace</a></li>
  10       </ul>
  11     </li>
  12     <li><a href="#Examples"> Examples</a><ul>
  13         <li><a href="#Slashdot News"> Slashdot News</a></li>
  14         <li><a href="#Business Opportunities Weblog"> Business Opportunities Weblog</a></li>
  15       </ul>
  16     </li>
  17     <li><a href="#Plugin Settings"> Plugin Settings</a></li>
  18     <li><a href="#Style sheets"> Style sheets</a></li>
  19     <li><a href="#Plugin Installation Instructions"> Plugin Installation Instructions</a></li>
  20     <li><a href="#Plugin Info"> Plugin Info</a></li>
  21   </ul>
  22 </div>
  23
  24 ## <a name="Description"></a> Description
  25
  26 This plugin displays RSS and ATOM feeds from news sites. Use it to build news portals that show headline news.
  27
  28 **_Note:_** Syndic8.com ( <http://www.syndic8.com/> ) is a good site listing many RSS feeds.
  29
  30 ## <a name="Syntax Rules"></a> Syntax Rules
  31
  32 `%HEADLINES{"..."}%`
  33
  34 <table border="1" cellpadding="0" cellspacing="0">
  35   <tr>
  36     <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
  37     <th bgcolor="#99CCCC"><strong> Explanation </strong></th>
  38     <th bgcolor="#99CCCC"><strong> Default </strong></th>
  39   </tr>
  40   <tr>
  41     <td><code>"..."</code></td>
  42     <td> source of RSS feed; this can be an url (starting with http) or a web.topic location for internal feeds </td>
  43     <td> None; is required </td>
  44   </tr>
  45   <tr>
  46     <td><code>href="..."</code></td>
  47     <td> (Alternative to above) </td>
  48     <td> N/A </td>
  49   </tr>
  50   <tr>
  51     <td><code>refresh="60"</code></td>
  52     <td> Refresh rate in minutes for caching feed; <code>"0"</code> for no caching </td>
  53     <td> Global <code>REFRESH</code> setting </td>
  54   </tr>
  55   <tr>
  56     <td><code>limit="12"</code></td>
  57     <td> Maximum number of items shown </td>
  58     <td> Global <code>LIMIT</code> setting </td>
  59   </tr>
  60   <tr>
  61     <td><code>header</code></td>
  62     <td> Header. Can include these variables: - $channeltitle, $title: title of channel (channel.title) %BR% - $channellink, $link: link of channel (channel.link) %BR% - $channeldescription, $description: description (channel.description) %BR% - $channeldate, $date: publication date of the channel (channel.pubDate) %BR% - $rights: copyrights of the channel (channel.copyright) %BR% - $imagetitle: title text for site (image.title) %BR% - $imagelink: link for site (image.link) %BR% - $imageurl: URL of image (image.url) %BR% - $imagedescription: description of image (image.description) </td>
  63     <td> Global <code>HEADER</code> setting </td>
  64   </tr>
  65   <tr>
  66     <td><code>format</code></td>
  67     <td> Format of one item. Can include these variables: %BR% - $title: news item title (item.title) %BR% - $link: news item link (item.link) %BR% - $description: news item description (item.description) %BR% - $date: the publication date (item.pubDate, item.date) %BR% - $category: the article category (item.category) </td>
  68     <td> Global <code>FORMAT</code> setting </td>
  69   </tr>
  70 </table>
  71
  72 The `header` and `format` parameters might also use variables rendering the `dc`, `image` and `content` namespace information. Note, that only bits of interest have been implemented so far and those namespaces might not be implemented fully yet.
  73
  74 ### <a name="Rendering the &lt;code&gt;dc&lt;/code&gt; namespace"></a> Rendering the `dc` namespace
  75
  76 The following variables are extracting the `dc` namespace info, that could be used in `header` and `format`. Nnote, that some of the variables are already used above. This is done by purpose to use different feeds with the same formating parameters. If there's a conflict the non-dc tags have higher precedence, i.e. a &lt;title&gt; content &lt;/title&gt; is prefered over &lt;dc:title&gt; content &lt;/dc:title&gt; .
  77
  78 - $title: channel/article title (dc:title)
  79 - $creator: channel creator (dc:creator)
  80 - $subject: subject text; this will also add an image according to the subject hash list, see [[above|Main/WebHome#Subject_Images]] (dc:subject)
  81 - $description: ... (dc:description)
  82 - $publisher: the channel/article publisher (dc:publisher)
  83 - $contributor: ... (dc:contributor)
  84 - $date: ... (dc:date)
  85 - $type: ... (dc:type)
  86 - $format: ... (dc:format)
  87 - $identifier: ... (dc:identifier)
  88 - $source: ... (dc:source)
  89 - $language: ... (dc:language)
  90 - $relation: ... (dc:relation)
  91 - $coverage: ... (dc: coverage)
  92 - $rights: ... (dc: rights)
  93
  94 ### <a name="Rendering the &lt;code&gt;image&lt;/code&gt; namespace"></a> Rendering the `image` namespace
  95
  96 An `image:item` is converted into an &lt;img&gt; tag using the following mappings:
  97
  98 - `src`: image url (rdf:about attribute of the image.item tag)
  99 - `alt`: image title (title)
 100 - `width`: image width (image:width)
 101 - `height`: image height image:height)
 102
 103 ### <a name="Rendering the &lt;code&gt;content&lt;/code&gt; namespac"></a> Rendering the `content` namespace
 104
 105 The variable $content is refering to the &lt;content:encoding&gt; content &lt;/content:encoding&gt;.
 106
 107 ## <a name="Examples"></a> Examples
 108
 109 ### <a name="Slashdot News"></a> Slashdot News
 110
 111 Write
 112
 113     %HEADLINES{"http://slashdot.org/slashdot.rdf"
 114       header="*[[$link][$title]]:* $description"
 115       format="$t* [[$link][$title]]"
 116     }%
 117
 118 to get the latest Slashdot news as a bullet list format:
 119
 120 %HEADLINES\{"http://slashdot.org/slashdot.rdf" header="---+!! [[$title|Main/Link]]$n $description" format="$t\* [[$title|Main/Link]]"\}%
 121
 122 ### <a name="Business Opportunities Weblog"></a> Business Opportunities Weblog
 123
 124 Write
 125
 126     %HEADLINES{"http://www.business-opportunities.biz/feed" limit="3"}%
 127
 128 to get the latest postings on the "Business Opportunities" weblog:
 129
 130 %HEADLINES\{"http://www.business-opportunities.biz/feed" limit="3"\}%
 131
 132 ## <a name="Plugin Settings"></a> Plugin Settings
 133
 134 Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%&lt;plugin&gt;\_&lt;setting&gt;%**</code>, for example, <code>**%HEADLINESPLUGIN\_SHORTDESCRIPTION%**</code>. **Note:** Don't modify the settings here; copy and customize the settings in [[Main.TWikiPreferences|Main/TWikiPreferences]]. For example, to customize the USERAGENTNAME setting, create a HEADLINESPLUGIN\_USERAGENTNAME setting in Main.TWikiPreferences.
 135
 136 - One line description, shown in the [[TextFormattingRules]] topic:
 137   - Set SHORTDESCRIPTION = Show headline news in TWiki pages based on RSS and ATOM news feeds from external sites
 138
 139 - Refresh rate in minutes for cached feeds. Disable caching: `0`, default: `60`
 140   - Set REFRESH = 60
 141
 142 - Maximum number of items shown. Default: `100`
 143   - Set LIMIT = 100
 144
 145 - Use LWP::UserAgent, or fallback to TWiki's internal `getUrl()` method. Default: `yes`
 146   - Set USELWPUSERAGENT = yes
 147
 148 - Timeout fetching a feed using the LWP::UserAgent. Default: `20`
 149   - Set USERAGENTTIMEOUT = 20
 150
 151 - Name of user agent. Default: `TWikiHeadlinesPlugin/2.21`
 152
 153           * Set USERAGENTNAME = TWikiHeadlinesPlugin/2.21
 154
 155 - Default header: (variables are explained in the syntax rules)
 156
 157           * Set HEADER = <div class="headlinesChannel"><div class="headlinesLogo"><img src="$imageurl" alt="$imagetitle" border="0" />%BR%</div><div class="headlinesTitle">$n---+!! <a href="$link">$title</a></div><div class="headlinesDate">$date</div><div class="headlinesDescription">$description</div><div class="headlinesRight">$rights</div></div>
 158
 159 - Default format of one item: (variables are explained in the syntax rules)
 160
 161           * Set FORMAT = <div class="headlinesArticle"><div class="headlinesTitle"><a href="$link">$title</a></div>$n<span class="headlinesDate">$date</span> <span class="headlinesCreator"> $creator</span> <span class="headlinesSubject"> $subject </span>$n<div class="headlinesText"> $description</div></div>
 162
 163 - Values taken from configure: (only supported if CPAN:LWP is installed)
 164   - `$TWiki::cfg{PROXY}{HOST}` - proxy host, such as `"proxy.example.com";`
 165   - `$TWiki::cfg{PROXY}{PORT}` - proxy port, such as `"8080";`
 166   - `$TWiki::cfg{PROXY}{SkipProxyForDomains}` - domains excluded from proxy, such as `"intra.example.com, bugs.example.com";`
 167
 168 ## <a name="Style sheets"></a> Style sheets
 169
 170 The default HEADER and FORMAT settings use the following styles. See the [style.css](http://www.dementia.org/twiki//view/style.css) file defining the default CSS properties (indentation illustrates enclosure).
 171
 172 - headlinesRss: output of the [[HeadlinesPlugin]] (div)
 173   - headlinesChannel: channel header (div)
 174     - headlinesLogo: channel logo (div)
 175     - headlinesTitle: channel title (div)
 176     - headlinesDate: channel date (div)
 177     - headlinesDescription: channel description (div)
 178     - headlinesRight: channel copyright (div)
 179   - headlinesArticle: one news item (div)
 180     - headlinesTitle: article title (div)
 181     - headlinesDate: article date (span)
 182     - headlinesCreator: author of article (span)
 183     - headlinesSubject: subect category of the article (span)
 184     - headlinesText: article text (div)
 185
 186 ## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
 187
 188 - [Download](http://www.dementia.org/twiki//view/%TOPIC%.zip) the ZIP file
 189 - Unzip it in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
 190   <tr>
 191     <th bgcolor="#99CCCC"><strong> File: </strong></th>
 192     <th bgcolor="#99CCCC"><strong> Description: </strong></th>
 193   </tr>
 194   <tr>
 195     <td><code><b>data/TWiki/%TOPIC%.txt</b></code></td>
 196     <td> plugin topic </td>
 197   </tr>
 198   <tr>
 199     <td><code><b>pub/TWiki/%TOPIC%/style.css</b></code></td>
 200     <td> default css </td>
 201   </tr>
 202   <tr>
 203     <td><code><b>lib/TWiki/%TOPIC%.pm</b></code></td>
 204     <td> plugin perl module </td>
 205   </tr>
 206   <tr>
 207     <td><code><b>lib/TWiki/%TOPIC%/Core.pm</b></code></td>
 208     <td> plugin core </td>
 209   </tr>
 210 </table>
 211  Check if above examples show a news feed instead of variable.
 212 - Optionally, run <code>**%TOPIC%\_installer.pl**</code> to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
 213 - Alternatively, manually make sure the dependencies listed in the table below are resolved. <table border="1">
 214   <tr>
 215     <th>Name</th>
 216     <th>Version</th>
 217     <th>Description</th>
 218   </tr>
 219   <tr>
 220     <td align="left">Digest::MD5</td>
 221     <td align="left">&gt;=2.33</td>
 222     <td align="left">Required. Download from CPAN:Digest::MD5</td>
 223   </tr>
 224   <tr>
 225     <td align="left">LWP::UserAgent</td>
 226     <td align="left">&gt;=5.803</td>
 227     <td align="left">Optional. Download from CPAN:LWP::UserAgent</td>
 228   </tr>
 229 </table>
 230
 231 ## <a name="Plugin Info"></a> Plugin Info
 232
 233 <table border="1" cellpadding="0" cellspacing="0">
 234   <tr>
 235     <td align="right"> Plugin Author: </td>
 236     <td> TWiki:Main.PeterThoeny, TWiki:Main.MichaelDaum </td>
 237   </tr>
 238   <tr>
 239     <td align="right"> Copyright: </td>
 240     <td> © 2002-2009, Peter Thoeny, <a href="http://www.twiki.net/" target="_top">TWIKI.NET</a>; 2005-2007, Michael Daum <a href="http://wikiring.de" target="_top">http://wikiring.de</a></td>
 241   </tr>
 242   <tr>
 243     <td align="right"> License: </td>
 244     <td> GPL (<a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GNU General Public License</a>) </td>
 245   </tr>
 246   <tr>
 247     <td align="right"> Plugin Version: </td>
 248     <td> v2.21 - 12 Feb 2009 </td>
 249   </tr>
 250   <tr>
 251     <td align="right"> Change History: </td>
 252     <td>  </td>
 253   </tr>
 254   <tr>
 255     <td align="right"> 12 Feb 2009: </td>
 256     <td> {PROXY}{HOST} supports domain with and without protocol -- Peter Thoeny </td>
 257   </tr>
 258   <tr>
 259     <td align="right"> 06 Feb 2009: </td>
 260     <td> added {PROXY}{SkipProxyForDomains} configure setting, added USERAGENTNAME plugin setting -- Peter Thoeny </td>
 261   </tr>
 262   <tr>
 263     <td align="right"> 11 Dec 2008: </td>
 264     <td> added {PROXY}{HOST} and {PROXY}{PORT} configure settings -- Peter Thoeny </td>
 265   </tr>
 266   <tr>
 267     <td align="right"> 13 Sep 2007: </td>
 268     <td> fixed parsing of content:encoded </td>
 269   </tr>
 270   <tr>
 271     <td align="right"> 23 Jul 2006: </td>
 272     <td> improved atom parser; if a posting has no title default to 'Untitled' </td>
 273   </tr>
 274   <tr>
 275     <td align="right"> 26 Apr 2006: </td>
 276     <td> added lazy compilation </td>
 277   </tr>
 278   <tr>
 279     <td align="right"> 10 Feb 2006: </td>
 280     <td> packaged using the TWiki:Plugins/BuildContrib; minor fixes </td>
 281   </tr>
 282   <tr>
 283     <td align="right"> 03 Feb 2006: </td>
 284     <td> off-by-one: limit="n" returned n+1 articles; make FORMAT and HEADER format strings more robust </td>
 285   </tr>
 286   <tr>
 287     <td align="right"> 23 Jan 2006: </td>
 288     <td> released v2.00 </td>
 289   </tr>
 290   <tr>
 291     <td align="right"> 05 Dec 2005: </td>
 292     <td> internal feed urls must be absolute </td>
 293   </tr>
 294   <tr>
 295     <td align="right"> 02 Dec 2005: </td>
 296     <td> added web.topic shorthand for internal feeds </td>
 297   </tr>
 298   <tr>
 299     <td align="right"> 29 Nov 2005: </td>
 300     <td> fixed CDATA handling </td>
 301   </tr>
 302   <tr>
 303     <td align="right"> 21 Nov 2005: </td>
 304     <td> added ATOM support; extended RSS support; added dublin core support; added content support; optionally using LWP to fetch feeds to follow redirections; corrected CPAN dependencies ; recoding special chars from html integer to entity encoding to increase browser compatibility; added css support; use <code>getWorkArea()</code> if available </td>
 305   </tr>
 306   <tr>
 307     <td align="right"> 11 May 2005: </td>
 308     <td> TWiki:Main.WillNorris: added DevelopBranch compatability </td>
 309   </tr>
 310   <tr>
 311     <td align="right"> 31 Oct 2004: </td>
 312     <td> Fixed taint issue by TWiki:Main.AdrianWeiler; small performance improvement </td>
 313   </tr>
 314   <tr>
 315     <td align="right"> 29 Oct 2004: </td>
 316     <td> Fixed issue of external caching if mod_perl or SpeedyCGI is used </td>
 317   </tr>
 318   <tr>
 319     <td align="right"> 02 Aug 2002: </td>
 320     <td> Implemented caching of feeds, thanks to TWiki:Main/RobDuarte </td>
 321   </tr>
 322   <tr>
 323     <td align="right"> 11 Jun 2002: </td>
 324     <td> Initial version (V1.000) </td>
 325   </tr>
 326   <tr>
 327     <td align="right"> Perl Version: </td>
 328     <td> 5.8 </td>
 329   </tr>
 330   <tr>
 331     <td align="right"> TWiki:Plugins/Benchmark: </td>
 332     <td>[[TWiki/GoodStyle]] 100%, [[TWiki/FormattedSearch]] 99.5%, %TOPIC% 94% </td>
 333   </tr>
 334   <tr>
 335     <td align="right"> Plugin Home: </td>
 336     <td> TWiki:Plugins/%TOPIC% </td>
 337   </tr>
 338   <tr>
 339     <td align="right"> Feedback: </td>
 340     <td> TWiki:Plugins/%TOPIC%Dev </td>
 341   </tr>
 342   <tr>
 343     <td align="right"> Appraisal: </td>
 344     <td> TWiki:Plugins/%TOPIC%Appraisal </td>
 345   </tr>
 346 </table>
 347
 348 -- TWiki:Main.PeterThoeny - 12 Jan 2009 %BR% -- TWiki:Main.MichaelDaum - 13 Sep 2007