Publishing a document allows you to define a different viewing audience, properties, location of containment, and specific file and presentation format (which might or might not be different from the original source document). This section provides some conceptual information on the publishing objects exposed by the Content Engine APIs.
A publish style template serves as a template for a particular kind of transformation and is tied to a specific transformation engine on a specific object store. The publish style template describes how a transformation engine translates a source document into a different format, as opposed to simply copying the source document without transformation. (Note that a transformation engine can have more than one style template associated with it.) Information in the style template can be whatever is meaningful to that transformation engine. For example, the style template might include an XML-based description of the transformation to be done for this style template, an ID of another document that contains a more detailed template, or a URL for publishing to an external location. A style template also specifies a list of input formats (MIME types) supported for the style template as well as the output format (MIME type) generated when the style template is applied.
Style templates are created using either an administrative application (such as the HTML Transformation Engine Administrator supplied with the HTML Transformation Plug-in) or via the Content Engine APIs.
You can set and return properties on a PublishStyleTemplate
object that provide information about the style template. For example, some
properties specify the valid source document MIME types that can be transformed
(InputFormats property) and the document MIME type that will be produced (OutputFormat
property). A style template's TransformationEngine property specifies its transformation
engine, and its TransformationInstructions property contains transformation-engine-specific
instructions for processing documents.
A publish template is a document that contains template information used to automate the selection of options for a publishing request. These options include the optional style template to use and the properties and security to apply to the destination document. A publish template also provides some instructions for republishing a document, such as whether to version the existing destination document or replace it. Publish templates are authored in the Publishing Designer application.
The publish template can also specify dependency; that is, a publication can be dependent on the source document. This dependency controls cascade delete operations, in which the publication is automatically deleted when the source document is deleted. (The XML tag for dependency specification is <issourcedependent> with a value of "true" or "false".) For a code sample, see Creating a Publish Template Object.
The template information is an XML document and is a PublishTemplate
object's content. Because versioning is enabled on the PublishTemplate
class,
the XML content can be versioned. Also, because the PublishTemplate
extends Document
, you can work with a publish template in the
same way you work with a document (such as checking out the publish template,
setting its content, checking it back in, filing it into a folder, and deleting
it).
A PublishRequest
object represents a request to publish a document, and is created when you call publish
or republish
methods on a Document
object. The PublishRequest
object's InputDocument property refers to the specific document version being
published. In addition, its PublicationDocument property can refer to an existing
publication document in the republish case. (A requirement is that this document
must be published from some source document in the same version series as that
pointed to by InputDocument.)
Depending on how options are configured in the publish template used for the
publish operation, the existing publication document might be versioned to create
a new document version or an independent publication document in a new version
series. In either case, the existing publication document version might be removed
at the end of the publish operation depending on the options configured in the
publish template. A PublishRequest
object's PublishTemplate property tracks the publish template being used.
If the publish template has a publish style template (which is optional),
then the PublishRequest
object is persisted to the Content Engine server and
the PublishRequest
object's PublishStyleTemplate property is set. If you choose not to specify a
publish style template, then no transformation engine is specified and no transformation takes place. The publish request operation occurs
immediately, the PublishRequest
object reflects a completed status, and
the object does not represent a persisted request.
At some point during the publish operation, a target document is created that ultimately becomes the publication document.
A PublishRequest
object's OutputFolder property specifies the folder in which the
destination document is to be filed. If publishing to an external location,
that location is referenced as an external content reference element in
the destination document. The destination document will still be filed in the specified
output folder.
You can obtain information on the status of a PublishRequest
by querying its
properties. Its PublishingStatus property indicates whether the publish request is in the inQueue,
inWork, inError, Complete, or Deleting state. If the publish request is in the inError state, you can examine its ErrorCode and
ErrorDescription
properties for information on the error condition. For more information about each of the PublishRequest
object's properties, see PublishRequest Properties.