<font size="+1">Function:</font> content_keyword.new</li></ul><p>Creates a new keyword (also known as "subject category").</p><table cellpadding="3" cellspacing="0" border="0">
</ul><p> </p><h3><a name="overview">Overview</a></h3><p>Content revisions contain the data for content items. There is a
</ul>
<p> </p>
<h3><a name="overview">Overview</a></h3>
<p>Content revisions contain the data for content items. There is a
many to one relationship between content revisions and content
items. There is at most one "live" revision for every content item
though. For example, there may be 5 revisions of the review for the
movie "Terminator," yet only one of these may be live on the
website at a given time.</p><p> </p><h3><a name="related">Related Objects</a></h3>
website at a given time.</p>
<p> </p>
<h3><a name="related">Related Objects</a></h3>
See also: {content_item }
<p> </p><h3><a name="api">API</a></h3><ul><li>
<font size="+1">Function:</font> content_revision.copy</li></ul><p>Creates a new copy of an attribute, including all attributes</p><table cellpadding="3" cellspacing="0" border="0">
<font size="+1">Function:</font> content_revision.new</li></ul><p>Create a new revision for an item.</p><table cellpadding="3" cellspacing="0" border="0">
<font size="+1">Procedure:</font> content_revision.to_html</li></ul><p>Converts a revision uploaded as a binary document to html</p><table cellpadding="3" cellspacing="0" border="0">
<font size="+1">Function:</font> content_symlink.new</li></ul><p>Create a new symlink, linking two items</p><table cellpadding="3" cellspacing="0" border="0">
<font size="+1">Function:</font> content_symlink.resolve</li></ul><p>Resolves the symlink and returns the target item id.</p><table cellpadding="3" cellspacing="0" border="0">
<p>Serving <em>content</em> is a basic function of any web site.
Common types of content include:</p>
<ul>
<li>Journal articles and stories</li><li>Documentation</li><li>News reports</li><li>Product reviews</li><li>Press releases</li><li>Message board postings</li><li>Photographs</li>
</ul><p>Note that the definition of content is not limited to what is
</ul>
<p>Note that the definition of content is not limited to what is
produced by the publisher. User-contributed content such as
reviews, comments, or message board postings may come to dominate
active community sites.</p><p>Regardless of its type or origin, it is often useful for
active community sites.</p>
<p>Regardless of its type or origin, it is often useful for
developers, publishers and users to handle all content in a
consistent fashion. Developers benefit because they can base all
their content-driven applications on a single core API, thereby
...
...
@@ -20,28 +25,36 @@ Publishers benefit because they can subject all types of content to
the same management and production practices, including access
control, workflow, categorization and syndication. Users benefit
because they can enjoy a single interface for searching, browsing
and managing their own contributions.</p><p>The content repository itself is intended <em>only</em> as a
and managing their own contributions.</p>
<p>The content repository itself is intended <em>only</em> as a
common substrate for developing content-driven applications. It
provides the developer with a core set of content-related
services:</p><ul>
services:</p>
<ul>
<li>Defining arbitrary content types.</li><li>Common storage of content items (each item consists of a text
or binary data with additional attributes as specified by the
content type).</li><li>Establishing relationships among items of any type.</li><li>Versioning</li><li>Consistent interaction with other services included in the ACS
<property name="context">{/doc/acs-content-repository {Content Repository}} {Content Repository Developer Guide: HTML Conversion}</property>
<property name="doc(title)">Content Repository Developer Guide: HTML Conversion</property>
<master>
<body>
<h2>Converting Binary Documents to HTML</h2><p>The content repository uses the INSO libraries included with
<h2>Converting Binary Documents to HTML</h2>
<p>The content repository uses the INSO libraries included with
Intermedia to support conversion of binary files such as Microsoft
Word documents to HTML. This document describes how to make this
conversion be part of the item creation or editing process, such
that the content is always stored in the repository as HTML.</p><p>
that the content is always stored in the repository as HTML.</p>
<p>
<b>Note:</b> Because temporary tables and LOB storage are used
during the conversion process, the entire process described here
must be performed within the context of a single transaction.</p><h3>Create the Revision</h3><p>The first step is to create the revision that will be associated
must be performed within the context of a single transaction.</p>
<h3>Create the Revision</h3>
<p>The first step is to create the revision that will be associated
with the converted document, and obtain the corresponding ID. The
<tt>content</tt> column for the revision must be initialized with
<h2>Organizing Content Items</h2><p>The content repository organizes content items in a hierarchical
<h2>Organizing Content Items</h2>
<p>The content repository organizes content items in a hierarchical
structure similar to a file system. You manage content items in the
repository using the same basic operations as in a file system:</p><ul>
repository using the same basic operations as in a file system:</p>
<ul>
<li>A freshly installed content repository consists of a single
"root" folder (analogous to the root directory <tt>/</tt> in UNIX
or an empty partition in Windows or MacOS).</li><li>You organize items by creating subfolders under the root.</li><li>You can move or copy items from one folder to another.</li><li>You can create "links" or "shortcuts" for items to make them
...
...
@@ -16,7 +16,8 @@ accessible from within other directories.</li><li>Each item has a "file name" an
determined by its location on a particular branch of the repository
tree. For example, the path to an item named <tt>widget</tt> in the
folder <tt>products</tt> would be <tt>/products/widget</tt>.</li>
</ul><p>The content repository adds an additional twist to a traditional
</ul>
<p>The content repository adds an additional twist to a traditional
filesystem: <em>any</em> content item, not just a folder, may serve
as a container for any number of other content items. For example,
imagine a book consisting of a preface, a number of chapters and a
...
...
@@ -24,14 +25,20 @@ bibliography (which in turn may have any number of entries). The
book itself is a content item, in that it has attributes
(publisher, ISBN number, publication date, synopsis, etc.)
associated with it. It also is the logical container for all its
components.</p><p>It is important to note that folders are simply a special
components.</p>
<p>It is important to note that folders are simply a special
subtype of content item. The content repository's representation of
a parent-child relationship between a folder and the items it
contains is no different from the relationship between a book and
its chapters. Folders may be thought of simply as generic
containers for grouping items that are not necessarily part of a
greater whole.</p><h3>An Example</h3><p>Consider a simple repository structure with the following
contents:</p><img src="organization.gif" height="360" width="440" border="1"><p>Note the following:</p><ul>
greater whole.</p>
<h3>An Example</h3>
<p>Consider a simple repository structure with the following
<h2>Object Relationships</h2><p>Many applications of the content repository require that content
<h2>Object Relationships</h2>
<p>Many applications of the content repository require that content
items be related to each other as well as to other classes of
objects. Examples include:</p><ul>
objects. Examples include:</p>
<ul>
<li>News stories may be linked to other stories on the same
topic.</li><li>An article may be linked to any number of photos or charts that
are embedded in the article.</li><li>A long article is divided into multiple sections, each of which
is intended for separate display.</li><li>Product reviews are linked to specific products.</li><li>User portraits are linked to specific users.</li>
</ul><p>The ACS kernel provides a standard, highly flexible data model
</ul>
<p>The ACS kernel provides a standard, highly flexible data model
and API for relating objects to other objects. If you have a highly
specific problem and are developing your own user interface on the
content repository, you can use the ACS relationships framework
directly. The relationship framework in the content repository
itself is simply intended as a convenience for handling common
relationship situations involving content items.</p><h3>Parent-Child Relationships</h3><p>In many cases one content item may serve as a natural container
<h2>Publishing Content</h2><p>The content repository does not place any restrictions on the
<h2>Publishing Content</h2>
<p>The content repository does not place any restrictions on the
methods employed for delivering content via a public server
infrastructure. Applications are free to query the repository and
process the data in any way desired.</p><p>Although there are no restrictions on publishing methodology,
process the data in any way desired.</p>
<p>Although there are no restrictions on publishing methodology,
the repository API is intended to facilitate generic template-based
publication, regardless of the specific presentation layer used.
The following diagram illustrates the steps typically involved in
such a publication process:</p><img src="flow.gif" border="1"><p>In general, there is an initial <em>resolution</em> step in
such a publication process:</p>
<img src="flow.gif" border="1">
<p>In general, there is an initial <em>resolution</em> step in
which the server must identify the appropriate content item and
then decide which template to actually parse. Following that is an
<em>execution</em> step, during which setup tasks associated with
the template are performed. Finally, the <em>merging</em> step
combines the data and layout into a rendered page.</p><h3>Matching URLs to Content Items</h3><p>The primary mechanism for matching URLs to Content Items are
combines the data and layout into a rendered page.</p>
<h3>Matching URLs to Content Items</h3>
<p>The primary mechanism for matching URLs to Content Items are
<em>virtual URL handlers</em>, <tt>.vuh</tt> files. An explanation
of virtual URL handlers can be found in the tutorial on the
<a href="/doc/request-processor">Request Processor</a>.</p><p>Here is an example <tt>index.vuh</tt> file that you can adapt to
</pre><p>The <tt>content_root</tt> and <tt>template_root</tt> parameters
</pre>
<p>The <tt>content_root</tt> and <tt>template_root</tt> parameters
select the content and template root folders. In the example, they
are just the default roots that the content repository initializes
on installation. If you want to store your content completely
independent from that of other packages, you can initialize your
own content root and pass that folder's ID on to
<tt>content::init</tt>.</p><p>To publish content through URLs that are underneath
<tt>/mycontent</tt> you need to do the following:</p><ol>
<tt>content::init</tt>.</p>
<p>To publish content through URLs that are underneath
<tt>/mycontent</tt> you need to do the following:</p>
<ol>
<li>Create a directory <tt>mycontent</tt> in your server's page
root and an <tt>index.vuh</tt> file in that directory.</li><li>Adapt the <tt>set content_root ...</tt> and <tt>set
template_root ..</tt> statements in the example above so that they
...
...
@@ -60,11 +69,16 @@ want to publish content from.</li><li>Change the <tt>set the_url ...</tt> statem
variable <tt>the_url</tt> contains the absolute path to the content
item you wish to serve from your (or the default) content
root.</li>
</ol><p>If you use the example <tt>index.vuh</tt> file above unaltered
</ol>
<p>If you use the example <tt>index.vuh</tt> file above unaltered
for requests to <tt>my_content</tt>, a request for
<tt>http://yourserver/mycontent/news/articles/42</tt> would request
the content item <tt>/news/articles/42</tt> from the content
repository on the default content root folder.</p><h3>Matching Content Items to Templates</h3><h3>Querying Content</h3><h3>Querying Attributes</h3><p>When you create a new content type or add an attribute to an
repository on the default content root folder.</p>
<h3>Matching Content Items to Templates</h3>
<h3>Querying Content</h3>
<h3>Querying Attributes</h3>
<p>When you create a new content type or add an attribute to an
existing content type, a view is created (or recreated) that joins
the attribute tables for the entire chain of inheritance for that
content type. The view always has the same name as the attribute
...
...
@@ -73,24 +87,34 @@ from the table itself (for example, if the attribute table for
<b>Press Releases</b> is <tt>press_releases</tt>, then the view
will be named <tt>press_releasesx</tt>. Querying this view is a
convenient means of accessing any attribute associated with a
content item.</p><p>As a shortcut, the item's template may call
content item.</p>
<p>As a shortcut, the item's template may call
<tt>content::get_content</tt> in its Tcl file in order to
automatically retrieve the current item's attributes. The
attributes will be placed in a onerow datasource called
<tt>content</tt> . The template may then call
<tt>template::util::array_to_vars content</tt> in order to convert
the onerow datasource to local variables.</p><p>In addition to the "x" view, the Content Repository creates an
the onerow datasource to local variables.</p>
<p>In addition to the "x" view, the Content Repository creates an
"i" view, which simplifies the creation of new revisions. The "i"
view has the same name as the content table, with "i" appended at
the end. You may insert into the view as if it was a normal table;
the insert trigger on the view takes care of inserting the actual
values into the content tables.</p><h3>Querying Additional Data</h3><p>Templates often display more than simple content attributes.
values into the content tables.</p>
<h3>Querying Additional Data</h3>
<p>Templates often display more than simple content attributes.
Additional queries may be necessary to obtain data about related
objects not described directly in attribute tables. The setup code
associated with a template typically performs these queries after
the initial query for any needed attributes.</p><h3>Merging Data with Templates</h3><h3>Returning Output</h3><ol>
the initial query for any needed attributes.</p>
<h3>Merging Data with Templates</h3>
<h3>Returning Output</h3>
<ol>
<li>Write to the file system</li><li>Service public requests directly</li>
</pre><h3>Insert additional attributes</h3><p>Given that there is no way (AFAIK) to pass variable parameters
</pre>
<h3>Insert additional attributes</h3>
<p>Given that there is no way (AFAIK) to pass variable parameters
to a PL/SQL function, there is no way to make
<tt>content_revision.new</tt> generic enough to support submission
of the attributes for all different content types. This leaves you
with three alternatives:</p><ol>
with three alternatives:</p>
<ol>
<li>Call <tt>content_revision.new</tt> followed by manual DML
statements to write data into the content BLOB and insert
attributes.</li><li>Write a PL/SQL package for each of your content types, which
encapsulates the above code.</li><li>Create revisions by inserting into the attribute view for each
content type.</li>
</ol><p>The last option is made possible by an <tt>instead of
</ol>
<p>The last option is made possible by an <tt>instead of
insert</tt> trigger on the attribute view for each content type.
(An <em>attribute view</em> joins together the storage tables for
the ancestors of each content type, including <tt>acs_objects</tt>
...
...
@@ -68,32 +78,44 @@ code to create or replace the trigger is automatically generated
and executed with each call to
<tt>content_type.create_attribute</tt>. The trigger makes it
possible to create complete revisions with a single insert
statement:</p><pre>
statement:</p>
<pre>
insert into cr_revisionsx (
item_id, revision_id, title
) values (
18, 19, 'All About Revisions'
);
</pre><p>Because a special trigger is generated for each content type
</pre>
<p>Because a special trigger is generated for each content type
that includes insert statements for all inherited tables, revisions
with extended attributes may be created in the same fashion:</p><pre>
with extended attributes may be created in the same fashion:</p>
<pre>
insert into cr_imagesx (
item_id, revision_id, title, height, width
) values (
18, 19, 'A Nice Drawing', 300, 400
);
</pre><h3>Inserting content via file or text upload</h3><h3>Selecting a live revision</h3><p>The live revision of a content item can be obtained with the
</pre><p>The URL and title may be used to construct a hyperlink directly
to the item.</p><p>You may implement any number of variants on this basic query to
</pre>
<p>The URL and title may be used to construct a hyperlink directly
to the item.</p>
<p>You may implement any number of variants on this basic query to
place additional constraints on the results, such as publication
date, content type, subject heading or a particular attribute (see
below).</p><p>Some limitations of the current implementation include:</p><ul>
below).</p>
<p>Some limitations of the current implementation include:</p>
<ul>
<li>Multilingual searches are not enabled by default. You may
enable them for one more languages by setting the appropriate
Intermedia preferences when creating
...
...
@@ -47,10 +56,14 @@ probably a limitation of <tt>content_item.get_path</tt>: it should
be possible to specify an arbitrary function to return the path for
items of a particular content type, with
<tt>content_item.get_path</tt> as the default.</li>
</ul><h3>Searching Attributes</h3><p>This task is primarily handled to two Intermedia indices:</p><p>Providing a generic mechanism for searching attributes is
</ul>
<h3>Searching Attributes</h3>
<p>This task is primarily handled to two Intermedia indices:</p>
<p>Providing a generic mechanism for searching attributes is
complicated by the fact that the attributes for each content type
are different. The content repository takes advantage of the XML
features in Oracle 8.1.6 to address this:</p><ol>
features in Oracle 8.1.6 to address this:</p>
<ol>
<li><p>After creating a new revision and inserting attributes into the
storage table for the content type and all its ancestors, you must
execute the <tt>content_revision.index_attributes</tt> procedure.
...
...
@@ -63,15 +76,19 @@ using the Oracle XML Parser for Java v2 is used to actually
generate the XML document.</p></li><li><p>A special Intermedia index configured to parse XML documents is
built on the column containing the XML documents for all
revisions.</p></li>
</ol><p>The Intermedia index allows you to use the WITHIN operator to
search on individual attributes if desired.</p><pre>
</ol>
<p>The Intermedia index allows you to use the WITHIN operator to
search on individual attributes if desired.</p>
<pre>
select
revision_id,score(1)
from
cr_revisions
where
contains(attributes, 'company WITHIN title', 1) > 0
</pre><p>Some limitations of the current implementation include:</p><ol>
</pre>
<p>Some limitations of the current implementation include:</p>
<ol>
<li>A <tt>USER_DATASTORE</tt> associated with each row of the
<tt>cr_items</tt> table, which feeds Intermedia the contents of the
<tt>content</tt> column (a BLOB) for the <em>live</em> revision of
...
...
@@ -86,7 +103,10 @@ also be able implement custom handlers, to allow the XML document
to reflect one-to-many relationships or special formatting of
attributes as well. The handler should specify a java class and
method, which a dispatch method can call by reflection.</li>
<h2>Applying Templates</h2><p>The content repository allows you to associate templates with
<h2>Applying Templates</h2>
<p>The content repository allows you to associate templates with
both content types and individual content items. A template
determines how a content item is rendered when exported to the file
system or served directly to a client.</p><p>The content repository does not make any assumptions about the
system or served directly to a client.</p>
<p>The content repository does not make any assumptions about the
type of templating system used by the application server with which
it is being used. Templates are simply made available to the
application server as text objects. The server is responsible for
merging the template with the actual content.</p><h3>Creating templates</h3><p>The content repository handle templates as a special class of
merging the template with the actual content.</p>
<h3>Creating templates</h3>
<p>The content repository handle templates as a special class of
text object. The interface for handling templates builds on that of
simple content items:</p><pre>
simple content items:</p>
<pre>
template_id := content_template.new(
name => 'image_template',
parent_id => :parent_id
);
</pre><p>The name represents the tail of the location for that content
</pre>
<p>The name represents the tail of the location for that content
template. The parent ID must be another content item, or a subclass
of content item such as a folder.</p><p>
of content item such as a folder.</p>
<p>
<tt>The content_template.new</tt> function accepts the standard
<tt>creation_date</tt>, <tt>creation_user</tt>, and
<tt>creation_ip</tt> auditing parameters.</p><p>Content items and templates are organized in two separate
<tt>creation_ip</tt> auditing parameters.</p>
<p>Content items and templates are organized in two separate
hierarchies within the content repository. For example, you may
place all your press releases in the <tt>press</tt> folder under
the item root (having the ID returned by
<tt>content_item.get_root_folder</tt>). You may have 5 different
templates used to render press releases. These my be stored in the
<tt>press</tt> folder under the <em>template</em> root (having the
ID returned by <tt>content_template.get_root_folder</tt>).</p><p>Templates are placed under their own root to ensures that bare
ID returned by <tt>content_template.get_root_folder</tt>).</p>
<p>Templates are placed under their own root to ensures that bare
templates are never accessible via a public URL. This is also done
because the relationship with the file system may be different for
templates than for content items. For example, templates may be
associated with additional code or resource files that developers
maintain under separate source control.</p><h3>Associating templates with content types</h3><p>You use the <tt>content_type.register_template</tt> procedure to
associate a template with a particular content type:</p><pre>
maintain under separate source control.</p>
<h3>Associating templates with content types</h3>
<p>You use the <tt>content_type.register_template</tt> procedure to
associate a template with a particular content type:</p>
<pre>
content_type.register_template(
content_type => 'content_revision',
template_id => :template_id,
use_context => 'public',
is_default => 't'
);
</pre><p>The <tt>use_context</tt> is a simple keyword that specifies the
</pre>
<p>The <tt>use_context</tt> is a simple keyword that specifies the
situation in which the template is appropriate. One general
context, <tt>public</tt>, is loaded when the content repository is
installed. Templates in this context are for presenting content to
users of the site. Some sites may wish to distinguish this further,
for example using <tt>intranet</tt>, <tt>extranet</tt> and
<tt>public</tt> contexts.</p><p>The <tt>is_default</tt> flag specifies that this template will
<tt>public</tt> contexts.</p>
<p>The <tt>is_default</tt> flag specifies that this template will
serve as the default template in the case that no template is
registered to a content item of this content type and this use
context. Any content type/context pair may have any number of
templates registered to it, but there can be only one default
template per pair.</p><p>To make a template the default template for a content
type/context pair:</p><pre>
template per pair.</p>
<p>To make a template the default template for a content
type/context pair:</p>
<pre>
content_type.set_default_template(
content_type => 'content_revision',
template_id => :template_id,
use_context => 'public'
);
</pre><h3>Associating templates with content items</h3><p>Individual items may also be associated with templates using the
<h2>Defining Content Types</h2><p>The content repository requires you to define each type of
<h2>Defining Content Types</h2>
<p>The content repository requires you to define each type of
content supported by your supplication. Content types are defined
as <a href="?">ACS Object Types</a>, and may be created in the same
fashion as any other object type. This page provides some specific
examples and details related to defining ACS object types in the
context of the content repository.</p><h3>Determine content attributes</h3><p>A content item typically consists of two components:</p><ol>
context of the content repository.</p>
<h3>Determine content attributes</h3>
<p>A content item typically consists of two components:</p>
<ol>
<li>Text or binary data stored as a single object</li><li>Structured attributes stored as distinct values</li>
</ol><p>Note that a content type does <em>not</em> have to store its
</ol>
<p>Note that a content type does <em>not</em> have to store its
primary content in the <tt>BLOB</tt> column of the
<tt>cr_revisions</tt> table. There is some additional overhead
associated with retrieving small passages of text from the BLOB
...
...
@@ -22,18 +25,22 @@ difference is trivial (fewer than about 10 microseconds), but if
many items must be queried at the same time the difference may
become significant. If the primary content will always be small, it
is perfectly acceptable to store the content in an attribute column
instead.</p><p>Basic attributes for all content types are stored in the
instead.</p>
<p>Basic attributes for all content types are stored in the
<tt>cr_revisions</tt> (note that they are stored in the revisions
table so that attributes may be updated for each new revision of
the actual data). Most types of content require more than the basic
attributes. For example, when storing images you will usually want
to store the pixel height and width so that images can be selected
and sorted by size, as well as displayed efficiently.</p><h3>Create an attribute table</h3><p>Extended attributes associated with ACS object types may be
and sorted by size, as well as displayed efficiently.</p>
<h3>Create an attribute table</h3>
<p>Extended attributes associated with ACS object types may be
stored as key-value pairs in a central table (generic storage), or
in a custom table whose primary key references the associated ACS
object ID (specific storage). To ensure efficient access to
attributes, the content repository API requires you to use specific
storage. Your table should have the form:</p><pre>
</ol><h3>Java</h3><p>In additional to SQL and PL/SQL, the content repository
</ol>
<h3>Java</h3>
<p>In additional to SQL and PL/SQL, the content repository
implements a limited set of key methods in Java. The XML import and
export methods are dependent on Oracle's XML Parser for Java v2,
available from the Oracle Technology Network:</p><a href="http://technet.us.oracle.com/tech/xml/parser_java2/index.htm"><tt>http://technet.us.oracle.com/tech/xml/parser_java2/index.htm</tt></a><p>To load the XML parser, download and untar the distribution.
