The Handbook of ARA

© 2007-2014 Denis Sureau

http://www.scriptol.com/

 

What's ARA?

ARA means for Atom API and RSS, it is a library of functions for processing Atom and RSS files and in particular, for generating or editing a syndication feed.
This handbook is devoted to the editor and generator of files of feed.

Pre-requisites

To be able to use Ara, your hosting must support PHP 5. The file of installation will inform you by displaying the version of PHP. If PHP is not available on the site, nothing will be displayed.
Sometimes hosting supports PHP 5 but it is configured in PHP 4 per default. In this case it will have to be reconfigured by a simple line in a .htaccess file stored the repertory of Ara.

SetEnv PHP_VER 5 
or
AddType x-mapp-php5 .php

According to the server and the operating system, the commands of the options of configuration can be different, inform you near your host or your server software.

The program uses the Ajax form Anaa that is included in the archive.

Installation and use

Ara is a Web page that holds a form. To use the Ara editor, it should be installed on the Web site of which you want to syndicate the contents. That simply consists in uploading the contents of the file in a sub-directory, which is named by default Ara, but of which you can choose the name.
These files must be stored on the website:
- any file whose filename starts by ara,
- anaa.js and
- install.php.

Once the files put on line on your site, you type the URL (the complete address of the Web page) of installation file, for example:

http://www.scriptol.com/ara/install.php

This one ask you to register a login and a password. Those are essential before to use the program, to have the right to create and update an RSS file on your site, without anyone could modify it his own way.

Note the login and the password which you chose, then erase the install.php file for security issue

The creation of a feed

Thanks to the many automatisms integrated in the Ara editor by means of PHP scripts is is very easy. For creating a new file, enter its name, then enter the URL of a page and click on the button Add, finally click on Create an RSS feed. And it is all.
We will detail these various steps more precisely.

1) Log in

Within the first form, enter your login and your password. Then click on Check User. You will remain logged for the duration of the session, therefore as long as you do not close the browser.
Once the right login and password recognized by the program, two grayed buttons become active, the button Reload and Create an RSS feed.
You can then start to create a feed.

2) Choose a file name

The second form makes it possible to enter the name of a feed RSS. If you already created a feed which you want to publish, click on the button Reload.
For security, the file name must have an extension, and this one must belong to the following list:

.atom 
.rss 
.xml 
.rdf

The root path

If you want to create a feed named rss.xml and store it at root of the site, enter this path:

/rss.xml

Don't use an absolute Web URL with a domain name. PHP functions used to save an XML file have limits, one cannot use a URL, one needs a relative way. They use a path on the server.
Fortunately the Ara software is able to translate a relative web path to a server path and this is achieved with the file is loaded or by a click on the Convert button.

These issues about path don't apply to Web pages of article or channel, which are indicated by a complete URL .

3) Select the options

The third form contains several options:

number of items

It is the maximum number of articles which the feed will contain. Choose a number in the list or type a number directly.

add description

add date

Include also the date of publication or not.

4) Indicate the channel

The fourth form makes it possible to enter the URL of the channel that is the website, concerned by the feed, and on which you uploaded Ara.
Enter the complete URL.
You can publish the title, description and the date by clicking on Edit. The editor is at the bottom of the page, we will come there.

5) Add the articles

The fifth form makes it possible to enter the URL of the articles and contains a textfield, as well as a button to add the URL to the list.
Note that it is easier to provide the URL of the articles by opening the browser in one second window, by displaying the articles and by recovering the exact URL in the URL field by a double click. Then you type CTRL+C for copy and in the field of article, you type CTRL+V.
When you add the URL of an article, the title (and not the URL) appears in a list above within the fifth form.
On the left of each title, an EDIT button is displayed. Although the descriptive data of the article are extracted automatically from the page, you can wish to modify them.

6) Editing a description

The form of description is common to the channel and the articles. To edit the description of an article, one clicks on the EDIT button on the left of the title in the list.
It is then possible to change the title, description, the date.
Then clicks on the Replace button under the description.

The Clear Fields button erases the contents of all the fields.

In fact one can create an element from scratch with the editor, by giving the URL and all the elements of description. The Replace button then adds the new element to the list.

7) How to erase an item

To renovate your feed of syndication, you need to delete oldest articles in order to add new ones.
It is by using the editor that one deletes an article. Click on EDIT, then on the Delete Item button.

8) Create the feed

If you already typed the name of the file in the top of the page, that you indicated the channel and added at least an article, you can create a feed file by clicking on the button Create an RSS Feed.

If the file has been previously loaded, the path should have been translated to the server path and stored in the textfield above the buttons. Otherwise you have to type the web path (/rss.xml for example) and click on the convert button to translate the path.
Note that if Ara is stored at root of the site, you have just to type the name of the file, no translation is required.

Making the feed visible

Once your file created, and stored at root of the site, or in a sub-directory if it relates to a particular folder, it remains to make it visible to the public and software.

So that a browser can detect the presence of a feed, it is necessary to add the following tag inside the HEAD section of the home page or the page of a project, for a file in the RSS format:

<link rel="alternate" type="application/rss+xml" href="http://www.scriptol.com/rss.xml">

and if it is in the Atom format:

<link rel="alternate" type="application/atom+xml" href="http://www.scriptol.com/atom.xml">

Of course replace scriptol.com by the domain name of your site.
And so that the visitors can reach it, uses an image with a link on the file, stored anywhere on a page:

<a href="rss.xml"> <img   src="images/feed-24x24.png" border="0">My feed</a>

What gives in 16 pixels or in 24 pixels.

Security issues

As you can note it, Ara will function only if one gives initially a password. The name of user and the password are chosen by yourself at installation stage. You remain logged on the editor and can use it as long as you do not disconnect yourselves from the site, which arrives when you close the browser or the tab of the page.
Another security measure is the control of the type of file. Only the files having the extensions whose list is given higher can be created on the site.
Do not forget to erase the install.php file once you are registered. This precaution taken, it is normally impossible to a malicious user to affect your site through the Ara scripts. However, if you have a doubt about the safety of the software, add a comment on the Ara page on the website.

Conditions of use

Ara is under the GNU GPL license. You can use it freely and for free. It is allowed to you to modify the source and to distribute it but by preserving the copyright notice in the files. It is forbidden to modify the program to remove the security measures which it comprises and to distribute it in this form.


By Denis Sureau on June 25, 2007. Software and documentation available on Scriptol.com.