Developers > Kernel Documentation > Content Management > ContentData.pm

ContentData.pm

ContentData.pm : manage content revisions.

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:

current (or active)
The current revision is the most recently published revision. It is the revision that is approved for public view.

newest

The newest revision is the most recently added revision. It is a working copy that is not displayed to the public until it is published.

These may, of course, refer to the same revision.

Configuration & Setup

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:

id
The numeric content_data ID will be used to fetch the revision description from the database.

page
The content_data record can be passed as a hash reference, if it has already been fetched.

(null)
If no content_data description is provided, the object will configure an empty content_data object that will have limited functionality.

The setup methods are normally invoked automatically by the class contructor method new(), which receives the same %option parameters.

Revision Queries

defined()

Returns TRUE if the revision references actual web data. The data can be in one of the following forms:

raw data
Typically text data, stored in verbatim form.

file data
Encoded file upload, typically used for images. No check is performed that the file data decodes to a meaningful file format.

file
A path to a file stored outside the CMS. No check is performed that this file actually exists and is readable.

URL

A URL to a resource stored outside the system. No check is performed that this resource is accessible.

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.

Retrieving/Displaying Revisions

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($attributes,$url);

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).

You can optionally specify some custom attributes, or a URL to the content data. The system will specify suitable defaults for these values.

get_html_dynamic()

Same as previous, but forces the URL of content data to a dynamic representation.

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_static_url()

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 no such URL can be constructed.

get_dynamic_url()

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'').

Addressing Revisions

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.

Publishing

 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 C.  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.

publish_target_filename
The filename to publish to.

publish_target
The complete path, including filename, to 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:

from
This parameter contains a path to a temporary file that should be copied to the publication location.

fdata
This parameter contains an ExSite-encoded binary file that should be decoded and written to the publication location.

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().

Revision Management

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.

Topics