The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Blog-Simple-0.03
1 ++
/ Blog::Simple

NAME

Blog::Simple - Perl extension for the creation of a simple weblog (blogger) system.

SYNOPSIS

        use Blog::Simple;

        my $sbO = Blog::Simple->new();

        # generally you need to call $sbO->create_index() only once to create bb.idx
        $sbO->create_index() unless (-f 'bb.idx');

        my $content='<p>blah blah blah in XHTML </p>
        <p><b>Better</b> when done in XHTML </p>';
        my $title = 'some title';
        my $author = 'a.n. author';
        my $email = 'anaouthor@somedomain.net';
        my $smmry = 'blah blah';

        # add blog entry
        $sbO->add($title,$author,$email,$smmry,$content);

        # get result in $outHTML
        my $outHTML = $sbO->render_current('blog_test.xsl',3);

        # print result to STDOUT
        $sbO->render_all('blog_test.xsl', '-');

        # print result in 'blog.html'
        $sbO->render_current('blog_test.xsl',1,'blog.html');

        $sbO->remove('08');

REQUIRES

XML::XSL

EXPORT

None by default.

DESCRIPTION

This module provides a simple mechanism for blogging, the reverse chronological diary-like systems so popular on the Internet today. It was intended to be simple, and just handles the basics of blogging: managing blog entries (adding, removing -- there probably should be a 'modify,' but there isn't), generating the most recent n entries, and generating all of the entries in the 'blogbase'.

Blog::Simple requires that the XML::XSL module be installed. Rather than try and do the rendering itself, it passes the XML that it generates to an XSL file that the user creates. So you will need to know XSLT to really find this module useful.

Blog::Simple generates XML files and stores them in a blogbase and in a timestamped subfolder. The blogbase consists of a folder under the path you specify in your code called b_base and a file called bb.idx. If no path is given, then it uses the directory the calling Perl file is saved in. bb.idx contains a tab-delimited list of the path, datestamp, title, author, summary of each blog entry. The Blog::Simple generated XML files are stored underneath b_base in automatically generated timestamped folders.

The XML entry for a blog is rendered as follows (this XML template is hardcoded in the add() method):

        <simple_blog>
        
                <!-- title of blog -->
                <title>$title</title>
                
                <!-- who wrote it -->
                <author>$author</author>
                
                <!-- email -->
                <email>$email</email>

                <!-- timestamp - generated automatically -->
                <ts>$ts</ts>
                
                <!-- just text here - NO TABS -->
                <summary>$smmry</summary>
                
                <!-- put XHTML blog between these tags      -->
                <!--   <img> tags must refer to same folder -->
                <content>$content</content>
        
        </simple_blog>

When you tell Blog::Simple to generate its output, you will need an XSL document. One I used for testing looks like:

        <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
        
                <!-- this is the main template match -->
                <xsl:template match="/">
                        <xsl:apply-templates select="simple_blog_wrap/simple_blog"/>              
                </xsl:template>

                <xsl:template match="simple_blog">
                        <xsl:apply-templates select="title"/>
                        <xsl:apply-templates select="ts"/>
                        <xsl:apply-templates select="content"/> 
                </xsl:template>

                <xsl:template match="title"><xsl:copy-of select="."/></xsl:template>

                <xsl:template match="ts"><xsl:copy-of select="."/></xsl:template>

                <xsl:template match="content"><xsl:copy-of select="."/></xsl:template>

        </xsl:stylesheet>

That should get you started. An XSL stylesheet is required when you invoke the render_current() and render_all() methods. Blog::Simple wraps a root element around all the <simple_blog></simple_blog> elements it renders called <simple_blog_wrap></simple_blog_wrap>. Keep this in mind when you are writing your XSL stylesheet.

METHODS

new( [$path] )

The new() method instantiates a new Blog::Simple object. It sets the path to the blogbase, defaulting to the directory of the calling script if no path is given. Use relative or absolute paths. For example:

        $sbO = Blog::Simple->new('c:/absolute/path');

or

        $sbO = Blog::Simple->new('../path/to/somewhere/relative');

create_index()

Call this method only once per blogbase you create. It merely generates the files necessary for Blog::Simple to work. You can manually create them somewhere, if you create the file bb.idx and the subdirectory b_base in some directory dir on your system, and then pass this path to the new() method. The resulting file structure in any case should be

          <path>/
                /bb.idx 
                /b_base

There are no arguments for this method.

        $sbO->create_index();

add( $title, $author, $email, $smmry, $content )

This adds an entry into the blogbase. It generates the XML and stores it as a file in a subdirectory below b_base. It also updates the blogbase, bb.idx, generating a timestamp and putting it at the head of the file.

        $sbO->add('some title', 'some author', 'sa@somewhere.net', 'some summary', 'some content, etc, etc...');

remove( $regex )

This method takes a regular expression, and searches through the bb.idx file, removing the entries that match. It creates an array of the paths of the entries it has removed, and stuffs a reference of it in a hash key associated with the object, called del_list. It does not remove the directories from the b_base directory; the array it returns can be used to do this.

        $sbO->remove('\:1[5-6]');

In order to access the array of deleted paths, the value of

        $sbO->{del_list};

is a reference to the created array, whose elements can be gotten by using

        while(@{$sbO->{del_list}}) {
                #process elements
        }

or some such.

render_current( $xsl_file [, $display_num, $out_file] )

This method processes an arbitrary number of the most recent blog entries against an XSL stylesheet that is passed as an argument. You pass it the stylesheet path/filename, and the number of entries to process. It will retrieve the entries from the filesystem, and wrap them in the root element <simple_blog_wrap></simple_blog_wrap> before passing them to your stylesheet. If the $display_num parameter is missing, the method defaults to 1, and returns one blog entry. $outfile is the path/filename to the output file. If you do not specify this, output is returned to STDOUT.

        $sbO->render_current('myxslfile.xsl', 3, 'output.html');

generates three blog entries and saves them to the file output.html. The same call, but sent to standard output:

        $sbO->render_current('myxslfile.xsl', 3, '-');

and again, but get the output in local variable:

        my $output = $sbO->render_current('myxslfile.xsl', 3);

render_all( $xsl_file [, $out_file] )

render_all() looks up all the blog entries stored in the blogbase and applies the stylesheet you provide against it. $out_file specifies a path/filename to save the output to.

        $sbO->render_all('mystylesheet.xsl', '-');

or

        $sbO->render_all('mystylesheet.xsl', 'output.html');

or

        my $out = $sbO->render_all('mystylesheet.xsl');

get_index()

This method simply reads in the bb.idx file entry by entry (line by line), and returns it as an array. This is a useful method for doing custom things with the blogbase.

        my @bI = $sB->get_index();

AUTHOR

J. A. Robson, <gilad@arbingersys.com>

SEE ALSO

XML, XSLT, Regular Expressions, XML::XSL