Howto integrate Tuttinova into your project


Introduction

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.

The Nova class

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.

Example 1.1. Handle multiple topics at once

<?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.

A simple news list

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.

Example 2. News list


<!--  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.

A single news

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

Example 3. Single News, retrieved by ID


<!--  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>

RSS feed

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.

RSS customization

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}.

These will replaced by the corresponding news field content. That is, these expressions are "variables".

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.