in 16 pixels or
in 24 pixels.© 2007-2014 Denis Sureau
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.
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.
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:
https://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
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.
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.
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
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 .
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.
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.
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.
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.
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.
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.
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="https://www.scriptol.com/rss.xml">
and if it is in the Atom format:
<link rel="alternate" type="application/atom+xml" href="https://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.
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.
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.