/ 
AxKit-App-TABOO-0.52
River stage zero No dependents
/ AxKit::App::TABOO::Provider::News

NAME

AxKit::App::TABOO::Provider::News - News Provider for TABOO

SYNOPSIS

In the Apache config:

<LocationMatch ^/news/(.+)/(.+)/($|comment)>
      PerlHandler AxKit
      AxContentProvider AxKit::App::TABOO::Provider::News
</LocationMatch>

Please note that this should go after the configuration of the AxKit::App::TABOO::Provider::NewsList Provider if you are using both.

DESCRIPTION

This is a Provider, it implements the AxKit Provider API, and therefore contains no method that anybody should use for anything. For that reason, this documentation deals with what you should expect to be returned for different URIs.

The News articles that are managed with this provider are posts that may have been submitted by users of the site, reviewed by an editor and posted. It will consist of the editor-approved content, called the Story, and content provided as responses by site users, called Comments.

In accordance with the TABOO philosophy, it interacts with Data objects, that are Perl objects responsible for retrieving data from a data storage, make up sensible data structures, return XML markup, etc.

URI USAGE

The URI in the News Provider consists of several parts that is parsed by the Provider and used directly to construct the objects that contain the data we wish to send to the user.

The URIs currently begin with /news. This should be made customizable in the future, but currently needs to be hardcoded in the httpd.conf and is hardcoded in the Provider itself.

The next part of the URI is the section. The section is coded as a simple word in the URI and use to identify the section for the story, as detailed in AxKit::App::TABOO::Data::Story.

Then comes the story name, used to identify the story, also as detailed in AxKit::App::TABOO::Data::Story.

If we take features to be our section and coolhack to be the name of the story, we can now construct the minimal URI that will make the News Provider return something (as presently implemented): /news/features/coolhack/. This will return markup containing the Story only, no comments.

If we want to see the comments, we should append comment/. The URI /news/features/coolhack/comment/ (remember the trailing slash) will give us the whole story but only the headings of comments, that is, the title and author fullname.

At this point, one can append the key words all or thread. Neither of this may have a trailing slash. E.g. /news/features/coolhack/comment/all will return everything that is known for this story, the full story and all the comments. The example /news/features/coolhack/comment/thread, OTOH will return all the comments, but only the title (and things like timestamp), of the story itself. The all keyword can only be used in this context.

We may now use commentpaths to access specific comments. See AxKit::App::TABOO::Data::Comment for details on commentpaths. The short story is that commentpaths is a series of usernames, separated by slashes, and not just any user name, but the usernames of those who posted the comments. For example, if user foo posts a comment, that comment will have commentpath /foo and if bar responds to it, that comment will have commentpath /foo/bar. No trailing slash. If you want bar's latest comment the URI of that comment is /news/features/coolhack/comment/foo/bar. That is, you get the title of the story, but you also get a nested list of all the comments containing only title and author name.

Finally, you can append /thread behind any commentpath, and you get the full text comment and every response to that comment, in addition to the title of the story. To get both foo and bar's comments, nicely nested, you want /news/features/coolhack/comment/foo/thread

So, you get nice, human understandable URIs for everything. That's actually one of the main design aims of TABOO.

You don't get as fine-grained control of which comments you'd like to see like on Slashdot, but then, not many sites attracts as many comments as Slashdot.

RETURNED XML

It is the Data object's task to return XML marking up the data contained in the object. For the most part, the element name is the same as the field name used in the data storage, see the DATA STORAGE section for AxKit::App::TABOO::Data::Story and AxKit::App::TABOO::Data::Comment. What elements are used is most interesting for an XSLT developer, who might want to look at the output the Provider gives.

There are a few things worth noting:

  • User information can be found within user or submitter elements.

  • Every reply, even the first root responses will be found within reply elements. Furthermore, a reply to a comment will appear within the reply element of the parent comment.

  • The nested lists of comment titles will appear exactly like the full comments, except that the fields with no content are represented with empty elements, and the whole thing will be enclosed in a commentlist element.

TODO

Since every resource comes with a lasttimestamp, it should be relatively simple to implement mtime better than it is now, but the question is if all code updates lasttimestamp reliably enough...

The get_styles method is implemented, but just to "make it work right now". It needs to take many conditions into account, such as the mime type requested by the user. It is even possible it should be going into a parent class.

Due to AxKit Bug 8032, Exceptions can't be thrown whereever one likes, but this is a problem that needs to be corrected in AxKit first.

BUGS

Well, it is a beta, so there can be bugs...

SEE ALSO

AxKit::App::TABOO::Provider::NewsList.

FORMALITIES

See AxKit::App::TABOO.