NAME

Krang::Template - Interface for managing template objects

SYNOPSIS

 # create a new template
 my $template = pkg('Template')->new(category    => $category,
                                     content     => '<tmpl_var test>',
                                     filename    => 'test.tmpl');

 # save contents of the object to the DB.
 $template->save();

 # put the object back into circulation for other users
 $template->checkin();

 # checkout object to work on it
 $template->checkout();

 # saves to the db again, increments version field of the object
 $template->save();

 # use this template for testing, will override deployed versions of the
 # same template
 $template->mark_for_testing();

 # no longer use this template for testing
 $template->unmark_for_testing();

 # Mark the template as having been deployed to the Krang publish path.
 # unsets testing flag in the database
 $template->mark_as_deployed();

 # Mark the template as not existing in the publish path.
 # unsets deployed, deploy_version, deploy_date.
 $template->mark_as_undeployed();

 # reverts to template revision specified by $version
 $template->revert( $version );

 # deploy template
 $template->deploy

 # remove all references to the object in the template and
 # template_version tables
 $template->delete();

 # returns array of template objects matching criteria in %params
 my @templates = pkg('Template')->find( %params );

 # Get permissions for this object
 $template->may_see() || croak("Not allowed to see");
 $template->may_edit() || croak("Not allowed to edit");

DESCRIPTION

Templates determine the form of this system's output. This module provides a means to check in, check out, edit, revert, save, and search Template objects.

A template is either associated with an element class and hence determines its formatting or it may serve as some manner of miscellaneous utility whether formatting or otherwise. Template data, i.e. the 'content' field, is, at present, intended to be in HTML::Template format. All template filenames will end in the extension '.tmpl'. Users have the ability to revert to any previous version of a template.

This module interfaces or will interface with Krang::CGI::Template, Krang::Burner, the FTP interface, and the SOAP interface.

INTERFACE

FIELDS

This module employs Krang::MethodMaker to provide accessors for all and mutators for some of the object's fields. The fields can be accessed and set in the following manner:

 # accessor
 $value = $template_obj->readable_field();

 # mutator
 $template->obj->readable_and_writeable_field( $value );

The four read/write fields for the object are:

• category
  
A reference to the category object to which this template belongs. Returns undef if template does not have a category (global templates don't).
• category_id
  
Integer that identifies the parent category of the template object.
• content
  
The HTML::Template code that make up the template.
• filename
  
The filename into which the 'content' will be output once the template is deployed.

The remaining read-only fields are:

• checked_out
  
Boolean that is true when the given object is checked_out.
• checked_out_by
  
Interger id of the user object that has the template object checked out which corresponds to the id of an object in the user table.
• creation_date
  
Date stamp identifying when the object was created. This is a Time::Piece object, initalized during new() to the current date and time.
• deployed
  
Boolean that is true when the given object has been deployed.
• deploy_date
  
Date stamp identifying when the object was last deployed. This is a Time::Piece object.
• deployed_version
  
Integer identifying the version of the template that is currently deployed.
• site
  
A reference to the Krang::Site object with which this object is associated.
• template_id
  
Integer id of the template object corresponding to its id in the template table.
• testing
  
Boolean that is true when the object has been marked for testing, i.e. the current object will be used to generate output for preview irrespective of deployed versions of the template.
• url
  
Text field where the object's calculated virtual url is stored. The url is calculated by concatenating its category's 'url' and its 'filename'. The purpose of this field is to ensure the uniqueness of a template.
• version
  
Integer identifying the version of the template object in memory.

METHODS

• $template = Krang::Template->new( %params )
  
Constructor provided by Krang::MethodMaker. Accepts a hash its argument. Validation of the keys in the hash is performed in the init() method. The valid keys to this hash are:
• category
  
• category_id
  
• content
  
• filename
  

The filename arguement is required.

• $template = $template->checkin()
  
• $template = Krang::Template->checkin( $template_id )
  
Class or instance method for checking in a template object, as a class method a template id must be passed.

Will throw Krang::Template::NoEditAccess unless user has edit access.

If the call to verify_checkout() fails, a Checkout exception is thrown.

• $template = $template->checkout()
  
• $template = Krang::Template->checkout( $template_id )
  
Class or instance method for checking out template objects, as a class method a template id must be passed.

Will throw Krang::Template::NoEditAccess unless user has edit access.

This method throws Krang::Template::Checkout if the object is already checked out by another user.

• $template->delete()
  
• Krang::Template->delete( $template_id )
  
Class or instance method for deleting template objects. As a class method the method accepts either a single template id or array object ids.

Deletion means deleting all instances of the object in the version table as well as the current version in the template.

This method attempts to check out the template before deleting; checkout() will croak if the object is checked out by another user.

Will throw Krang::Template::NoEditAccess unless user has edit access.

'1' is returned if the deletion was successful.

• $template->deploy()
  
Convenience method to Krang::Publisher, deploys template.
• $template->duplicate_check()
  
This method checks whether the url of a template is unique. A Krang::Template::DuplicateURL exception is thrown if a duplicate is found, '0' is returned otherwise.
• $template = $template->mark_as_deployed()
  
Instance method designed to work with Krang::Publisher->deploy_template to deploy templates.

The method updates the 'deployed', 'deploy_date', 'deployed_version', and 'testing' fields in the db.

• $template = $template->mark_as_undeployed()
  
Instance method designed to work with Krang::Publisher->undeploy_template to mark templates that have been removed from the publish path.

The method updates the 'deployed', 'deploy_date', and 'deployed_version' fields in the db.

• @templates = Krang::Template->find( %params )
  
• @template = Krang::Template->find( template_id => 1 )
  
• @templates = Krang::Template->find( template_id => [1, 2, 3, 5, 8] )
  
• @template_ids = Krang::Template->find( ids_only => 1, etc., )
  
• $count = Krang::Template->find( count => 1, etc., )
  
Class method that returns the template objects or ids matching the criteria provided in %params.

Fields may be matched using SQL matching. Appending ``_like'' to a field name will specify a case-insensitive SQL match.

@templates = Krang::Template->find(filename_like => '%' . $string . '%');

Notice that it is necessary to surround terms with '%' to perform sub-string matches.

The list valid search fields is:

• category_id
  
• below_category_id
  
• checked_out
  
• checked_out_by
  
• creation_date
  
• deploy_date
  
• deployed
  
• filename
  
• full_text_string
  
• template_id
  
• template_uuid
  
• testing
  
• version
  
• simple_search
  
• simple_search_check_full_text (boolean)
  

Additional criteria which affect the search results are:

• count
  
If this argument is specified, the method will return a count of the templates matching the other search criteria provided.
• ids_only
  
Returns only template ids for the results found in the DB, not objects.
• limit
  
Specify this argument to determine the maximum amount of template object or template 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 'template_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
• include_live
  
Include live templates in the search result. Live templates are templates that are neither retired nor have been moved to the trashbin. Set this option to 0, if find() should not return live templates. The default is 1.
• include_retired
  
Set this option to 1 if you want to include retired templates in the search result. The default is 0.
• * include_trashed
  
Set this option to 1 if you want to include trashed templates in the search result. Trashed templates live in the trashbin. The default is 0.

NOTE:When searching for template_id, these three include_* flags are not taken into account!

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

• $template = $template->mark_for_testing()
  
This method sets the testing fields in the template table to allow for the testing of output of an undeployed template. If the method call is successful, the 'testing' field is updated in the db. 'checked_out_by' will identify the user that has flagged the template for testing.

The method croaks if the template is not checked out or checked out by another user.

• $template = $template->mark_for_testing()
  
This method unsets the testing fields in the template table.

The method croaks if the template is not checked out or checked out by another user.

• $all_version_numbers = $template->all_versions();
  
Returns an arrayref containing all the existing version numbers for this template object.
• $template->prune_versions(number_to_keep => 10);
  
Deletes old versions of this template object. By default prune_versions() keeps the number of versions specified by SavedVersionsPerTemplate in krang.conf; this can be overridden as above. In either case, it returns the number of versions actually deleted.
• $template->revert( $version )
  
Reverts template object data to that of a previous version.

Reverting to a previous version effectively means deserializing the previous version from the database and using it to create a new, identical version, overwriting the values currently in the object.

The method croaks if the template is not checked out, checked out by another user, or it can't deserialize the retrieved version.

Otherwise, if the new version is successfully written to disk (no duplicate URL errors, etc.), the object itself is returned; if not, an error is returned.

• $template = $template->save()
  
Saves template data in memory to the database.

Stores a copy of the objects current contents to the template table. The version field is incremented on each save unless called with 'keep_version' set to 1.

duplicate_check() throws an exception if the template's url isn't unique. verify_checkout() throws an exception if the template isn't checked out or if it's checked out to another user. The method croaks if its executed SQL affects no rows in the DB.

Will throw Krang::Template::NoEditAccess unless user has edit access.

Will throw Krang::Template::NoCategoryEditAccess unless user has edit access to the specified category.

• $template = $template->update_url( $url );
  
Method called on object to propagate changes to parent category's 'url'.
• $template->serialize_xml(writer => $writer, set => $set)
  
Serialize as XML. See Krang::DataSet for details.
• $template = Krang::Template->deserialize_xml(xml => $xml, set => $set, no_update => 0)
  
Deserialize XML. See Krang::DataSet for details.

If an incoming template has the same URL as an existing template then an update will occur, unless no_update is set.

Note that the creation_date, version, deploy_date, deployed_version fields are ignored when importing templates.

Also, all templates are deployed after deserialization.

• $template->verify_checkout()
  
Instance method that verifies the given object is both checked out and checked out to the current user.

A Krang::Template::Checkout exception is thrown if the template isn't checked out or is checked out by another user, otherwise, '1' is returned.

• $template->retire()
  
• Krang::Template->retire(template_id => $template_id)
  
Archive the template, i.e. undeploy it and don't show it on the Find Template screen. Throws a Krang::Template::NoEditAccess exception if user may not edit this template. Croaks if the template is checked out by another user.
• $template->unretire()
  
• Krang::Template->unretire(template_id => $template_id)
  
Unretire the template, i.e. show it again on the Find Template screen, but don't redeploy it. Throws a Krang::Template::NoEditAccess exception if user may not edit this template. Throws a Krang::Template::DuplicateURL exception if a template with the same URL has been created in Live. Croaks if the template is checked out by another user.
• $template->trash()
  
• Krang::Template->trash(template_id => $template_id)
  
Move the template to the trashbin, i.e. undeploy it and don't show it on the Find Template screen. Throws a Krang::Template::NoEditAccess exception if user may not edit this template. Croaks if the template is checked out by another user.
• $template->untrash()
  
• Krang::Template->untrash(template_id => $template_id)
  
Restore the template from the trashbin, i.e. show it again on the Find Template or Archived Templates screens (depending on the location from where it was deleted). Throws a Krang::Template::NoRestoreAccess exception if user may not edit this template. Croaks if the template is checked out by another user. This method is called by Krang::Trash->restore().
• $template->clone(category_id => $category_id)
  
Copy $template to the category having the specified category_id. Returns an unsaved and checked out copy.

TO DO

 * Prevent duplicate template objects and paths once pkg('Category') is
   completed

SEE ALSO

Krang, Krang::DB, Krang::Log