[phpslash-users] API stuff

[Lauren M. <in...@ca...>]

--
I sent this yesterday, but it doesn't seem to have gone through.  If it
makes it to the list twice, my apologies.
--

Hello,

I've been othewise occupied for the last little bit, but would like to
pickup
the beginnings of API discussion from two weeks ago.  Let me tell you a
bit
of where I'm comming from.  Last winter I was working on a project that
I
wanted to include a stories sort of section but because of the design I
wanted it to be quite modular and all of the output needed to be
returned to
the calling function rather than printed directly so that it could be
filtered.  I put together a pretty rough hack using phpSlash as the
basis but
it never quite got finished.  I revisited it last month and decided to
begin
converting my hack into classes to try to tidy it up and actually make
it
more reusable.  So, I'm not using phpSlash on my site, but if what I
bang on
could be used in phpSlash then it would be good.

Here are design goals I see:
    - each class includes all access to the data set it represents,
display,
query, edit, append ...
    - nothing directly printed, always returned from method
    - only HTML structure tags used in output - ie: rather then FONT
tags,
mark tag classes and use CSS for formatting
    - use libphp for database access and permissions

Here is what I have so far.  This doesn't have any provision for
entering
data yet, or any permissoins.  Also, this isn't finished by any means,
comments invited.
A side note:  I've called it a 'storyboard' rather than 'weblog' because
I
wasn't familliar with the term weblog.

class library_storyboard_stories {
    /* must be set */
    var $database;        // database name to use
    var $tableprefix;     // prefix for table names, allows for more
than one
seperate storyboards
    var $modulename;      // this name is specific to my application,
but is
essentially the base
                          //   directory to mark URL's relative to.
    var $topicimagesdir;  // location of topic images
    var $count_max = 10;  // max number of stories to show
    var $mode = "thread"; // display mode
    /* optionally set */
    var $section;         // section to show
    var $date;            // date of articles to show
    var $sid;             // sid to show
    /* private */
    var $stories_array = array();    // array to locally handle stories
from
database
    var $stories_array_ptr;          // pointer to current story in
processing
...

Methods:
    query()
        Queries stories based on $section, $date, $sid, $count_max and
copying data into $stories_array
        Returns true if stories were found.
    output()
        Umbrella function that calls displayStory and uses the comments
class

        Returns story(ies) and comments from $stories_array
    /*private*/
    displayStory($sid)
        Returns a single story in HTML
    commentsbar()
        Returns the [More] [ Comments ] line
    navbar()
        Returns the previous | Reply | Flattened | next line
    relatedlinks()
        Returns related links.. don't think this is working properly
}

class library_storyboard_comments {
    /* must be set */
    var $database;        // database name to use
    var $tableprefix;     // prefix for table names, allows for more
than one
seperate storyboards
    var $modulename;      // this name is specific to my application,
but is
essentially the base
                          //   directory to mark URL's relative to.
    var $mode = "thread"  // mode to display
    var $sid;             // story that comments refer to.
    /* optionally set */
    var $pid;             // pid to print
    /*private*/
    var $comments_array;     // local store for comments from database
    var $children;           // an array indexing children by their
parents
(see index_children)
    var $mode_comment_prefix;    // these four variables are used for
variations between modes to try to
    var $mode_comment_function;  //   consolodate the comment formatting
into
one routine
    var $mode_child_before;      //
    var $mode_child_after;       //
...
Methods
    query()
        Queries based on sid and puts data in $comments_array
        Returns true if there are comments
    output()
        Umbrella function that sets the mode_* variables based on $mode
and
calls output_children_of()
        Returns comments from $comments_array in HTML
    /*private*/
    index_children()
        Creates an array lists of child cid's keyed by their pid in
$children

        Returns nothing
    output_children_of($pid)
        Recursive function
        Calls output_ThreadComment, output_CommentLink or output_Comment
based on mode settings
        Returns HTML structured comments that are children of $pid.
    output_ThreadComment ($cid)
        Calls output_Comment the first time through, output_CommentLink
the
remainder
        Returns single HTML structured comment
    output_Comment ($cid)
        Returns complete single HTML structured comment
    output_CommentLink ($cid)
        Returns HTML structured link to comment.
}

Sorry for the length, thanks for reading.

Lauren Matheson.