LoginRegisterCommercial SupportContact Us


POD documentation > Fundamentals > Base.pm

Base.pm

Base class, inherited by all ExSite classes
posted on 2:47 PM, July 12, 2009


ExSite::Base - ExSite Base class

The base class defines the most generic behaviours of the ExSite class libraries, which are inherited by all ExSite classes/objects.

new(%opt)

The generic constructor method copies the contents of %opt into the object hash attributes. It then invokes the initialize_object()

method to set up other Base class features.

initialize_object()

This method sets up system handlers and diagnostic accumulators. Classes that overload the new() constructor should call this from their own constructors in order to get the Base class behaviours.

get($attribute)

Returns the value of the named object attribute.

set($attribute,$value)

Sets the named object attribute to the given value.

unset($attribute)

Deletes the named attribute from the object, if it exists. Returns true if deleted, false if the attribute doesn't exist.


Handlers

Handlers exist to override or augment default system logic. The handler is passed sufficient data to decide if it wants to override the logic. Typically (but not in every case), the handler returns the results of its special processing (in a format understood by the caller), or undef if it decided not to override the system logic. In the latter case, ExSite will proceed with the default system logic. Otherwise, the details of what a particular handler does is documented elsewhere (kernel docs, or in the code).

handler($name,$handler_code)

Installs a special code handler under $name. $handler_code is a reference to a subroutine that accepts the arguments required by the handler, and returns the value expected by the handler.

run_handler($name,@params)

Attempts to find and run the handler(s) installed under $name. If no such handlers exist, returns undef. If one handler has been installed, it executes that handler (passing it @params), and returns the handler's return value. If more than one handler exist, they are run in sequence (in the order in which they were installed) until one returns a defined value. That value is returned to the caller, and the remaining handlers are not executed. This allows you to install several alternative versions of a handler, each for a different case, and allow them all to decide if they will take action or not. The first to act will pre-empt the others.


Diagnostics

Diagnostics are messages about system execution, including:

errors (type ``error'')
These are problems that prevent completion of a processing task, forcing the code to abort.

warnings (type ``warn'')
These are possible problems that do not prevent completion of a processing task, which the code can work around.

informational messages (type ``info'')
These are status messages that simply report on state or tasks being commenced/completed. They do not imply any problems, and are used mostly for logging or tracing execution flow.

Diagnostic messages are logged internally in the object, and depending on the settings of the logging configuration parameters, may also be written to log files.

error(@message)

Logs a list of error messages. Returns the error(s), formatted as HTML, so you can do something like this:

    $output_text .= $this->error("permission denied");

warn(@message)

Logs a list of warning messages. Returns the warning(s), formatted as HTML.

info(@message)

Logs a list of info messages. Returns the message(s), formatted as HTML.

errorcheck($type)

Returns true if any messages of $type (error, warn, info) have been logged. $type defaults to error, so you can do the following to see if an operation went smoothly or not:

    # some operation...
    if ($this->errorcheck()) {  # problems...

fetch_diagnostics($type)

Returns an array of diagnostic messages of $type (default is error). The array is empty if no diagnostics of that type were logged.

show_diagnostics($type,format)

Returns a formatted report of diagnostic messages of $type (default is error). $format can be ``HTML'' to format that report as text/html; otherwise it is formatted as plain text.

log($logfile,@messages)

Writes the messages to the given logfile, which is normally one of ``db'', ``cms'', or ``diag'', depending on the class of the object logging the message.

Logged messages include the URI, the user name, the timestamp, and the message. Messages are only written out if the config file is set to write messages of that type. The configuration settings understand 4 logging levels:

    0 - quiet (no diagnostics)
    1 - show error messages only
    2 - show errors and warnings
    3 - show all messages

showlog($logfile,$n)

Returns the last $n messages in the given logfile. If $n is not given, returns all messages in the logfile.