1 # <a name="Headlines Plugin"></a><a name=" Headlines Plugin"></a> Headlines Plugin
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>
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>
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>
24 ## <a name="Description"></a> Description
26 This plugin displays RSS and ATOM feeds from news sites. Use it to build news portals that show headline news.
28 **_Note:_** Syndic8.com ( <http://www.syndic8.com/> ) is a good site listing many RSS feeds.
30 ## <a name="Syntax Rules"></a> Syntax Rules
34 <table border="1" cellpadding="0" cellspacing="0">
36 <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
37 <th bgcolor="#99CCCC"><strong> Explanation </strong></th>
38 <th bgcolor="#99CCCC"><strong> Default </strong></th>
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>
46 <td><code>href="..."</code></td>
47 <td> (Alternative to above) </td>
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>
56 <td><code>limit="12"</code></td>
57 <td> Maximum number of items shown </td>
58 <td> Global <code>LIMIT</code> setting </td>
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>
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>
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.
74 ### <a name="Rendering the <code>dc</code> namespace"></a> Rendering the `dc` namespace
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 <title> content </title> is prefered over <dc:title> content </dc:title> .
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)
94 ### <a name="Rendering the <code>image</code> namespace"></a> Rendering the `image` namespace
96 An `image:item` is converted into an <img> tag using the following mappings:
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)
103 ### <a name="Rendering the <code>content</code> namespac"></a> Rendering the `content` namespace
105 The variable $content is refering to the <content:encoding> content </content:encoding>.
107 ## <a name="Examples"></a> Examples
109 ### <a name="Slashdot News"></a> Slashdot News
113 %HEADLINES{"http://slashdot.org/slashdot.rdf"
114 header="*[[$link][$title]]:* $description"
115 format="$t* [[$link][$title]]"
118 to get the latest Slashdot news as a bullet list format:
120 %HEADLINES\{"http://slashdot.org/slashdot.rdf" header="---+!! [[$title|Main/Link]]$n $description" format="$t\* [[$title|Main/Link]]"\}%
122 ### <a name="Business Opportunities Weblog"></a> Business Opportunities Weblog
126 %HEADLINES{"http://www.business-opportunities.biz/feed" limit="3"}%
128 to get the latest postings on the "Business Opportunities" weblog:
130 %HEADLINES\{"http://www.business-opportunities.biz/feed" limit="3"\}%
132 ## <a name="Plugin Settings"></a> Plugin Settings
134 Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%<plugin>\_<setting>%**</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.
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
139 - Refresh rate in minutes for cached feeds. Disable caching: `0`, default: `60`
142 - Maximum number of items shown. Default: `100`
145 - Use LWP::UserAgent, or fallback to TWiki's internal `getUrl()` method. Default: `yes`
146 - Set USELWPUSERAGENT = yes
148 - Timeout fetching a feed using the LWP::UserAgent. Default: `20`
149 - Set USERAGENTTIMEOUT = 20
151 - Name of user agent. Default: `TWikiHeadlinesPlugin/2.21`
153 * Set USERAGENTNAME = TWikiHeadlinesPlugin/2.21
155 - Default header: (variables are explained in the syntax rules)
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>
159 - Default format of one item: (variables are explained in the syntax rules)
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>
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";`
168 ## <a name="Style sheets"></a> Style sheets
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).
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)
186 ## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
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">
191 <th bgcolor="#99CCCC"><strong> File: </strong></th>
192 <th bgcolor="#99CCCC"><strong> Description: </strong></th>
195 <td><code><b>data/TWiki/%TOPIC%.txt</b></code></td>
196 <td> plugin topic </td>
199 <td><code><b>pub/TWiki/%TOPIC%/style.css</b></code></td>
200 <td> default css </td>
203 <td><code><b>lib/TWiki/%TOPIC%.pm</b></code></td>
204 <td> plugin perl module </td>
207 <td><code><b>lib/TWiki/%TOPIC%/Core.pm</b></code></td>
208 <td> plugin core </td>
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">
220 <td align="left">Digest::MD5</td>
221 <td align="left">>=2.33</td>
222 <td align="left">Required. Download from CPAN:Digest::MD5</td>
225 <td align="left">LWP::UserAgent</td>
226 <td align="left">>=5.803</td>
227 <td align="left">Optional. Download from CPAN:LWP::UserAgent</td>
231 ## <a name="Plugin Info"></a> Plugin Info
233 <table border="1" cellpadding="0" cellspacing="0">
235 <td align="right"> Plugin Author: </td>
236 <td> TWiki:Main.PeterThoeny, TWiki:Main.MichaelDaum </td>
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>
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>
247 <td align="right"> Plugin Version: </td>
248 <td> v2.21 - 12 Feb 2009 </td>
251 <td align="right"> Change History: </td>
255 <td align="right"> 12 Feb 2009: </td>
256 <td> {PROXY}{HOST} supports domain with and without protocol -- Peter Thoeny </td>
259 <td align="right"> 06 Feb 2009: </td>
260 <td> added {PROXY}{SkipProxyForDomains} configure setting, added USERAGENTNAME plugin setting -- Peter Thoeny </td>
263 <td align="right"> 11 Dec 2008: </td>
264 <td> added {PROXY}{HOST} and {PROXY}{PORT} configure settings -- Peter Thoeny </td>
267 <td align="right"> 13 Sep 2007: </td>
268 <td> fixed parsing of content:encoded </td>
271 <td align="right"> 23 Jul 2006: </td>
272 <td> improved atom parser; if a posting has no title default to 'Untitled' </td>
275 <td align="right"> 26 Apr 2006: </td>
276 <td> added lazy compilation </td>
279 <td align="right"> 10 Feb 2006: </td>
280 <td> packaged using the TWiki:Plugins/BuildContrib; minor fixes </td>
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>
287 <td align="right"> 23 Jan 2006: </td>
288 <td> released v2.00 </td>
291 <td align="right"> 05 Dec 2005: </td>
292 <td> internal feed urls must be absolute </td>
295 <td align="right"> 02 Dec 2005: </td>
296 <td> added web.topic shorthand for internal feeds </td>
299 <td align="right"> 29 Nov 2005: </td>
300 <td> fixed CDATA handling </td>
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>
307 <td align="right"> 11 May 2005: </td>
308 <td> TWiki:Main.WillNorris: added DevelopBranch compatability </td>
311 <td align="right"> 31 Oct 2004: </td>
312 <td> Fixed taint issue by TWiki:Main.AdrianWeiler; small performance improvement </td>
315 <td align="right"> 29 Oct 2004: </td>
316 <td> Fixed issue of external caching if mod_perl or SpeedyCGI is used </td>
319 <td align="right"> 02 Aug 2002: </td>
320 <td> Implemented caching of feeds, thanks to TWiki:Main/RobDuarte </td>
323 <td align="right"> 11 Jun 2002: </td>
324 <td> Initial version (V1.000) </td>
327 <td align="right"> Perl Version: </td>
331 <td align="right"> TWiki:Plugins/Benchmark: </td>
332 <td>[[TWiki/GoodStyle]] 100%, [[TWiki/FormattedSearch]] 99.5%, %TOPIC% 94% </td>
335 <td align="right"> Plugin Home: </td>
336 <td> TWiki:Plugins/%TOPIC% </td>
339 <td align="right"> Feedback: </td>
340 <td> TWiki:Plugins/%TOPIC%Dev </td>
343 <td align="right"> Appraisal: </td>
344 <td> TWiki:Plugins/%TOPIC%Appraisal </td>
348 -- TWiki:Main.PeterThoeny - 12 Jan 2009 %BR% -- TWiki:Main.MichaelDaum - 13 Sep 2007