syntax-classes.php

<?php
/**
 *
 * Object-Oriented stuff for Plans!
 *
 * Defines a set of objects that are constructed by pages and then passed
 * to the interface, where they are turned into HTML or whatever else.
 *
 * Please realize that these objects can and should be extended as the need arises.
 * What is here is not meant to be a comprehensive set.
 *
 * @package Interfaces
 */
/**
 * This is an entire page of content generated by plans. Passed whole to the
 * interface for printing.
 */
class PlansPage {
    /**
     * What category this page belongs to
     * @var string
     */
    public $group;
    /**
     * A unique identifier for this page
     * @var string
     */
    public $identifier;
    /**
     * A title for the page
     * @var string
     */
    public $title = PLANSVNAME;
    /**
     * The main panel that contains all the links, autoreads, etc
     * @var MainPanel
     */
    public $mainpanel;
    /**
     * An array of Widgets, the contents of this page
     * @var array
     */
    public $contents;
    /**
     * The footer of the page
     * @var Footer
     */
    public $footer;
    /**
     * CSS stylesheets to be used
     * @var array an array of URLs to stylesheets
     */
    public $stylesheets;
    /**
     * Javascript files to be used
     * @var array an array of URLs to script files
     */
    public $scripts;
    /**
     * The URL of this page
     * @var string
     */
    public $url;
    /**
     * The current priority level of the autoread list
     * @var int
     */
    public $autoreadpriority;
    /**
     * @param string $group the group this page belongs to
     * @param int $id a unique identifier for this page
     * @param string a title for the page
     * @param string the URL of this page
     */
    function __construct($group, $id, $title, $url) {
        $this->group = $group;
        $this->identifier = $id;
        $this->title = $title;
        $this->url = $url;
        $this->contents = array();
        $this->stylesheets = array();
        $this->scripts = array();
    }
    /**
     * Add a widget to the page.
     * @param Widget $widget the widget to be added.
     */
    public function append(Widget $widget) {
        // If it's a form, we can set some defaults
        if ($widget instanceof Form) {
            if ($widget->action == null) $widget->action = $this->url;
            if ($widget->method == null) $widget->method = 'post';
        }
        // Add it to the list
        $this->contents[] = $widget;
    }
}
/**
 * The main panel of links for plans. Includes the finger box, links to different
 * parts of Plans, and the autoread lists.
 */
class MainPanel {
    public $identifier = 'mainpanel';
    /**
     * Link back to the home page
     * @var Hyperlink;
     */
    public $linkhome;
    /**
     * Gives the Finger (or Read) box
     * @var Form
     */
    public $fingerbox;
    /**
     * The user's navigation links
     * @var WidgetList
     */
    public $links;
    /**
     * A list of AutoRead objects
     * @var WidgetList
     */
    public $autoreads;
}
/**
 * The footer found on most pages.  Currently may contain the
 * "do you read?" thing and legalese stuff.
 */
class Footer {
    /**
     * A link to a recently updated plan
     * @var PlanLink
     */
    public $doyouread;
    /**
     * Whatever legalese text goes at the bottom
     * @var RegularText
     */
    public $legal;
}
/**
 * General-purpose class for things found within a PlansPage.
 */
abstract class Widget {
    /**
     * A unique identifier for this item
     * @var null|string
     */
    public $identifier;
    /**
     * A group name of related widgets
     * @var null|string
     */
    public $group;
    /**
     * @param string $name An identifying name for this widget.
     * @param boolean $unique is <var>$identifier</var> unique?
     *
     * <b>Note:</b> While this identification scheme, incidentally, is quite similar to
     * the id and class properties in HTML, don't assume that this is the only way they
     * may be used.
     */
    public function __construct($name, $unique) {
        if ($unique) {
            $this->identifier = $name;
        } else {
            $this->group = $name;
        }
    }
}
/**
 * A list of widgets somehow thematically related. May serve as a structural sub-category.
 */
class WidgetGroup extends Widget {
    /**
     * An array of widgets
     */
    public $contents;
    function __construct($identifier, $unique) {
        parent::__construct($identifier, $unique);
        $this->contents = array();
    }
    public function append(Widget $widge) {
        $this->contents[] = $widge;
    }
}
/**
 * Similar to WidgetGroup, but implies more of a structural relationship between elements.
 */
class WidgetList extends WidgetGroup {
    /**
     * A title for this list
     * @var null|string
     */
    public $title;
    function __construct($identifier, $unique, $title = null) {
        parent::__construct($identifier, $unique);
        $this->title = $title;
    }
}
/**
 * A set of FormItems that are directly related.
 *
 * This again implies a more direct relationship than simply being in the same
 * form.  Layout speaking, items in a FormItemSet will generally be on the same
 * line or will be visually grouped in some other manner.
 */
class FormItemSet extends WidgetList {
    /**
     * The form this set is in
     * @var Form
     */
    public $parent_form;
    /**
     * @param FormItem|FormItemSet
     */
    public function append(Widget $item) {
        $item->parent_form = $this->parent_form;
        parent::append($item);
    }
}
/**
 * An autoread list. Stores its own priority level.
 */
class AutoRead extends WidgetList {
    /**
     * A number designating the "priority" level of this list
     * @var int
     */
    public $priority;
    /**
     * A link to set this autoread as current
     * @var Hyperlink
     */
    public $link;
    /**
     * A link to mark all plans in this autoread as read
     * @var Hyperlink
     */
    public $markasread_link;
    /**
     * @param int $p a priority level
     * @param string $url a URL to set this autoread as current
     * @todo Give markasread as a param?
     */
    function __construct($p, $url) {
        parent::__construct("autoreadlev$p", true, "Level $p");
        $this->priority = $p;
        $this->contents = array();
        $this->link = new Hyperlink('set_' . $this->identifier, true, $url, $this->title);
        $this->markasread_link = new Hyperlink('markasread', false, "setpriv.php?myprivl=$p&mark_as_read=1", 'X');
    }
}
/**
 * A link to a page.
 */
class Hyperlink extends Widget {
    /**
     * Location of the page
     * @var string a URL
     */
    public $href;
    /**
     * The text of the link
     * @var string
     */
    public $description;
    function __construct($id, $unique, $href, $desc = null) {
        parent::__construct($id, $unique);
        $this->href = $href;
        if ($desc === null) {
            $desc = $href;
        }
        $this->description = $desc;
    }
}
/**
 * A link to another user's plan.
 */
class PlanLink extends Hyperlink {
    /**
     * @param string $username the username to link to
     */
    function __construct($username) {
        $href = "read.php?searchname=$username";
        parent::__construct('planlove', false, $href, $username);
    }
}
/**
 * A link that, when clicked, shows or hides another element using Javascript.
 *
 * In the absence of Javascript, this will degrade gracefully by simply
 * displaying the target element always.
 *
 * @todo Be smarter about ids - maybe auto-generate unique ids?
 */
class DisplayToggleLink extends Hyperlink {
    /**
     * @param Widget $target the element to be shown or hidden when this link is clicked
     * @param string $show_desc the description to use when clicking this link will show the target
     * @param string $hide_desc the description to use when clicking this link will hide the target
     * @param boolean $initially_hidden is the target hidden when the page loads?
     */
    public function __construct($id, $unique, $target, $show_desc = 'Show', $hide_desc = 'Hide', $initially_hidden = true) {
        parent::__construct($id, $unique, 'javascript:void(0)', ($initially_hidden ? $show_desc : $hide_desc));
        if (!$target->identifier) {
            //STUB
            throw new Exception('You may only link a display toggle to a widget with a unique identifier.');
        }
        $this->target_id = $target->identifier;
        $this->show_desc = $show_desc;
        $this->hide_desc = $hide_desc;
        $this->initially_hidden = $initially_hidden;
    }
}
/**
 * A web form.
 */
class Form extends WidgetGroup {
    /**
     * The form's action. Defaults to containing page.
     * @var string a URL
     */
    public $action;
    /**
     * The form's method. Defaults to 'post'.
     * @var string 'post' or 'get'
     */
    public $method;
    /**
     * @param string $name a name for the form. Must be unique within the page
     */
    public function __construct($name) {
        parent::__construct($name, true);
    }
    /**
     * @param FormItem|FormItemSet
     */
    public function append(Widget $item) {
        $item->parent_form = $this;
        parent::append($item);
    }
}
/**
 * An item (field) within a form.
 */
class FormItem extends Widget {
    /**
     * The name of the field
     * @var string
     */
    public $name;
    /**
     * The title of the field
     * @var string
     */
    public $title;
    /**
     * Text description of the item
     * @var string
     */
    public $description;
    /**
     * The value of the item
     * @var mixed
     */
    public $value;
    /**
     * The type
     * @var string
     */
    public $type;
    /**
     * The disabled state of the item
     * @var bool
     */
    public $disabled;
    /**
     * The form this set is in
     * @var Form
     */
    public $parent_form;
    /**
     * @param string $name a name for this input. Must be unique within the form.
     * @param mixed $value the value of this input
     */
    public function __construct($name, $value = null) {
        parent::__construct($name, true);
        $this->name = $name;
        $this->value = $value;
    }
}
class SubmitInput extends FormItem {
    public $type = 'submit';
    public function __construct($value = 'Submit') {
        parent::__construct(null, $value);
    }
}
class HiddenInput extends FormItem {
    public $type = 'hidden';
}
class RadioInput extends FormItem {
    public $type = 'radio';
    /**
     * Is this item checked?
     * @var boolean
     */
    public $checked;
}
class CheckboxInput extends FormItem {
    public $type = 'checkbox';
    /**
     * Is this item checked?
     * @var boolean
     */
    public $checked;
}
class TextInput extends FormItem {
    public $type = 'text';
    /**
     * Is the item read-only?
     * @var bool
     */
    public $readonly = false;
}
class PasswordInput extends FormItem {
    public $type = 'password';
    /**
     * @param string $name a name for this input. Must be unique within the form.
     */
    public function __construct($name) {
        parent::__construct($name);
    }
}
class TextareaInput extends FormItem {
    public $type = 'textarea';
    /**
     * How many rows the box should span
     * @var int
     */
    public $rows;
    /**
     * How many columns the box should span
     * @var int
     */
    public $cols;
    public function __construct($name, $value = null, $rows = 3, $cols = 40) {
        $this->rows = $rows;
        $this->cols = $cols;
        parent::__construct($name, $value);
    }
}
/**
 * The form users edit their plan with
 *
 * Notice that this encompasses the entire form, not just the textarea
 */
class EditBox extends Form {
    /**
     * The username we're editing
     * @var string
     */
    public $username;
    /**
     * The contents of this plan
     * @var PlanText
     */
    public $text;
    /**
     * @see TextareaInput::$rows
     */
    public $rows;
    /**
     * @see TextareaInput::$columns
     */
    public $columns;
    public function __construct($username, $text, $rows, $cols, $submitable = 1) {
        parent::__construct('editbox', true);
        $this->username = $username;
        $this->rows = $rows;
        $this->columns = $cols;
        $this->text = $text;
        $this->submitable = $submitable;
    }
}
class PlanContent extends Widget {
    /**
     * The username we're editing
     * @var string
     */
    public $username;
    /**
     * The contents of this plan
     * @var PlanText
     */
    public $text;
    /**
     * The "name" on this plan
     */
    public $planname;
    /**
     * The date this user last logged in
     * @var int a UNIX timestamp
     */
    public $lastlogin;
    /**
     * The date this user last updated
     * @var int a UNIX timestamp
     */
    public $lastupdate;
    /**
     * A form to add this plan to autoread
     * @var Form
     */
    public $addform;
    public function __construct($username, $planname, $lastlogin, $lastupdate, $text) {
        parent::__construct('plan', true);
        $this->username = $username;
        $this->lastlogin = $lastlogin;
        $this->lastupdate = $lastupdate;
        $this->planname = $planname;
        $this->text = $text;
    }
}
abstract class Text extends Widget {
    /**
     * A string used to preface some text widgets. Details of
     * implementation left up to the interface.
     */
    public $title;
    /**
     * A string with the text to be displayed.
     *
     * Please note: this string may contain some basic HTML in it,
     * namely <<i>> and <<b>> tags, and hyperlinks.
     */
    public $message;
    public function __construct($group, $title) {
        parent::__construct($group, false);
        $this->title = $title;
    }
}
/**
 * Regular, boring old text.
 *
 * Only use this if your text doesn't fit in any of the other categories
 */
class RegularText extends Text {
    public function __construct($message) {
        parent::__construct('text', '');
        $this->message = $message;
    }
}
/**
 * Text to give the user information
 */
class InfoText extends Text {
    public function __construct($_message, $title = '') {
        if (!$title) {
            $title = 'Info';
        }
        parent::__construct('infomessage', $title);
        $this->message = $_message;
    }
}
/**
 * Text to warn the user that there's a problem
 */
class AlertText extends Text {
    /**
     * Is this alert a critical error (such as a crash)?
     * @var boolean
     */
    public $error;
    public function __construct($message, $title, $error = false) {
        parent::__construct('alertmessage', $title);
        $this->message = $message;
        $this->error = $error;
    }
}
/**
 * Text to request something from the user
 */
class RequestText extends Text {
    public function __construct($_message) {
        parent::__construct('requestmessage', 'Question');
        $this->message = $_message;
    }
}
/**
 * A section heading
 */
class HeadingText extends Text {
    /**
     * Number representing the nesting level of the heading (1 is a top level heading)
     * @var int
     */
    public $sublevel;
    public function __construct($_message, $_level) {
        parent::__construct('heading' . $_level, NULL);
        $this->message = $_message;
        $this->sublevel = $_level;
    }
}
class Secret extends Text {
    /**
     * The date this secret was submitted
     * @var int a UNIX timestamp
     */
    public $date;
    /**
     * The id of this secret
     * @var int
     */
    public $secret_id;
    public function __construct($text) {
        parent::__construct('secret', '');
        $this->message = $text;
    }
}
/**
 * For storing the contents of a user's plan.
 */
class PlanText extends Text {
    /**
     * A boolean: true if the text is in plans markup (i.e. [b] for
     * bold text), and false if text is in HTML form.
     */
    public $planmarkup;
    public function __construct($_message, $_planmarkup) {
        parent::__construct('plantext', "Plan Text");
        $this->message = $_message;
        $this->planmarkup = $_planmarkup;
    }
}
/**
 * Navigation bar for notes.
 *
 * This may be either for a single thread or the whole board.
 */
class NotesNavigation extends Widget {
    /**#@+
    * @var Hyperlink|null
    */
    public $newest;
    public $oldest;
    public $newer;
    public $even_newer;
    public $older;
    public $even_older;
    /**#@-*/
    /**
     * @var RegularText
     */
    public $current;
}
/**
 * The main Notes board
 */
class NotesBoard extends WidgetList {
}
/**
 * A single topic in notes.
 *
 * This may exist as either an entry in a NotesBoard, or on its own.
 */
class NotesTopic extends WidgetList {
    /**
     * Is this being used as a summary (i.e. on the main board), or as a
     * container for posts?
     * @var boolean
     */
    public $summary;
    /**
     * Title of the thread
     * @var Hyperlink
     */
    public $title;
    /**
     * Date of most recent activity
     */
    public $updated;
    /**
     * Number of posts in this thread
     * @var int
     */
    public $posts;
    /**
     * The thread creator
     * @var PlanLink|null
     */
    public $firstposter;
    /**
     * The most recent poster
     * @var PlanLink|null
     */
    public $lastposter;
}
/**
 * @todo give this a structure that isn't dependent on JS. Like, extend
 * Hyperlink and hold whole links for up and down, with an active flag if needed
 */
class NotesPost extends Widget {
    /**
     * Who posted this message
     * @var PlanLink|null
     */
    public $poster;
    /**
     * The date this was posted
     * @var int a UNIX timestamp
     */
    public $date;
    /**
     * The post id
     * @var int
     */
    public $id;
    /**
     * The score in Notes voting
     * @var int
     */
    public $score;
    /**
     * The number of votes cast for this post
     * @var int
     */
    public $votes;
    /**
     * How the current user has voted
     * @var string 'yes' or 'no' or null if no vote
     */
    //public $user_vote;
    
    /**
     * The contents of this post
     * @var string
     */
    public $contents;
}