The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Contentment-0.011_033
River stage zero No dependents
++
/ Contentment::Site

NAME

Contentment::Site - A plugin for managing site information

SYNOPSIS

  my $site = $context->current_site;

  my $base_url = $site->base_url;
  print qq(<a href="$base_url/my/absolute/link.html">Absolute Link</a>\n);

DESCRIPTION

The Contentment::Site class is used to store site information. Each request recieved by Contentment is matched against each site record to find a match. If no match is found, the default site information is assumed. Based upon this information, various plugins can make decisions to make a given site appear or behave differently from the main site.

Currently, sites are differentiated by very primitive means. Additional means may be added in the future. At this time, each site is specified by four parameters: scheme, server name, server port, and root path. An additional field also uniquely identifies each site called the site name, which is just a mnemonic identifier. Each site has other configuration information associated with it, which is stored via the Contentment::Setting table.

It is possible for the current request to match on all three scheme, server name, and server port and match more than one root path. For example, given the request:

  http://www.contentment.org/foo/bar.html

and two different site records with the following base URLs:

  http://www.contentment.org/
  http://www.contentment.org/foo/

in this case, the current request essentially matches both. In the case of this occurrence, the site record with the longest matching root path will be given preference.

The site record with site name "default" is special. This is the site that will be used as the current site if no site matches directly.

FIELDS

Each instance of Contentment::Site has the following fields:

$scheme = $site->scheme
$site->scheme($new_scheme)

This is the scheme the site matches. Only values of "http" and "https" make sense. This value must be set.

$server_name = $site->server_name
$site->server_name($new_server_name)

This is the server name that the site matches. This value must be set to a fully-qualified hostname or string representation of an IP address. (Obviously, the former should be preferred.)

See "BUGS" about a possible caveat involving host names without periods (i.e., "localhost").

$server_port = $site->server_port
$site->server_port($new_server_port)

This is the port number of the site. This must be set. Typically, the value will be "80" if the scheme is "http" and "443" if the scheme is "https", but it might be something completely different in either case.

$root_path = $site->root_path
$site->root_path($new_root_path)

This is the full path to the root of the server. This must be given even if the root path is just the root path of the server---in which case it should be given as "/", and not the empty string "". The root path should always end in a trailing slash.

$uri = $site->base_url
$site->base_url($new_uri)
$uri = $site->base_uri
$site->base_uri($new_uri)

This method returns a URI object set to contain the information returned by scheme(), server_name(), server_port(), and root_path(). The URI object will be normalized via the canonical() method.

If the the mutator form of the method is used to set a new URI ($new_uri), the URI may be given as either a string or URI object. If given as a string, it will be passed to URI's constructor. Each of the other fields will be updated from the URI object given.

$site_name = $site->site_name
$site->site_name($new_site_name)

This is a mnemonic site name that is mostly useful for the management of sites. The site named "default" is special and is used when no other site matches. There must always be at least one site with the site name of "default".

$settings = $site->settings
$site->settings($new_settings)

This holds the rest of the settings for the site. This field actually returns the value of the setting named "Contentment::Site::site_name", where site_name is the value returned by site_name(). The value returned is a reference to a hash.

If you need to update the settings, you must use the mutator method here to make those settings stick. The settings will be immediately updated, but not committed.

METHODS

Each instance of Contentment::Site is an Oryx object, with all the methods there and the methods described in the "FIELDS" section. In addition, the following methods are defined.

$site = Contentment::Site->current_site

This fetches the site record that either matches the current request or fetches the site record with the site name "default".

CONTEXT

This class adds the following methods to the context:

$site = $context->current_site

Returns a reference to the Contentment::Site instance for the current site.

@sites = $context->sites(\%params)

Returns a list of site instances. If the optional %params hash is not given or is empty, all sites will be returned. Otherwise, this method returns the sites found by calling the search() method, like so:

  my @sites = Contentment::Site->search(\%params);

HOOK HANDLERS

Contentment::Site::install

This handles the "Contentment::install" hook and installs the database table.

Contentment::Site::begin

This handles the "Contentment::Request::begin" hook. It checks to see if a default site has already been created (by looking to see if the "default_created" setting is set in the "Contentment::Plugin::Site" settings). Creates a default site based upon the information given in the current request. It will check for a global configuration setting named "initial_site_root_path" to fill in the root path. If none is set, it will assume "/" (which may be bad, but I can't think of a better solution at this time).

BUGS

I'm not sure where this comes from, but LWP doesn't handle cookies where the hostname does not contain a period. Instead, if it encounters such a host, it automatically appends ".local" to the hostname.

Since the test suite relies upon "localhost" (a hostname without a period) and cookies need to be tested, upon creation or update this class will automatically add ".local" to the host part of any site URI that does not contain a period. Whether this is a good idea or bad one, I don't know, but it solves the problem at this time.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2005 Andrew Sterling Hanenkamp <hanenkamp@cpan.org>. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.