Zine Data Structure

E-Zines are comprised of articles organized into hierarchical trees. Each article has a class, which determines where in the tree it is expected to appear. Each article also has a type, which is more specific than the class for zines. (For articles, comments, and attachments, the type and class are equivalent.) The zine type determines general formatting and indexing rules for associated articles. The various types are:

Type	Class	Notes
e-zine	zine	Holds articles by various authors, which eventually expire into the archives as they are replaced by newer articles.
book	zine	Holds an ordered set of articles that collectively comprise a single work. Articles do not expire.
forum	zine	Holds ongoing commentary from the readership.
news	zine	Holds articles which eventually expire into the archives as they are replaced by newer articles. Authors are usually not noted.
blog	zine	Holds articles by a single author, which eventually expire into the archives. Analogous to a magazine column, or an online diary.
wiki	zine	Holds articles by various authors, which can be cross-linked, and which the readers can contribute to.
photoblog	zine	Similar to a blog, but emphasizes the image content over the text content.
regular article	article	These are the individual stories/posts that readers are consuming.
comment	comment	Readers can append their own thoughts to particular articles or forums.
attachment	attachment	These are images or other files that are connected to zines, articles, or comments.

Article Trees

The rules for how articles in the overall tree are allowed to nest under each other are:

zines may only nest under zines
regular articles may nest under zines or other regular articles
comments may nest under articles or comments; comments may also nest under forums
attachments may nest under any type

It may be possible to configure article relationships to break these rules, but in that case there is no assurance of the misconfigured articles being found and displayed by the system.

Each article has a parent article, which is the next article higher in the tree. To build a tree object from an array of articles, use this:

my $tree = new ExSite::Tree(
                            "article_id",    # primary key
			    "parent_id",     # parent key
			    @articles        # tree nodes
			    );

In principle the entire tree can be defined and constructed using only the parent reference. However, this makes for inefficient and recursive queries to retrieve the data needed to build the tree. To allow for simpler and more efficient queries, we also track each article's thread and reference.

The thread is the highest-level article of the same class. If the current article is the highest-level article of the same class, then the thread is not set (ie. it is set to 0).

The reference is used to group related articles. For comments and articles, the reference is the lowest-level article of a different class above it in the tree. A record with no reference is at the top level of the tree.

Attachments have the same thread and reference as the article they are attached to. This makes it easier to select article and their attachments together in a single query.

For example, consider a single branch of the article tree that nests as follows:

Zine Z1

Zine Z2

Article A1

Article A2

Comment C1

Comment C2

Comment C3

Attachment Att1

The following relationships hold true:

Article	Parent	Thread	Reference
Z1	n/a	n/a	n/a
Z2	Z1	Z1	Z1
A1	Z2	n/a	Z2
A2	A1	A1	Z2
C1	A1	n/a	A2
C2	C1	C1	A2
C3	C2	C1	A2
Att1	C3	n/a	A2

Examples

To build a complete index of articles and their comments under a particular zine, while ignoring all other zines, select all records whose reference points to the zine of interest:

# construct a tree of everything in Z2
my @articles = $db->fetch_match("article",{reference=>$z2});
my $tree = new ExSite::Tree("article_id","parent_id",@articles);

To fetch a list of threads (ie. top-level comments) in a forum, select all comments whose reference is the forum, and whose thread is not set:

my @articles = $db->fetch_match("article",{type=>"comment",reference=>$forum_id,thread=>0});

To fetch a complete thread from a discussion, select all articles of a given thread:

# fetches all articles under the top-level article
my @articles = $db->fetch_match("article",{type=>"comment",thread=>$thread_id});
# fetches all articles including the top-level article
my @articles = $db->fetch_match("article","type=\"comment\" and (article_id=$thread_id or thread=$thread_id");
my $tree = new ExSite::Tree("article_id","parent_id",@articles);