NAME

Krang::Site - a means to access information on sites

SYNOPSIS

  use Krang::ClassLoader 'Site';

  # construct object
  my $site = Krang::Site->new(preview_url => 'preview.com',   # required
                              preview_path => 'preview/path/',# required
                              publish_path => 'publish/path/',# required
                              url => 'site.com');             # required

  # saves object to the DB and creates the root category '/' of the site
  $site->save();

  # getters
  my $id = $site->site_id();                    # undef until save()
  my $path = $site->preview_path();
  my $path = $site->publish_path();
  my $url = $site->preview_url();
  my $url = $site->url();

  # setters
  $site->preview_path( $new_preview_path );
  $site->publish_path( $new_publish_path );
  $site->url( $url );

  # delete the site from the database
  $site->delete();

  # a hash of search parameters
  my %params =
  ( order_desc => 1,            # result ascend unless this flag is set
    limit => 5,                   # return 5 or less site objects
    offset => 1,                  # start counting result from the
                                  # second row
    order_by => 'url'             # sort on the 'url' field
    preview_path_like => '%bob%', # match sites with preview_path
                                  # LIKE '%bob%'
    publish_path_like => '%fred%',
    preview_url => 'preview',     # match sites where preview_url is
                                  # 'preview'
    site_id => 8,
    url_like => '%.com%' );

  # any valid object field can be appended with '_like' to perform a
  # case-insensitive sub-string match on that field in the database

  # returns an array of site objects matching criteria in %params
  my @sites = pkg('Site')->find( %params );

DESCRIPTION

A site is the basic organizational unit within a Krang instance. A site may correspond to a web-site but only necessarily maps to a unique URL. Content within the site is stored within categories; see Krang::Category.

On preview, site output is written to paths under 'preview_path' and then the user is redirected to 'preview_url' - it is the same for 'publish_path' and 'url' upon publishing an asset.

This module serves as a means of adding, deleting, accessing site objects for a given Krang instance. Site objects, at present, do little other than act as a means to determine the urls and path associated with a site.

N.B - On save(), the root category for the site '/' is created.

INTERFACE

FIELDS

Access to fields for this object is provided my Krang::MethodMaker. The value of fields can be obtained and set in the following fashion:

 $value = $site->field_name();
 $site->field_name( $some_value );

The available fields for a site object are:

• preview_path
  
Full filesystem path under which the media and stories of this site will be output for preview.
• preview_url
  
URL relative to which one is redirected after the preview output of a media object or story is generated. The document root of this server is the value of 'preview_path'.
• publish_path
  
Full filesystem path under which the media and stories are published.
• site_id (read-only)
  
Integer which identifies the database rows associated with this site object.
• site_uuid (read-only)
  
Unique ID which identfies a site across different machines when moved via krang_export/krang_import.
• url
  
Base URL where site content is found. Categories and consequently media and stories will form their URLs based on this value.

METHODS

• $site = Krang::Site->new( %params )
  
Constructor for the module that relies on Krang::MethodMaker. Validation of '%params' is performed in init(). The valid fields for the hash are:
• preview_path
  
• preview_url
  
• publish_path
  
• url
  
• $success = $site->delete()
  
• $success = Krang::Site->delete( $site_id )
  
Instance or class method that deletes the given site from the database and its root category that gets instantiated on save(). It croaks if any categories reference this site other than '/'. It returns '1' following a successful deletion.

This method's underlying call to dependent_check() may result in a Krang::Site::Dependency exception if an object in the system is found that relies upon the Site in question.

N.B. - This call will result in the deletion of the Site's root category.

• $site->dependent_check()
  
• Krang::Site->dependent_check( $site_id )
  
Class or instance method that should be called before attempt to delete a Site. If any categories are found that depend rely upon this Site, then a Krang::Site::Dependency exception is thrown, otherwise, 0 is returned.

The exception's 'category_id' field contains a list of the ids of depending categories. You might wish to handle the exception thusly:

 eval {$site->dependent_check()};
 if ($@ and $@->isa('Krang::Site::Dependency')) {
     croak("This Site cannot be deleted.  Categories with the following" .
           " ids depend upon it: " . join(",", $@->category_id) . "\n");
 }

N.B. - the root category of the site is excluded from this lookup.

• $site->duplicate_check()
  
This method checks the database to see if any existing site objects possess the same URLs any of the same values as the object in memory. If this is the case, a Krang::Site::Duplicate exception is thrown, otherwise, 0 is returned.
• @sites = Krang::Site->find( %params )
  
• @sites = Krang::Site->find( site_id => [1, 1, 2, 3, 5] )
  
• @site_ids = Krang::Site->find( ids_only => 1, %params )
  
• $count = Krang::Site->find( count => 1, %params )
  
Class method that returns an array of site objects, site ids, or a count. Case-insensitive sub-string matching can be performed on any valid field by passing an argument like: ``fieldname_like => '%$string%''' (Note: '%' characters must surround the sub-string). The valid search fields are:
• preview_path
  
• preview_url
  
• publish_path
  
• site_id
  
• site_uuid
  
• url
  

Additional criteria which affect the search results are:

• count
  
If this argument is specified, the method will return a count of the sites matching the other search criteria provided.
• ids_only
  
Returns only site ids for the results found in the DB, not objects.
• limit
  
Specify this argument to determine the maximum amount of site object or site ids to be returned.
• offset
  
Sets the offset from the first row of the results to return.
• order_by
  
Specify the field by means of which the results will be sorted. By default results are sorted with the 'site_id' field.
• order_desc
  
Set this flag to '1' to sort results relative to the 'order_by' field in descending order, by default results sort in ascending order

The method croaks if an invalid search criteria is provided or if both the 'count' and 'ids_only' options are specified.

• $site = $site->save()
  
Saves the contents of the site object in memory to the database and creates its root category. The method also updates the urls of categories that reference it via update_child_categories() if its 'url' field has changed since the last save.

The method croaks if the save would result in a duplicate site object (i.e. if the object has the same path or url as another object). It also croaks if its database query affects no rows in the database.

• $success = $site->update_child_categories()
  
This method updates child categories' urls provided the 'url' field of the object has recently been changes (see save()). It returns 1 on the success of the update.
• $url = $site->url()
  
• $site = $site->url( $url )
  
Instance method that gets and sets the object 'url' field. When called as a setter, the '_old_url' is updated as well.
• $site->serialize_xml(writer => $writer, set => $set)
  
Serialize as XML. See Krang::DataSet for details.
• $site = Krang::Site->deserialize_xml(xml => $xml, set => $set, no_update => 0, skip_update => 0)
  
Deserialize XML. See Krang::DataSet for details.

If an incoming site has the same URL as an existing site then the incoming site is skipped. This change from the usual deserialize_xml() behavior was made on the theory that preview_path and publish_path are likely to vary between alpha, beta and production instances of the same site.

TO DO

SEE ALSO

Krang, Krang::DB