mozdev.org

ForumZilla   boxes decorative element

resources Home | FAQ | Source Code | Known Bugs | Enter New Bug Report

ForumZilla Server-Side How-To

ForumZilla Server-Side How-To

Overview
About RDF
About RSS
Forum Description File
Story Description File
ForumZilla Support in Slash
ForumZilla Support in Scoop
MIME type
Troubleshooting


Overview

Forumzilla is a Mozilla XUL-based application that provides a three-paned Usenet newsreader-like interface to web discussion forums. It displays stories and comments from forums that publish information about their content in ForumZilla's Resource Description Framework (RDF) schema.

ForumZilla also displays stories from forums that publish information about their stories in the RDF Site Summary (RSS) 1.0 format, which is another RDF schema. RSS can be combined with the ForumZilla schema to create a hybrid RDF document that can be read by both ForumZilla and other applications that only understand RSS.

To fully support ForumZilla, a web discussion forum must publish a forum description file (in either the ForumZilla or RSS schemas), a story description file for each story listed in the forum description file, and a page for each story and comment that displays the content of the story or comment.

The content pages can be written in any format displayable in the Mozilla browser, although typically they will be HTML. These pages can be formatted especially for ForumZilla or can be the same pages users see when they view the forum via a web browser. Forums can make available the URL of an ad that will be displayed at the top of the ForumZilla application window, and they can also specify the location of a vertical navigation bar that will appear in ForumZilla's window.


About RDF

RDF is an XML tag language specifically designed for publishing meta-data. Meta-data are information about other information. In a filesystem, for example, the name of a file and the date it was created are meta-data about that file, while the contents of the file are the data.

For a web discussion forum, meta-data includes, among other things, the author, title, and publication date of stories and the author, subject, and moderation score of comments.

While RDF provides the general structure for describing meta-data, RDF is most useful when extended with schemas, which are sets of tags designed to describe particular kinds of objects. The ForumZilla schema, for example, contains tags like "forum", "articles", "title", and "author" that are useful in describing the stories and comments in a forum.


About RSS

RSS is an RDF schema for describing web sites whose content can be organized into "channels" of "items". It is well suited for the description of web discussion forums in which each forum ("channel") contains a sequence of stories ("items").

Nevertheless, RSS is--by design--both a simple and a generic schema that does not contain tags for publishing more detailed information about items like a threaded list of comments. RSS encourages extensibility by permitting additional RDF schemas (called RSS modules) to be intermixed with standard RSS to produce a richer description of a web site than standard RSS alone can provide.

ForumZilla currently supports the displaying of forums and their stories using RSS, and it is possible to add ForumZilla schema descriptions of stories and their comments to RSS descriptions of a forum and its stories in order to add full ForumZilla functionality to a forum that publishes its stories in RSS 1.0 format.

RSS is a powerful and well-designed standard for publishing meta-data. In the future, the ForumZilla schema will move towards becoming an RSS module. To publish using a hybrid RSS/ForumZilla schema today, create a standard RSS description of your forum; add the ForumZilla schema namespace below to the rdf:RDF tag for the forum; and add an fz:description tag to each item description that points to the item's story description file. Here is a snippet of an RSS file with these changes highlighted in red:


<?xml version="1.0" encoding="UTF-8"?>

<rdf:RDF
 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 xmlns="http://purl.org/rss/1.0/"
 xmlns:fz="http://www.zapogee.com/rdf/forumzilla/"
>

  ...

  <item rdf:about="http://www.fz.com/?sid=9876&amp;op=display">
    <title>ForumZilla 0.2.6 Released</title>
    <link>http://www.fz.com/?sid=9876&amp;op=display</link>
    <fz:description rdf:resource="http://www.fz.com/?sid=9876&amp;op=display"/>
  </item>

  ...


Forum Description File

A forum description file describes a forum and its stories. It includes information such as the forum title, ad URL, navigation URL, and a list of stories along with links to their story description files. Here is a sample forum description file:


<?xml version="1.0" encoding="UTF-8"?>

<rdf:RDF 
 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 xmlns:fz="http://www.zapogee.com/rdf/forumzilla/"
>

  <fz:forum rdf:about="http://www.fz.com/">
    <fz:title>The Forumzilla Forum</fz:title>
    <fz:navigation rdf:resource="http://www.fz.com/navigation.html" />
    <fz:ads rdf:resource="http://www.fz.com/ads.html" />

    <fz:articles>
      <rdf:Seq>
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;op=display" />
        <rdf:li rdf:resource="http://www.fz.com/?sid=1234&amp;op=display" />
        <rdf:li rdf:resource="http://www.fz.com/?sid=5674&amp;op=display" />
        <rdf:li rdf:resource="http://www.fz.com/?sid=9393&amp;op=display" />
      </rdf:Seq>
    </fz:articles>

  </fz:forum>

  <fz:story rdf:about="http://www.fz.com/?sid=9876&amp;op=display">
    <fz:title>Something happens!</fz:title>
    <fz:description rdf:resource="http://www.fz.com/?sid=9876&amp;op=describe"/>
    <fz:date>2000-10-05T10:20:47Z</fz:date>
    <fz:lastcommentdate>2000-10-06T23:30:59Z</fz:lastcommentdate>
    <fz:numcomments>5</fz:numcomments>
  </fz:story>

  <fz:story rdf:about="http://www.fz.com/?sid=1234&amp;op=display">
    <fz:title>Something else happens!</fz:title>
    <fz:description rdf:resource="http://www.fz.com/?sid=1234&amp;op=describe"/>
    <fz:date>2000-10-05T13:27:44Z</fz:date>
    <fz:lastcommentdate>2000-10-05T19:31:53Z</fz:lastcommentdate>
    <fz:numcomments>2</fz:numcomments>
  </fz:story>

  <fz:story rdf:about="http://www.fz.com/?sid=5674&amp;op=display">
    <fz:title>A third thing happens!</fz:title>
    <fz:description rdf:resource="http://www.fz.com/?sid=5674&amp;op=describe"/>
    <fz:date>2000-10-06T01:10:01Z</fz:date>
    <fz:lastcommentdate>2000-10-08T23:32:23Z</fz:lastcommentdate>
    <fz:numcomments>17</fz:numcomments>
  </fz:story>

  <fz:story rdf:about="http://www.fz.com/?sid=9393&amp;op=display">
    <fz:title>Can't stop things from happening.</fz:title>
    <fz:description rdf:resource="http://www.fz.com/?sid=9393&amp;op=describe"/>
    <fz:date>2000-10-06T09:33:42Z</fz:date>
    <fz:lastcommentdate>2000-10-07T11:22:54Z</fz:lastcommentdate>
    <fz:numcomments>8</fz:numcomments>
  </fz:story>

</rdf:RDF>

?xml

The ?xml tag is optional. If present, it must appear at the top of the file. It identifies the file as an XML document and specifies the character encoding.

rdf:RDF

The rdf:RDF tag is required and must appear at the top of the file underneath the ?xml tag (if present). It encloses the entire document and identifies it as an RDF file much like the HTML tag identifies an HTML file. The tag should appear as shown along with its two attributes, xmlns:rdf and xmlns:fz, which specify RDF schemas that will appear in the document. The first attribute specifies the generic RDF schema while the second one specifies the ForumZilla schema.

fz:forum

The fz:forum tag is required. The value of the rdf:about attribute for the tag should be the URL of the forum's home page or another URL that uniquely identifies the forum. (Note: This tag replaces the generic rdf:description tag for the forum in previous versions of the ForumZilla schema.)

fz:title

The fz:title tag is required and must appear within the fz:forum tag as well as within each fz:story tag. The value of the tag should be the title of the forum or story. This name will be displayed in the ForumZilla interface in the list of forums to which the user is subscribed and in the list of stories for each subscribed forum.

fz:navigation

The fz:navigation tag is optional. If included, the value of the rdf:resource attribute for the tag should be the URL of an HTML page that displays a vertical navigation bar for the forum. This page will be displayed in a section of the ForumZilla interface which can be minimized and maximized. (Note: In the future this mechanism may be replaced with a menu on the ForumZilla menu bar that contains navigation options for each forum as it is currently being viewed.)

fz:ads

The fz:ads tag is optional. If included, the value of the rdf:resource attribute for the tag should be the URL of an HTML page that displays a standard 468x60 banner ad for the forum. This page will be displayed in a section of the ForumZilla interface which cannot be minimized or otherwise hidden and which appears and disappears automatically as the user moves between forums that run ads and those that do not. The ad page will be reloaded each time a user selects a new story or comment to read.

fz:articles

The fz:articles tag is required and must appear within the fz:forum tag. It must contain an RDF sequence which consists of opening and closing rdf:Seq tags and zero or more rdf:li tags, one for each story in the forum. The rdf:resource attribute of each rdf:li tag should contain a URL to the story's content page. In addition, this link must match the URL in the rdf:about attribute of the story's fz:story tag. (Note: For consistency with the terminology used by the majority of web discussion forums, this name of this tag may change in the future to fz:stories.)

fz:story

The fz:story tag must appear once for each story in the forum. The rdf:about attribute of the tag should contain a URL to the story's content page. (Note: This tag replaces the generic rdf:description tag for the story in previous versions of the ForumZilla schema.)

fz:description

The fz:description tag is required and must appear within each fz:story tag. It should contain the URL of the story's story description file. (Note: In previous versions of the ForumZilla schema there was also an fz:description tag within the equivalent of the fz:forum tag. This tag is no longer necessary and will be ignored if present.)

fz:date

The fz:date tag is optional and must appear within an fz:story tag. The value of the tag should be the date and time the story was posted. The value must be in the date format specified in the W3C Note on Date and Time Formats.

fz:lastcommentdate

The fz:lastcommentdate tag is optional and must appear within an fz:story tag. The value of the tag should be the date and time the most recent comment on the story was posted. This column is used by ForumZilla to determine whether or not there are new comments since the last time the user viewed the story. The value must be in the date format specified in the W3C Note on Date and Time Formats.

fz:numcomments

The fz:numcomments tag is optional and must appear within an fz:story tag. The value of the tag should be the number of comments posted on the story. This column is used by ForumZilla to determine whether or not there are new comments since the last time the user viewed the story.


Story Description File

A story description file describes a story and its comments. It includes information such as a list of comments for the story and the comments' titles, authors, and moderation scores along with a list of the story's and each comments' replies. Here is a sample story description file:


<?xml version="1.0" encoding="UTF-8"?>

<rdf:RDF
 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 xmlns:fz="http://www.zapogee.com/rdf/forumzilla/"
>

  <fz:story rdf:about="http://www.fz.com/?sid=9876&amp;op=display">
    <fz:comments>
      <rdf:Seq>
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=1" />
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=2" />
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=3" />
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=4" />
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=5" />
      </rdf:Seq>
    </fz:comments>
    <fz:replies>
      <rdf:Seq>
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=1" />
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=5" />
      </rdf:Seq>
    </fz:replies>
  </fz:story>

  <fz:comment rdf:about="http://www.fz.com/?sid=9876&amp;cid=1">
    <fz:title>First post!</fz:title>
    <fz:author>nobody</fz:author>
    <fz:datetime>2000-10-05T10:24:04Z</fz:datetime>
    <fz:score>(Score: -1; beat-me-to-the-punch)</fz:score>
    <fz:points>-1</fz:points>
    <fz:replies>
      <rdf:Seq>
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=2" />
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=4" />
      </rdf:Seq>
    </fz:replies>
  </fz:comment>

  <fz:comment rdf:about="http://www.fz.com/?sid=9876&amp;cid=2">
    <fz:title>Re:First post!</fz:title>
    <fz:author>somebody</fz:author>
    <fz:datetime>2000-10-05T10:25:56Z</fz:datetime>
    <fz:score>(Score: 1)</fz:score>
    <fz:points>1</fz:points>
    <fz:replies>
      <rdf:Seq>
        <rdf:li rdf:resource="http://www.fz.com/?sid=9876&amp;cid=3" />
      </rdf:Seq>
    </fz:replies>
  </fz:comment>

  <fz:comment rdf:about="http://www.fz.com/?sid=9876&amp;cid=3">
    <fz:title>Re:First post!</fz:title>
    <fz:author>nobody</fz:author>
    <fz:datetime>2000-10-05T10:37:01Z</fz:datetime>
    <fz:score>(Score: 1)</fz:score>
    <fz:points>1</fz:points>
  </fz:comment>

  <fz:comment rdf:about="http://www.fz.com/?sid=9876&amp;cid=4">
    <fz:title>Stop spamming with first post!</fz:title>
    <fz:author>anybody</fz:author>
    <fz:datetime>2000-10-06T15:22:30Z</fz:datetime>
    <fz:score>(Score: 3)</fz:score>
    <fz:points>3</fz:points>
  </fz:comment>

  <fz:comment rdf:about="http://www.fz.com/?sid=9876&amp;cid=5">
    <fz:title>Another top level post!</fz:title>
    <fz:author>everybody</fz:author>
    <fz:datetime>2000-10-06T23:30:59Z</fz:datetime>
    <fz:score>(Score: 2)</fz:score>
    <fz:points>2</fz:points>
  </fz:comment>

</rdf:RDF>

?xml

The ?xml tag is optional. If present, it must appear at the top of the file. It identifies the file as an XML document and specifies the character encoding.

rdf:RDF

The rdf:RDF tag is required and must appear at the top of the file underneath the ?xml tag (if present). It encloses the entire document and identifies it as an RDF file much like the HTML tag identifies an HTML file. The tag should appear as shown along with its two attributes, xmlns:rdf and xmlns:fz, which specify RDF schemas that will appear in the document. The first attribute specifies the generic RDF schema while the second one specifies the ForumZilla schema.

fz:story

The fz:story tag is required and may appear anywhere within the rdf:RDF tag. The value of the rdf:about attribute for the tag should be the URL of the story's content page. This URL must be the same as the one given for the story in the rdf:about attribute to the fz:story tag in the forum description file.

fz:comments

The fz:comments tag is required and must appear within the fz:story tag. It must contain an RDF sequence which consists of opening and closing rdf:Seq tags and zero or more rdf:li tags, one for each comment on the story. The rdf:resource attribute of each rdf:li tag should contain the URL to the comment's content page. This link must match the URL in the rdf:about attribute of the comment's fz:comment tag.

fz:replies

The fz:replies tag is required and must appear within the fz:story tag. It must contain an RDF sequence which consists of opening and closing rdf:Seq tags and zero or more rdf:li tags, one for each comment which is a direct reply to the story (i.e. not a reply to another comment). The rdf:resource attribute of each rdf:li tag should contain the URL to the comment's content page. This link must match the URL in the rdf:about attribute of the comment's fz:comment tag.

fz:comment

The fz:comment tag must appear once for each comment on the story and may appear anywhere within the rdf:RDF tag. The rdf:about attribute of the tag should contain the URL to the comment's content page. (Note: This tag replaces the generic rdf:description tag for the comment in previous versions of the ForumZilla schema.)

fz:title

The fz:title tag is optional but strongly recommended and must appear within an fz:comment tag. The value of the tag should be the title/subject of the comment. This name will be displayed in the ForumZilla interface under the "Subject" column of the comment tree.

fz:author

The fz:author tag is optional but strongly recommended and must appear within an fz:comment tag. The value of the tag should be the name or user ID of the author of the comment. This value will be displayed in the ForumZilla interface under the "Author" column of the comment tree.

fz:datetime

The fz:datetime tag is optional but strongly recommended and must appear within an fz:comment tag. The value of the tag should be the date and time the comment was posted. This value will be displayed in the ForumZilla interface under the "Date" column of the comment tree. While this value can be any text string, the date format specified in the W3C Note on Date and Time Formats is highly recommended both for compatibility with RSS and to make it possible to accurately sort comments by date. (Note: For consistency the name of this tag may change in the future to fz:date.)

fz:score

The fz:score tag is optional and must appear within an fz:comment tag. The value of the tag should be the rating the comment has received via the forum's moderation system (if any). The value will be displayed in the ForumZilla interface under the "Score" column of the comment tree and can be any text string.

fz:points

The fz:points tag is optional and must appear within an fz:comment tag. The value of the tag should be a numeric representation of the rating the comment has received via the forum's moderation system (if any). Higher ratings should result in greater numeric values. This value will not be displayed in the ForumZilla interface but will be used to sort the comment tree when the user sorts the tree by "Score".


ForumZilla Support in Slash

You can add ForumZilla support to Slashcode version 1.0.9 by adding fz.pl v0.1.6 to your script directory. Locate your forum description file at the following URL:

http://yoursite.com/fz.pl?op=forumdesc

Work is underway to provide ForumZilla support in Slashcode 2.0.


ForumZilla Support in Scoop

ForumZilla support is built in to Scoop 0.6 (not including Scoop 0.6pre2 and earlier releases). Locate your forum description file at the following URL:

http://yoursite.com/?op=fz


MIME Type

Forum and story description files should be returned by the server as MIME type "text/xml".


Troubleshooting

If you are having problems viewing your forum with ForumZilla, read over the following tips and make sure your description files do not suffer from the common problems listed here.

MIME Type

Description files should be returned by the server as MIME type "text/xml". Apache is not configured by default to return .rdf files with this MIME type, so if your description files are static RDF files in the filesystem (rather than being dynamically generated by a script), then you must configure Apache to return the correct MIME type for these files. Add the following line to your Apache configuration file (probably httpd.conf) and restart Apache to fix this problem:

    AddType text/xml rdf

If your description files are dynamically generated by a script, make sure you set their MIME type to "text/xml".

Case Sensitivity

RDF is case-sensitive, so all tags must match in upper and lower case exactly as shown in the examples in this document. Make sure you aren't using the wrong case or mixing cases somewhere.

Ampersands and Brackets

XML requires that you encode ampersands and tag brackets in text strings. Make sure you encode these characters by replacing them with their entity equivalents (& -> &amp;, < -> &lt;, > -> &gt;). Ampersands, in particular, are common in URLs that appear within description files.


Version 1.1 draft 1. Last modified 2001 March 27 by Myk Melez.

The forumzilla project can be contacted through the mailing list or the member list.
Copyright © 2000-2018. All rights reserved. Terms of Use & Privacy Policy.