Krang::Publisher - Center of the Publishing Universe.
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');
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.
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:
Returns a 1 if the current publish run is in preview-mode, 0 otherwise.
Returns a 1 if the current publish run is in publish-mode (e.g. going live), 0 otherwise.
Returns a Krang::Category object for the category currently being published.
Returns a Krang::Story object for the Story currently being published.
$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:
$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:
$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() .
Nothing at the moment.