YaBB3 - The YaBB3 global forum object.


Name

YaBB3 - The YaBB3 global forum object.


Synopsis

  use YaBB3 qw($Y);
  $Y = new YaBB3;
  if( !$Y->init()) {
        my $errmsg = 'YOUR ERROR MESSAGE';
        # dont use the TT here to display such an early error
    $Y->error( $errmsg, 'error', {'directPrint' => 1}, 1);
    exit;
  }
        
    exit;
}


Overview

The global YaBB3 forum state object. It provides access to the forum components, and to the current CGI request and login context.


Description

The YaBB3 forum structure and state are stored in a DBI package accessible database. One of a set of Perl script files are used as the target of any CGI forum request. The script first creates and initializes this YaBB3 object, which it assigns to the globally available YaBB3::$Y variable, to define the login context and get access to that database. The database records needed for the request are loaded into the object field hashes and the request is processed. Either a reply is composed and returned using the Template package, or an error reply is composed and returned by the $Y->{ERROR} object.

Any other package can access this global object through the exported YaBB3::$Y scalar by including this use statement:

  use YaBB3 qw($Y);

A YaBB3 object is created with the new() method.

  $Y = new YaBB3;

The object can then be initialized, using the init() method, with commonly required objects (like the CGI, database, session, and error objects), and the global forum settings from the database. It will return true on success, and false if an error was logged. In case of an error don't use the $Y->errorDisplay and equal methods since it may be that we had an error while initializing the Template Toolkit or the Database. Both are required for the methods to work that is why we use the error method directly and specify the way how to display the error.

  if( !$Y->init()) {
        my $errmsg = 'YOUR ERROR MESSAGE';
                # Display the stack of logged errors.   
    $Y->error( $errmsg, 'error', {'directPrint' => 1}, 1);
    exit;
  }

The CGI Request

The request fields can be passed using a combinations of a cookie, POST header fields, and GET query fields, which are accessed using the YaBB3::yCGI object accessed through the $Y->{QUERY} field. The cookie can define the request context, the POST header fields provide any form based information, and the GET query fields specify the target script, command, and can override both the cookie and POST fields.

There is a target CGI script file for each category of request, and the specific request is passed in the $Y->{QUERY}->{ACTION} field. The usual sequence of events is as follows:

The Login Session and User

Any request made to the forum is made in the context of a logged-in member or an anonymous guest. This context is defined by a session. Each client that first accesses the forum is logged-in as an anonymous guest and is passed a session id. Each subsequent request made by that client is processed in the context of that session id. If the client then logs-in as a registered member, a new member session is created and the new session id is passed back. Now all subsequent requests from that client will be made in the context of that member session until the member is logged-off or times-out.

Any current session is identified by a session id string. This session id is generated each time a user logs-in as a member or an anonymous guest connects. It provides information about the member in the context of the set of requests made between when they have logged-in and logged-out, and is stored in the backing database. It also helps to secure the session against external interference or request spoofing.

The YaBB3::Entities::Session object manages the state of the current session and is accessed through the $Y->{SESSION} field. The YaBB3::Entities::User object manages the state of the current member and is accessed through the $Y->{USER} field.

The Forum Configurable Settings

The configurable settings of the YaBB3 forum are kept in a database table, and are managed by the YaBB3::Settings object through the $Y->{SETTINGS} field. This allows the forum to be configured without changing any of the forum script files, and allows multiple forums to be managed by single set of script files. In OOP terms: The script files define behavior and the specific forum database defines state.

The Forum Structure and Database

All forum data and current state is kept in a database that is accessed using a database-independent SQL protocol. This allows the administrator to use whatever database they desire (like MySQL or MSSQL). The forum data can be exported from one database application to another without altering the forum state. The database is managed by the DBDriver object which is accessed throught the $Y->{DB} field.

The forum message hierarchy is organized as a tree with the following branches:

The database message hierarchy records for a single forum are managed by a set of objects accessed through an associated YaBB3 hash field. CATEGORIES Hash of YaBB3::Entities::Category records. POSTS Hash of YaBB3::Entities::Post records.

The database also contains:

The current sessions, member groups, and private messages are accessed through objects kept in the following YaBB3 hash fields: SESSIONS Hash of YaBB3::Entities::Session records. GROUPS Hash of YaBB3::Entities::Group records. MESSAGES Hash of YaBB3::Entities::Message records.

Other objects, like BBC and Smiley lists, are created on the fly as needed.

The Templated Composition of the Reply

The Template package is a third party package called the Template Toolkit. It uses XHTML template files with embedded elements to create the XHTML reply pages that are sent back to the client. This package is managed by the Template object and is accessed through the $Y->{TT} field.

Full documentation for the Template Toolkit is available at http://www.template-toolkit.org/docs.html.

The Error Log

Any error encountered during the processing of a request can be logged in the YaBB3::Error object stored in $Y->{Error}. However, YaBB3 has some convenience methods that should be used instead. When a method returns the result of the $Y->error() method, it logs the given error in an error stack and returs the undefined value. The returned undefined value tells the method caller that an error occurred, and the caller can either take it's own action, or log and return it's own error call. The logged error will display the file and line where the error occurred, and the file and line of the caller. If each caller logs an error, the entire stack frame will be displayed.

Eventually control will be returned to the top-level script. If an error was logged, this script can call the $Y->errorDisplay() method to compose and send the error response. If an end-user friendly generic response is desired, the $Y->errorGenericDisplay() will display the template object generic message instead. Note that only a top-level script should use the error dispaly methods so that the entire stack frame will be returned.

The $Y->isError() method will return true if any error is currently logged.

Development Debugging


Reference

Use Packages

  YaBB3::Entities::User
  YaBB3::Entities::Session
  YaBB3::DBDriver
  YaBB3::Settings
  YaBB3::Error
  YaBB3::Language
  YaBB3::yCGI
  YaBB3::Display
  Template
  Exporter
  Language::English::Common   # and other packages with the language strings. will change to an dynamically load of these files depending on the users chosen language

Exports

  Default   $Y $VERSION
  Optional
  Tags

Package Fields

  $Y        The global YaBB3 forum object.
  $VERSION  The package version number as a float.

Object Super Classes

  Exporter

Object Fields

$START_TIME
The time this request was received by the server.

/%POSTS
Hash of post records.

/%CATEGORIES
Hash of category records.

/%SESSIONS
Hash of session records.

/%GROUPS
Hash of member group records.

/%MESSAGES
Hash of private message records.

/%ERROR
The error log object.

/%DB
The DBI object.

/%SETTINGS
The Configurable forum settings object.

/%TT
The template object.

/%QUERY
The CGI query object.

/%SESSION
The current session object.

/%USER
The current session user object.

/%TXT
The multilanguage object.

Object Methods

new

  Returns
  /%       The constructed object reference.

Construct and return a new YaBB3 forum object as an empty hash.

init

    $on_web     True  If run as CGI/mod_perl (default)
                False Otherwise
    $do_apache  True  If run on an Apache server
                False Otherwise

Initialize the global forum object fields, current session, common text and user.

loadStats

  Returns
  /%       A reference to a hash of usage statistics.
              $total_topics   The count of topics on all boards.
              $total_posts    The count of posts on all boards.
              $total_members  The count of registered members.
             /%latest_post    The last posted message as a YaBB3::Entities::Post object.
             /%latest_thread  The topic of the last posted message as the
                              first YaBB3::Entities::Post object in the topic.
             /%newest_member  The newest member as a /YaBB3::Entities::User object.
              $guest_count    The count of online guests.
             /@users          A list of online YaBB3::Entities::User objects.

Return a hash reference of usage statistics for this forum.

buildURL

  $        [Opt] The URL target script name.
  $        [Opt} The URL query string.
  Returns
  $        The composed URL string.

Build and return an URL for this forum using the given target script name and query string. The forum base URL, path, and file extension, will be added.

getScript

  $script_name  Script name.
  Returns
  $             The script file name.

Return the filename for the given script name. This simply adds the file extension to the script name.

navPost

  /%post     The post to prepend.
  /@navtree  The navigation tree array.
  Returns
  /@         The altered navigation tree array.

Prepend the given post and each ancestor to the given navtree.

navBoard

  /%board    The board to prepend.
  /@navtree  The navigation tree array.
  Returns
  /@         The altered navigation tree array.

Prepend the given board and each ancestor to the given navtree.

navCat

  /%cat      The category to prepend.
  /@navtree  The navigation tree array.
  Returns
  /@         The altered navigation tree array.

Prepend the given category and each ancestor to the given navtree.

formatTime

Deprecated soon ?! Used in Templates

error

  See YaBB3::Error->error for arguments.
  Returns
  undef      Indicates to the caller that there was an error.

Add an error message to the Error object stack. See YaBB3::Error for details.

errorDisplay

  See YaBB3::Error->errorDisplay for arguments.
  Returns
  undef      Indicates to the caller that there was an error.

Display an error message and the error stack. See YaBB3::Error for details.

errorGenericDisplay

  See YaBB3::Error->errorGenericDisplay for arguments.
  Returns
  undef      Indicates to the caller that there was an error.

Display a generic error message and the error stack. See YaBB3::Error for details.

isError

  Returns
  $        1 If there are any logged errors.
           0 If not.

Return true if there has been an error.


Author

Brian Hann (c0bra@users.sourceforge.net) Torsten Mrotz (tmrotz@yabbforum.com)

Copyright ©2000-2005, YaBB 3 Development Team. All Rights Reserved.
You may distribute this module under the terms of YaBB 3.
 YaBB3 - The YaBB3 global forum object.