Using the Tuttinova interface allows you to manage topics and edit news. That is handy, but only half of the job : you still need to display these news on your web site or application.
This document explains how to grab news from the Tuttinova backend, namely the Nova class, and output them in various manners :
Note: You will need some PHP knowledge to understand what follows.
Before doing anything else you need to load and instantiate a Nova object : it is a small subset of the Tuttinova backend, optimized to retrieve news fastly.
Example 1. Load and create a Nova object
<?php
include '/path/to/tuttinova/Nova.php';
$nova = new Nova('main');
?>
In Example 1, we first load the Nova.php
file and then provide the Nova constructor with the name of the topic we want to retrieve news from : main
You should replace main
with whatever topic name you've set up in
the Tuttinova administration interface
As you can see in Example 1, we provide a complete path to Nova.php
.
That works fine, and is pretty useful when your hosting provider does not allow
you to modify the include_path
php configuration value. Of course, if you
can modify it, you may provide a shorter/relative path instead.
<?php
include '/path/to/tuttinova/Nova.php';
$nova = new Nova(array('salsa','rumba'));
?>
Example 1.1 shows how to retrieve news from several topics, by passing an array
of topics names instead of a single string. That will mix news from the two
topics salsa
and rumba
.
All examples below assume that you use a single topic when retrieving your news, but you can pass an array of topics in all cases.
This is pretty straightforward to achieve. The news you grab from the Nova Reader come as a 2-dimensions associative array : you just need to iterate and output.
Example 2 is a complete and working example that you can copy and paste as a quickstart.
It is included in the Tuttinova distribution, and located in ./example/index.php
.
<!-- Tuttinova - example/index.php : News list example -->
<html>
<head>
<title>Example</title>
</head>
<body>
<h1>Example for "main"</h1>
<?php
// Load and instantiate a Nova object
include '../Nova.php';
$nova = new Nova('main'); // Change 'main' to your topic name
// Grab the news
$data = $nova->fetch(10);
// Try displaying the news
if ($data === false) {
echo "<b>ERROR:</b> Couldn't retrieve the news";
} elseif (empty($data)) {
echo "No news";
} else {
foreach ($data as $news) {
extract ($news);
echo "<p><b>$subject</b><br>\n";
echo "$author - " . date ('n/j/Y \a\t g:i a',$date) . "</p>\n";
echo "<p>$content</p>\n";
echo "<a href=single.php?id=$id>Read More...</a><hr>\n";
}
}
?>
</body>
</html>
This news list features the common "Read more..." link, which links here to a
script named single.php
. That script is supposed to display a single
news on a page of its own. This is just an example, that mainly demonstrates the
use of the internal $id
field.
The $id
variable (extracted from $news['id']
) provides
a unique identifier for each news, which is handy for the purpose of calling a
such script as single.php
, or whatever you'll choose to call that
script.
This section explains how to retrieve a news with a specific id. As showed in the News list section Tuttinova uses an internal data field to attribute each news a unique identifier.
The Nova class, in turn, provides the fetchSingle()
method which accepts
this identifier as argument, as demonstrated in Example 3. This example is provided as a
standalone file located in ./example/single.php
<!-- Tuttinova - example/single.php : Single news example -->
<html>
<head>
<title>Single news example</title>
</head>
<body>
<?php
// 1 - Load and instantiate a Nova object
include '../Nova.php';
$nova = new Nova(); // Change 'main' to your topic name
// 2 - Grab the news
$news = $nova->fetchSingle(@$_GET['id']);
// 3 - Display the news (or not)
if (!$news) {
echo "No such news id : '" . @$_GET['id'] . "'\n";
} else {
extract ($news);
echo "<h1>$subject</h1>\n";
echo "<p><b>$author</b> - " . date ('n/j/Y \a\t g:i a', $date) . "</p>\n";
echo "<p>$content</p><hr>\n";
echo "<a href=index.php>Back to index</a>\n";
}
?>
</body>
</html>
Let's now see how to generate a so-called RSS feed. The Nova::fetchRSS() method is meant for this purpose.
Example 4. RSS feed
<?php
/* Tuttinova - example/rss.php : RSS feed example */
header('Content-type: text/xml');
echo '<?xml version="1.0" encoding="UTF-8"?>';
?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/">
<channel>
<title>Tuttinova RSS Example</title>
<link>http://tuttinova.sourceforge.net</link>
<language>en-us</language>
<description>Demonstrates Tuttinova's RSS features</description>
<?php
// Load and create a Nova object
include '../Nova.php';
$nova = new Nova('main');
// Set up a link passing the news {id} as GET parameter
$tags = array (
'link' => 'http://' . $_SERVER['HTTP_HOST'] .
dirname($_SERVER['PHP_SELF']) . '/single.php?id={id}'
);
// Grab the formatted RSS news items
$rss = $nova->fetchRSS(10, 0, $tags);
// Display the news
echo $rss;
?>
</channel>
</rss>
Example 4 demonstrates the use of the fetchRSS()
method, which accepts as
its first argument the number of news to retrieve, and as second argument
the news to start fetching from, exactly as fetch()
.
The difference with fetch(), though, is that this will grab news as preformated RSS items. That is why we need to pass it this third argument , $tags, to configure how RSS tags are related to the actual news data fields.
In Example 4, we only setup the link
tag, which may be sufficient in many case,
since the Nova routine will automatically fill in the title
, description
,
and dc:creator
tags. We set up a url string, and use the {id}
expression to pass the linked script the news unique indentifier as a GET argument.
But if all that's a bit obscure to you, just copy and paste the above example,
change 'main'
argument to your own topic name, and you're done.
If you feel like customizing your RSS feed, though, then read on.
The default RSS tags that Nova::fetchRSS()
will
generate are shown below :
<?php
= array(
'title' => '{subject}',
'link' => null,
'description' => '{content}',
'dc:creator' => '{author}',
);
?>
So if you call this method, ignoring the $tags
argument, as in :
<?php
echo $nova->fetchRss(10);
?>
You should obtain something like :
<item>
<title>This is news 1</title>
<description>Here comes the content of your news</description>
<dc:creator>your_tuttinova_username</dc:creator>
<dc:date>2004-06-01</dc:date>
</item>
[...]
<item>
<title>This is news 10</title>
<description>Here comes the content of your news</description>
<dc:creator>your_tuttinova_username</dc:creator>
<dc:date>2004-01-01</dc:date>
</item>
As you can see, no <link>
tag is generated. This is
because the default value is null
Similarly, if you set 'dc:creator'
to null, you won't get
any <dc:creator>
tag.
Note that the <dc:date> content is generated using an internal rendering routine.
Example 5. Advanced RSS tags customization
<?php
$tags = array(
'link' => 'http://www.foobar.com/shownews?id={id}',
'category' => '{category}',
'subject' => '[FOOBAR} {subject}',
'guid' => 'FOOBAR_{id}',
'dc:publisher' => 'Foo & Bar Corporate',
'dc:creator' => null,
);
$rssItems = $nova->fetchRSS($howMany, $offset, $tags);
?>
In Example 5. we further use expressions enclosed in brackets, namely :
{id}
, {subject}
and {category}
.
We also properly set up a guid
tag so that the news feed
readers can identify news uniquely. About this, note that the tuttinova
internal id field is composed of both the topic name and a numerical
news index.
Since you can create new data fields in Tuttinova (as this hypothetic
'category' field shown in Example 5), this makes the RSS rendering routine
quite flexible. You can set up static content as well, as the 'dc:publisher'
entry demonstrates.