show conversation as a hierarchical list

actions/conversation.php

@@ -11,7 +11,7 @@
  * @link     http://laconi.ca/
  *
  * Laconica - a distributed open-source microblogging tool
- * Copyright (C) 2008, Controlez-Vous, Inc.
+ * Copyright (C) 2009, Control Yourself, Inc.
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Affero General Public License as published by
@@ -31,7 +31,7 @@ if (!defined('LACONICA')) {
     exit(1);
 }
 
-require_once(INSTALLDIR.'/lib/noticelist.php');
+require_once INSTALLDIR.'/lib/noticelist.php';
 
 /**
  * Conversation tree in the browser
@@ -45,7 +45,7 @@ require_once(INSTALLDIR.'/lib/noticelist.php');
 
 class ConversationAction extends Action
 {
-    var $id = null;
+    var $id   = null;
     var $page = null;
 
     /**
@@ -70,24 +70,47 @@ class ConversationAction extends Action
         return true;
     }
 
+    /**
+     * Handle the action
+     *
+     * @param array $args Web and URL arguments
+     *
+     * @return void
+     */
+
     function handle($args)
     {
         parent::handle($args);
         $this->showPage();
     }
 
+    /**
+     * Returns the page title
+     *
+     * @return string page title
+     */
+
     function title()
     {
         return _("Conversation");
     }
 
+    /**
+     * Show content.
+     *
+     * Display a hierarchical unordered list in the content area.
+     * Uses ConversationTree to do most of the heavy lifting.
+     *
+     * @return void
+     */
+
     function showContent()
     {
         // FIXME this needs to be a tree, not a list
 
         $qry = 'SELECT * FROM notice WHERE conversation = %s ';
 
-        $offset = ($this->page-1)*NOTICES_PER_PAGE;
+        $offset = ($this->page-1) * NOTICES_PER_PAGE;
         $limit  = NOTICES_PER_PAGE + 1;
 
         $txt = sprintf($qry, $this->id);
@@ -106,24 +129,47 @@ class ConversationAction extends Action
 
 }
 
+/**
+ * Conversation tree
+ *
+ * The widget class for displaying a hierarchical list of notices.
+ *
+ * @category Widget
+ * @package  Laconica
+ * @author   Evan Prodromou <evan@controlyourself.ca>
+ * @license  http://www.fsf.org/licensing/licenses/agpl.html AGPLv3
+ * @link     http://laconi.ca/
+ */
+
 class ConversationTree extends NoticeList
 {
-    var $tree = null;
+    var $tree  = null;
     var $table = null;
 
+    /**
+     * Show the tree of notices
+     *
+     * @return void
+     */
+
     function show()
     {
         $cnt = 0;
 
-        $this->tree = array();
-        $table = array();
+        $this->tree  = array();
+        $this->table = array();
 
         while ($this->notice->fetch()) {
+
             $cnt++;
-            $this->table[$this->notice->id] = clone($this->notice);
+
+            $id     = $this->notice->id;
+            $notice = clone($this->notice);
+
+            $this->table[$id] = $notice;
+
             if (is_null($notice->reply_to)) {
-                // We assume no notice has -1 ID
-                $this->tree[-1] = array($notice->id);
+                $this->tree['root'] = array($notice->id);
             } else if (array_key_exists($notice->reply_to, $this->tree)) {
                 $this->tree[$notice->reply_to][] = $notice->id;
             } else {
@@ -135,8 +181,9 @@ class ConversationTree extends NoticeList
         $this->out->element('h2', null, _('Notices'));
         $this->out->elementStart('ul', array('class' => 'notices'));
 
-        if (array_key_exists(-1, $this->tree)) {
-            $this->showNoticePlus($this->tree[-1][0]);
+        if (array_key_exists('root', $this->tree)) {
+            $rootid = $this->tree['root'][0];
+            $this->showNoticePlus($rootid);
         }
 
         $this->out->elementEnd('ul');
@@ -145,12 +192,18 @@ class ConversationTree extends NoticeList
         return $cnt;
     }
 
+    /**
+     * Shows a notice plus its list of children.
+     *
+     * @param integer $id ID of the notice to show
+     *
+     * @return void
+     */
+
     function showNoticePlus($id)
     {
         $notice = $this->table[$id];
 
-        print_r($notice);
-
         // We take responsibility for doing the li
 
         $this->out->elementStart('li', array('class' => 'hentry notice',
@@ -174,26 +227,72 @@ class ConversationTree extends NoticeList
         $this->out->elementEnd('li');
     }
 
+    /**
+     * Override parent class to return our preferred item.
+     *
+     * @param Notice $notice Notice to display
+     *
+     * @return NoticeListItem a list item to show
+     */
+
     function newListItem($notice)
     {
         return new ConversationTreeItem($notice, $this->out);
     }
 }
 
+/**
+ * Conversation tree list item
+ *
+ * Special class of NoticeListItem for use inside conversation trees.
+ *
+ * @category Widget
+ * @package  Laconica
+ * @author   Evan Prodromou <evan@controlyourself.ca>
+ * @license  http://www.fsf.org/licensing/licenses/agpl.html AGPLv3
+ * @link     http://laconi.ca/
+ */
+
 class ConversationTreeItem extends NoticeListItem
 {
+    /**
+     * start a single notice.
+     *
+     * The default creates the <li>; we skip, since the ConversationTree
+     * takes care of that.
+     *
+     * @return void
+     */
+
     function showStart()
     {
-        // skip; ConversationTree draws the list
+        return;
     }
 
+    /**
+     * finish the notice
+     *
+     * The default closes the <li>; we skip, since the ConversationTree
+     * takes care of that.
+     *
+     * @return void
+     */
+
     function showEnd()
     {
-        // skip; ConversationTree draws the list
+        return;
     }
 
+    /**
+     * show link to notice conversation page
+     *
+     * Since we're only used on the conversation page, we skip this
+     *
+     * @return void
+     */
+
     function showContext()
     {
-        // skip; this _is_ the context!
+        return;
     }
 }