Publishing Concepts

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.

Publish Style Template

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.

Publish Template

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

Publish Request

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.