NAME

Krang::Publisher - Center of the Publishing Universe.

SYNOPSIS

  use Krang::ClassLoader 'Publisher';

  my $publisher = new pkg('Publisher')();

  # Publish a list of stories to the preview path.
  # returns preview URL of first story in the list.
  my $url = $publisher->preview_story(story => \@stories);

  # Publish a list of stories to the publish path.
  $publisher->publish_story(story => \@stories);

  # unpublish a story, usually called from $story->delete
  $publisher->unpublish_story(story => $story);

  # Publish a media object to the preview path.
  # Returns the media URL if successful.
  $url = $publisher->preview_media(media => $media);

  # Publish a media object to the preview path.
  # Returns the media URL if successful.
  $url = $publisher->publish_media(media => $media);

  # unpublish a media object, usually called from $media->delete
  $publisher->unpublish_media(media => $media);

  # Get the list of related stories and media that will get published
  my $asset_list = $publisher->asset_list(story => [$story1, $story2]);

  # Place a Krang::Template template into the production path, to be
  # used when publishing.
  $publisher->deploy_template(template => $template);

  # Remove a template from the production path.
  $publisher->undeploy_template(template => $template);

  # Returns the mark used internally to break content into pages.
  my $break_txt = $publisher->PAGE_BREAK();

  # Return the Krang::Story object of the story currently being published.
  my $story = $publisher->story();

  # Return the Krang::Category object for the current category of the
  # story being published.
  my $category = $publisher->category();

  # Return the filename for a given page of the story being published.
  my $filename = $publisher->story_filename(page => $page_num);

  # determine if we're in preview mode or publish mode.
  $bool = $publisher->is_preview();
  $bool = $publisher->is_publish();

  # check to see if an object will be published, given its current state
  $bool = $publisher->test_publish_status(object => $story, mode => 'publish');

DESCRIPTION

Krang::Publisher is responsible for coordinating the various components that make up a Story (Elements, Media, Categories), and putting them all together, out on the filesystem, for the world + dog to see. The publish process will result in either 'preview' or 'publish' output - content-wise, they are indistinguishable.

In both the preview and publish process, stories are checked for related media (see Krang::Story->linked_media()). Media objects will be copied into the proper output directory as part of the build process.

Unless version_check is turned off, all related assets will compare version() with preview_version() or published_version(), to see if the currently live version (in either preview or publish, depending on the mode) is the latest saved version. If so, the asset will not be published, though it will be checked for additional related assets to publish.

See Krang::ElementClass::TopLevel->force_republish() to bypass the version_check functionality.

In the publish (but not preview) process, stories will also be checked for linked stories (see Krang::Story->linked_stories()). Any linked-to stories will be checked for publish status, and will be published if they are marked as unpublished.

INTERFACE

FIELDS

Access to fields for this object are provided by Krang::MethodMaker. All fields are accessible in a read-only fashion. The value of fields can be obtained in the following fashion:

  $value = $publisher->field_name();

The available fields for a publish object are:

• is_preview
  
Returns a 1 if the current publish run is in preview-mode, 0 otherwise.
• is_publish
  
Returns a 1 if the current publish run is in publish-mode (e.g. going live), 0 otherwise.
• category
  
Returns a Krang::Category object for the category currently being published.
• story
  
Returns a Krang::Story object for the Story currently being published.

METHODS

• $publisher = Krang::Publisher->new();
  
Creates a new Krang::Publisher object. No parameters are needed at this time.
• $url = $publisher->preview_story(story => $story)
  
Generates a story, saving it to the preview doc root on the filesystem. Returns a URL to the story if successful, or will throw one of several potential Exceptions (potential issues: filesystem problems, exceptions thrown by other objects, anything else?) in the event something goes wrong.

Arguments:

• story
  
A single Krang::Story object.
• unsaved
  
defaults to 0. If unsaved is true, Krang::Story->preview_version will be set to -1. What this does is force a republish of the story object to the preview path the next time the object comes up as a related object to a story being previewed.

As part of the publish process, all media and stories linked to by $story will be examined. If the current version of each object has not been published to preview, it will be. If the object has been previewed previously, it will be skipped.

• version_check
  
Defaults to 1. When true, it checks all related stories and media to see if the current version has been published previously to the preview path, skipping those that have. When false, it will publish all related assets, regardless of whether or not the current version has been published to preview before.
• remember_asset_list
  
Boolean, defaults to false.

If true, the Krang::Publisher object will remember these media objects, and will skip re-publishing them if they come up again (e.g. if linked to a story being published).

This only affects successive publish calls to a single Krang::Publisher object. See bin/krang_publish for an example of this functionality being used.

• callback
  
The optional parameter callback will point to a subroutine which is called when each object is published to the preview location. It recieves three named parameters:
• object
  
The affected object.
• counter
  
The index of the current object in the list of objects being published.
• total.
  
The total number of objects being published.

• $publisher->publish_story(story => $story, callback => \%onpublish)
  
Publishes a story to the live webserver document root, as set by publish_path.

When a story is published, it is published under all categories it is associated with (see Krang::Story->categories()).

As part of the publish process, all media and stories linked to by $story will be examined. For each of these objects, if the latest version has not yet been published, it will be. If the current version has been published, it will be skipped (though the objects links will also be checked).

If you do not care about related assets (WARNING - You want to care!), you can set the argument disable_related_assets =>1

If the user attempts to publish an object that is checked out by someone else, it will get skipped.

It is assumed that the UI will prevent a user from attempting to publish something when they do not have permissions. The only access-control issues that will come up here would involve filesystem permissions.

Arguments:

• story
  
Either a single Krang::Story object, or a reference to an array of Krang::Story objects.
• disable_related_assets
  
Defaults to 0. If true, no link-checking is done, only the items passed in as part of the story argument are published.
• version_check
  
Defaults to 1. When true, it checks all related stories and media to see if the current version has been published previously, skipping those that have. When false, it will publish all related assets, regardless of whether or not the current version has been published before.
• maintain_versions
  
Defaults to 0. If true, will re-publish the last-published version of each asset rather than the latest version.
• remember_asset_list
  
Boolean, defaults to false.

If true, the Krang::Publisher object will remember these media objects, and will skip re-publishing them if they come up again (e.g. if linked to a story being published).

This only affects successive publish calls to a single Krang::Publisher object. See bin/krang_publish for an example of this functionality being used.

• callback
  
The optional parameter callback will point to a subroutine which is called when each object is published to the preview location. It recieves three named parameters:
• object
  
The affected object.
• counter
  
The index of the current object in the list of objects being published.
• total.
  
The total number of objects being published.

• skip_callback
  
The optional parameter skip_callback is a pointer to a subroutine which is called whenever an object is skipped during the publish process, for whatever reason. It takes four named parameters:
• object
  
The object being skipped during the publish run.
• error
  
The type of error. output_error, checked_out, and a number of internal exceptions are the current set.
• path
  
The location on the filesystem where the object was to be published to.
• error_msg
  
A text message explaining the error in more detail.

• $publisher->unpublish_story(story => $story)
  
Removes a story from its published locations. Usually called by $story->delete. Affects both preview and publish locations.

The published, publish_date and published_version attributes of the Krang::Story object all removed and set to undef.

• $publisher->unpublish_media(media => $media)
  
Removes a media object from its published locations. Usually called by $media->delete. Affects both preview and publish locations.

The published, publish_date and published_version attributes of the Krang::Media object are reset to undef.

• $url = $publisher->preview_media(media => $media, unsaved => 1)
  
Copies a media file out to the webserver doc root for the preview website.

Arguments:

• media
  
Required. The Krang::Media object being previewed.
• unsaved
  
Optional, defaults to 0. If unsaved is true, <Krang::Media-preview_version>> will be set to -1. What this does is force a republish of the media object to the preview path the next time the object comes up as a related object to a story being previewed.
• remember_asset_list
  
Boolean, defaults to false.

If true, the Krang::Publisher object will remember these media objects, and will skip re-publishing them if they come up again (e.g. if linked to a story being published).

This only affects successive publish calls to a single Krang::Publisher object. See bin/krang_publish for an example of this functionality being used.

Returns a url to the media file on the preview website if successful.

Will throw an exception if there are problems with the copy.

• $url = $publisher->publish_media(media => $media)
  
Copies a media file out to the webserver doc root for the publish website.

Arguments:

• media
  
Required. The Krang::Media object being published.
• remember_asset_list
  
Boolean, defaults to false.

If true, the Krang::Publisher object will remember these media objects, and will skip re-publishing them if they come up again (e.g. if linked to a story being published).

This only affects successive publish calls to a single Krang::Publisher object. See bin/krang_publish for an example of this functionality being used.

• maintain_versions
  
Defaults to 0. If true, we will re-publish the last-published version of the media (if any) rather than the latest.

Returns a url to the media file on the publish website if successful.

If the user attempts to publish content that is checked out by someone else, it will get skipped.

It is assumed that the UI will prevent a user from attempting to publish something when they do not have permissions.

Will throw an exception if there are problems with the copy.

• $asset_list = $publisher->asset_list(story => $story)
  
Returns the list of stories and media objects that will get published if either publish_story() or preview_story() is called.

The sub calls $story->linked_stories() and $story->linked_media() to generate the lists, recursively operating on the results generated by $story->linked_stories().

If successful, it will return lists of Krang::Story and Krang::Media objects that will get published along with $story. At the absolute minimum (no linked stories or media), $stories->[0] will contain the originally submitted parameter $story.

Arguments:

• story
  
The story parameter can either be a single Krang::Story object or a list of Krang::Story objects.
• keep_asset_list
  
Defaults to false. If true, the internal list of checked stories is not cleared upon completion. If you are going to be making multiple successive calls to asset_list(), and want to ensure that the returning asset list does not contain assets from previous calls, set to true.
• mode
  
Optional. Either 'preview' or 'publish'. If not set, checks to see if either is_preview() or is_publish is true. If neither are true, will croak.
• version_check
  
Defaults to true. If true, every related asset will be checked to see if either $object->preview_version() or $object->published_version() (depending on mode above) is equal to $object->version(). If so, it won't be published, but its' related assets will still be checked.

Setting version_check to 0 (false) will result in the original Krang behavior - all related content will be published, regardless of versioning.

This addition is a performance improvement - the purpose is to keep from publishing content that has not changed since the last publishing.

• maintain_versions
  
Defaults to 0. If true (and in publish mode), we will build a list of the last-published version of each asset (if any) rather than the latest version.

• $publisher->_process_assets(%args)
  
Called by publish_story(). Method takes in a list of assets to publish in publish_list, it than proceeds to write the assets to disk.

Arguments:

• publish_list
  
Array reference of assets to publish.
• skip_callback
  
The optional parameter skip_callback is a pointer to a subroutine which is called whenever an object is skipped during the publish process, for whatever reason. It takes four named parameters:
• callback
  
The optional parameter callback will point to a subroutine which is called when each object is published to the preview location. It recieves three named parameters:
• remember_asset_list
  
Boolean if set to true will not call clear asset lists in _clear_asset_lists()
• user_id
  
Needed to make sure the object to published isn't checked out by another user

• $publisher->_process_preview_assets(%args)
  
Called by preview_story(). Method takes in a list of assets to publish in publish_list, it than proceeds to write the assets to the preview_path. Decoupling of asset list from publishing of assets, permits an more natural entry point for a subclass ( to be written at a later time) to provide parallel publishing behavior.

Arguments:

• publish_list
  
array reference of assets to publish to the preview location.
• callback
  
The optional parameter callback will point to a subroutine which is called when each object is published to the preview location. It recieves three named parameters:
• story
  
Initial story object to preview.
• unsaved
  
defaults to 0. If unsaved is true, Krang::Story->preview_version will be set to -1. What this does is force a republish of the story object to the preview path the next time the object comes up as a related object to a story being previewed.

As part of the publish process, all media and stories linked to by $story will be examined. If the current version of each object has not been published to preview, it will be. If the object has been previewed previously, it will be skipped.

• $filename = $publisher->deploy_template(template => $template);
  
Deploys the template stored in a Krang::Template object into the template publish_path under $KRANG_ROOT.

The final path of the template is based on $category->url() and $template->element_class_name().

If successful, deploy_template() returns the final resting place of the template. In the event of an error, deploy_template() will croak.

deploy_template() makes no attempt to update the database as to the publish status or location of the template - that is the responsibility of Krang::Template (or should it call the appropriate method in Krang::Template?)

• $publisher->undeploy_template(template => $template);
  
Removes the template specified by a Krang::Template object from the template publish_path under $KRANG_ROOT.

The location of the template is based on $category->url() and $template->element_class_name().

If successful, undeploy_template() returns nothing. In the event of an error, undeploy_template() will croak.

undeploy_template() makes no attempt to update the database as to the publish status or location of the template - that is the responsibility of Krang::Template (or should it call the appropriate method in Krang::Template?)

• $dir = $publisher->template_search_path(category => $category)
  
Given the current category, returns the list of directories that may contain a template. The first element in the returning array contains the directory of the current category, the last element contains the directory of the root category (parent of all categories in the site).

Arguments:

• category
  
An optional argument - if not supplied, the current Krang::Category category in the publish run is used (usually the best choice).

A note on preview: In preview mode, this method will check to see if the user has a testing-template temporary directory (created if the user has templates checked out & flagged for testing). If so, the testing-template temporary directory paths will be interspersed with the deployed-template dirs (in the order of TEST/PROD/TEST/PROD).

• $txt = $publisher->page_break()
  
Returns the tag used internally to mark the break between pages in a story. When a multi-page story is assembled by the Krang::ElementClass element tree, it consists of a scaler containing these break tags. The preview/publish process will split the scaler along those tags to create the individual pages of the story.

No exceptions to throw.

• $txt = $publisher->content()
  
Returns the tag used internally to mark the break between the top and bottom sections of a category page. Once broken, the individual pages of a story will be placed in between the two halves, and the full HTML page will be assembled.

No exceptions to throw.

• $publisher->additional_content_block(filename => $filename, content => $html, use_category => 1);
  
additional_content_block creates an entry in the publisher that will be re-visited once the entire story content has been constructed. During the final output of the story, the content $html will be written out separately to $filename.

content and filename arguments are required.

use_category is a boolean flag that tells Krang::Publisher whether or not to add the current Krang::Category header/footer to the final output, as it will for the regular published output. Defaults to true.

category_tmpl_args is an optional hashref of keys/values to add to the $fill_template_args hashref passed to category's fill_template() method (which by default includes a single key/value pair, additional_content => $filename). this of course has no effect if use_category is set to 0.

mode is an optional parameter which will set the permissions of the file which is published. The mode should be specified in octal (NOT a string). If not specified, the mode of the published file will be based on the umask.

An optional post_process code ref may be supplied that will receive the created content as a scalarref after the optional category template has been applied.

If you want to write binary data (e.g. images), you must specify the 'binary' argument.

WARNING: additional_content_block() can be called as many times as desired, however it does not perform any sanity checks on filename - if your output contains multiple blocks of additional content with identical filenames, they will overwrite each other, and only the last one will remain.

• %vars = $publisher->publish_context(%set_params)
  
publish_context() provides a way to set and retrieve parameters in the Krang::Publisher object during the publish process for a single story.

publish_context() takes a hash of parameters for storage, and will return a hash of all stored parameters if called without arguments. Note that saving the same key-value pair multiple times will result in only the last variant being stored.

  # store 'foo => bar'
  $publisher->publish_context(foo => 'bar');

  # $vars{foo} is 'bar'
  my %vars = $publisher->publish_context();

  # foo is now 'baz'
  $publisher->publish_context(foo => 'baz');

Note - the internal hash used by publish_context() is cleared after every story is published - the variables stored here are not persistant across stories.

• $publisher->clear_publish_context()
  
Working in conjunction with publish_context() above, clear the internal hash.

Nothing is returned.

• $filename = $publisher->story_filename(page => $page_num);
  
Returns the filename (NOT the path + filename, just the filename) of the current story being published, given the page number.

Arguments:

• page
  
The page number of the story. Defaults to 0.
• story
  
Optional. Defaults to story(). Use it if you want a filename for something other than what is currently being published.

• $bool = $publisher->test_publish_status(object => $story, mode => 'publish')
  
Checks the current version of the object against its' stored preview_version or published_version. If the versions are not identical, it will return true, indicating that it should be published.

If the versions are identical, it will perform an additional check for Krang::Story objects, checking Krang::ElementClass::TopLevel->force_republish.

Will return 0 (false) if it determines that there is no rule indicating the asset should be published.

Arguments:

• object
  
The Krang::Story or Krang::Media object to be published.
• mode
  
Either 'preview' or 'publish'. If this is not set, it will check is_preview() and is_publish() for an indication of mode. If those are not set either, it will croak with an error.

• $url = $publisher->url_for(object => $story)
  
• $url = $publisher->url_for(object => $media)
  
• $url = $publisher->url_for(object => $category)
  
• $url = $publisher->url_for(object => $site)
  
• $url = $publisher->url_for(object => $object)
  
Returns the object's URL according to the publishing context. Object may be a Krang::Story, Krang::Media, Krang::Category, Krang::Site or any other object having both methods url() and preview_url() .

Returns the empty string if $object is not an object of any type.

Croaks if $object does not have both methods url() and preview_url() .

TODO

Nothing at the moment.

SEE ALSO

Krang::ElementClass, Krang::Category, Krang::Media