get_raw()get_html()get_url()get_url_static()get_url_dynamic()get_thumb_html()get_thumb_url()get_thumb_raw()preview()
A ContentData object is a particular revision of some piece of web content. It contains the actual, viewable web content (eg. HTML, image, other).
The terms ``ContentData'', ``content_data'', and ``revision'' are often used synonymously.
ContentData is part of the ExSite content stack, so it inherits from the ContentBase class, and is in turn inherited by the Content class. Each Content object contains a history list of content_data (revision) records. Each update to the content creates a new revision that is appended to this list.
Any number of revisions may be retained in the history, but there are two important revisions in this list:
These may, of course, refer to the same revision.
new()(This method is actually inherited from ExSite::ContentBase.)
setup()
setupContentData()Instantiate and/or configure a ContentData object. %option includes the
the configuration parameters, described below.
Usage:
my $rev = new ExSite::ContentData(%option);
$rev->setup(%option);
$rev->setupContentData(%option);
setup and setupContentData are synonymous; they are used to
setup or reconfigure an existing revision. new()
instantiates a new ContentData object (this method is actually
inherited from ExSite::ContentBase).
%option is used to pass the revision description information that
allows the object to be configured. It can include the following revision
description parameters:
The setup methods are normally invoked automatically by the class
contructor method new(), which receives the same %option
parameters.
defined()Returns TRUE if the revision references actual web data. The data can be in one of the following forms:
content_type()Returns the MIME type of the revision. This is taken directly from the content_data description, and not inferred from the data itself. Therefore, if the data has been incorrectly described, that incorrect description will be returned.
timestamp()Returns the creation time of the revision, in database (eg. MySQL timestamp) format.
is_file()Returns TRUE if the revision data is an encoded file upload.
is_image()Returns TRUE if the MIME type of the revision indicates that it is an image.
is_text()Returns TRUE if the MIME type of the revision indicates that it is text (ie. HTML, CSS, or plain text). Text data formats such as CSV or tab-delimited values will return FALSE.
is_publishable()Returns TRUE if the revision can be published to its own file. This is the case for all non-HTML MIME types.
get_fileinfo()Returns an array of the filename, size (in kilobytes), and MIME-type of the revision's encoded file. Returns undef if the revision is not an encoded file.
get_raw()Returns the raw data for the revision as a text or binary string. This can be printed to stdout to send it directly to the client, or manipulated by other code.
get_html()
my $html = $rev->get_html($mode);
Returns an HTML string to render the revision. For HTML revisions,
this is equivalent to get_raw(). Other MIME types will be
re-encoded to make them HTML-ready. Text types will be wrapped in
appropriate HTML tags to make them render appropriately. File types
will be converted to HTML tags that will allow the revision to be
downloaded in a separate request (eg. an IMG tag).
$mode can optionally be specificed to force ``dynamic'' or ``static''
representations of the content. This is meaningful for secondary files
(eg. images) only.
get_url()
$url = $rev->get_url($mode);
Returns a URL to fetch the revision in a stand-alone HTTP request. This is used to set up the SRC and HREF attributes in IMG, LINK, and A tags.
The returned URL may be static, if the revision has been published to
its own file, or dynamic if it must be read from the database.
The choice can be forced by passing the optional $mode parameter.
Dynamic URLs use the content.cgi program to fetch the data.
get_url_static()Returns a URL to fetch the revision in a stand-alone HTTP request. The URL is always to the static, published file, or to a dummy checker graphic, if not.
get_url_dynamic()Returns a URL to fetch the revision in a stand-alone HTTP request. The URL is always to the dynamic version of the content, or to a dummy checker graphic, if no such URL can be constructed.
get_thumb_html()Same as get_html() except that it returns an HTML string to render
a thumbnail of the content.
The revision data may include an explicit thumbnail, in which case
this is used. Otherwise, if the revision is an image, we simply
return the image with reduced dimensions. If the revision is not an
image, and no explicit thumbnail is provided, we return get_html().
get_thumb_url()Same as get_url() except that it returns a URL to the thumbnail.
If no explicit thumbnail exists, this returns the same result as
get_url().
get_thumb_raw()Returns the raw data for the thumbnail as binary string. Only works
if an explicit thumbnail is defined, otherwise undef is returned.
preview()
my $html = $rev->preview($mode);
Returns HTML that comprises an administrator preview of the revision.
Similar to get_html(), except that it allows for expansion of CMS
tags to show other embedded content objects, and for the viewing of
raw HTML ($mode = ``raw'').
filename()Returns a file name for the revision. If the revision is not already a file, then a filename is composed from the content ID and MIME type.
Note that content objects are often named for the original file name in their first revision. However, as the content gets updated, new files may be uploaded with different names. The content object name remains the same, but the revision filename will change. For example, a content object named ``logo.gif'' may eventually resolve to an actual file named ``logo-64px-BW.jpg''. This can be confusing when first encountered.
httppath()Returns the URL path to the file (ie. the part of the static URL after the host name), not including the filename itself. This is identical to the httppath to the page contianing the content.
diskpath()Returns the full disk path to the file, including the filename.
If the content belongs to a regular page, the file will be published into the general section directory. That could result in filename conflicts, which would cause different content objects under different pages, to publish to the same file. In this case, one will overwrite the other, and you will get unexpected results.
WARNING: you need write access to the publication directories to
publish files. The webserver normally does not have this access.
Negotiating this access is normally done by the publish program
(ie. publish.cgi), which has special permissions. If you do not have
these permissions, then you have to ask publish.cgi to do this task on
your behalf, using ExSite::Util::run_publisher(). The publish
program does not have access to specific revisions; you can only ask
it to publish a Content object, which will publish the newest revision
of the content.
set_publish_target()
my $target = $rev->set_publish_target($path,$filename);
Determines where a revision's file will be published. The path and
filename can be passed explicitly, or it will be inferred from the
diskpath() and filename(). The full path to be published to
will be returned, but the target will also be stored in the revision
object under the following attributes:
A revision in isolation has no context to determine where it ought to
be published, so this method must be called before you can publish.
This is done automatically by ExSite::Page::publish(), which can
inform the revisions which directory the page's files will publish to.
is_published()Returns the timestamp from the last time the content was published. If never published, returns 0. This is suitable for a simple logical test for whether the revision has been published.
publish()
my $status_message = $rev->publish($path,$filename);
Publishes the revision, and returns a text string reporting the status of the operation.
The publication $path and $filename can be passed explicitly,
but this is optional if we have a full context to determine which page
this content revision belongs to.
Publication of a revision accomplishes two things:
1) It writes out the revision's file(s) to disk. If the revision
includes a thumbnail, it will also be written.
2) It marks the revision as published and therefore viewable by the public.
There is one special case worth noting: if the revision refers to an external file, then this file is assumed to already exist on disk and in theory does not need to be published. However, the CMS falls back on this method of revision storage for revisions that are too large for storage in the database. In this case, the file may not yet exist on disk because it has just been uploaded. So we check in the POST data for possible replacements for this file, under the following parameters:
unpublish()Removes the revision's file and thumbnail from disk. It will fail if the file is located outside the system HTMLroot. (This is not considered a bug, because those files are technically outside the CMS and should not be deleted by the CMS.)
mkdir()
my $status_message = $rev->mkdir($path);
Creates the directories in path, if they do not exist. It will only
create directories inside the system's HTMLroot for security reasons.
If you need to create directories outside this area, you must untaint
the $path yourself before passing it to mkdir().
rmdir()
my $status_message = $rev->rmdir($path);
Deletes the directory in $path, if it exists. It will only
delete directories inside the system's HTMLroot for security reasons.
If you need to remove directories outside this area, you must untaint
the $path yourself before passing it to rmdir().
rm()
my $status_message = $rev->rm($path);
Deletes the file specified by $path, if it exists. It will only
delete directories inside the system's HTMLroot for security reasons.
If you need to remove files outside this area, you must untaint
the $path yourself before passing it to rm().
validate()
my @errors = $rev->validate($revdata);
if (@errors == 0) { # revision is OK }
Returns TRUE if the values in the the $revdata hashref comprise
a valid and legal revision description. Returns an array of error
messages, which will be empty if the revision validates.
make()
make_content_data()$section->make($revdata,$options);
Creates a new revision using the attributes in the $revdata hashref.
The information in $revdata is validated, and authorization checks
are performed to ensure the user has update privileges. The data may
be further modified as follows:
write_to_file()
$rev->write_to_file($content_id,$data);
Write a file straight to disk. This is used when an oversized file
was passed to make() which could not be stored in the database.
Instead, we repost the file to publish.cgi, which will take care of
writing it direct to disk. $content_id tells the publish program
where this file belongs, and $data is the ExSite-encoded file data.
restore()Creates a new revision that is identical to this revision. This is used to ``restore'' an old revision to use, without rolling back through all the intermediate revisions.
delete()Deletes the revision from the database. Does not attempt to unpublish it. This is functionally equivalent to ``rolling back'' to the previous revision (which will now be the newest revision).
purge()Deletes all but this revision from the database.