NAME

Library::News - Perl extension for managing an XML news file

SYNOPSIS

use Library::News;

shell_add_new("news.xml");

news2Html("news.xml", 4);

showForm("news.xml", \%ARGS);

setLanguage("pt");

@languages = languages();

DESCRIPTION

The News module aims to help web masters designing and managing web sites news in an easy way. The news module provides three functions. Two of them provide managing features (adding a new) and the other provides an easy way for printing the new.

Note that the news XML file should not be edited manually.

There is a project to make an object oriented API for using this module but is not yet full implemented.

languages

This function returns an array with the possible languages to use. When choosing a language with the setLanguage function, you must enter a code equal to on returned by this function.

setLanguage

This function sets the language to be used. To know what language to use, call the last function and print the elements of the array.

By default, it is used portuguese (pt).

You must not use this module in different languages over the same file.

shell_add_new

This function is designed to be used in the shell. You can have a program named add_new, written in Perl like

#!/usr/bin/perl

my $filename = shift;
shell_add_new($filename);

for adding news to some file. So, you can call it using

add_new news.xml

and the program will prompt for all the data it needs. If you have only a file, you can replace the line

my $filename = shift;

with something like

my $filename = "news.xml";

The second argument to shell_add_new is not needed but can be used: the name of the language to use.

news2Html

This is a pretty printer for the news xml file. You should supply the news XML filename and a number 'n'. The function returns a string with the most recent 'n' news formatted in HTML for direct use in a CGI. If 'n' is -1, then, news2Html returns all news converted to HTML.

The third argument, if supplied, changes the language used to parse the XML file.

showForm

This function was designed to be used on CGI. Most web designers have to maintain ways of updating information by thirty part persons. So, it can create a web CGI to add news.

The way is calling showForm with the news XML filename and a reference to an hash with the CGI parameters and printing the resulting string. showForm returns HTML for a form asking for the news information. Then, it calls itself to check the correctness of the new XML. If the XML is not correct, it asks for the user correct it. If the XML is correct, it asks if the user wants to continue. If yes, it updates the news XML file.

If using the CGI module you can convert the param() function to an hash using:

@keys = param();
foreach $key (@keys) {
  $args{$key} = param($key);
}
showForm("news.xml",\%args);

You can change the language to use in the %args array. For example, use:

$args{language}='uk'

DTD

Using english:

<!ENTITY % xhtml-subset "(#PCDATA|em|ol|ul|a|img)" >

<!ELEMENT news (new+) >
<!ELEMENT new (date, title, url?, text) >
<!ELEMENT date #PCDATA>
<!ELEMENT title #PCDATA>
<!ELEMENT url #PCDATA>
<!ELEMENT a #PCDATA>
   <!ATTLIST a href CDATA #REQUIRED>
<!ELEMENT text (%xhtml-subset;|p)+>
<!ELEMENT p (%xhtml-subset;) >
<!ELEMENT em (#PCDATA) >
<!ELEMENT ol (li+) >
<!ELEMENT ul (li+) >
<!ELEMENT li (%xhtml-subset;|p)>
<!ELEMENT img EMPTY>
   <!ATTLIST img src CDATA #REQUIRED
                 alt CDATA #REQUIRED>

Using portuguese:

<!ENTITY % xhtml-subset "(#PCDATA|em|ol|ul|a|img)" >

<!ELEMENT novidades (novidade+) >
<!ELEMENT novidade (date, titulo, url?, texto) >
<!ELEMENT data #PCDATA>
<!ELEMENT titulo #PCDATA>
<!ELEMENT url #PCDATA>
<!ELEMENT a #PCDATA>
   <!ATTLIST a href CDATA #REQUIRED>
<!ELEMENT texto (%xhtml-subset;|p)+>
<!ELEMENT p (%xhtml-subset;) >
<!ELEMENT em (#PCDATA) >
<!ELEMENT ol (li+) >
<!ELEMENT ul (li+) > 
<!ELEMENT li (%xhtml-subset;|p)>
<!ELEMENT img EMPTY>
   <!ATTLIST img src CDATA #REQUIRED
                 alt CDATA #REQUIRED>

Other languages can be added using the News.lang file in the lib directory.

AUTHOR

Alberto M. B. Simões, <albie@alfarrabio.um.geira.pt>

SEE ALSO

Manpages CGI(3), perl(1).

cpanm Library::News

perl -MCPAN -e shell
install Library::News