Organizing Content Items

ACS Documentation : Content Repository : Developer Guide

The content repository organizes content items in a hierarchical structure similar to a filesystem. You manage content items in the repository using the same basic operations as in a filesystem:

• A freshly installed content repository consists of a single "root" folder (analogous to the root directory / in UNIX or an empty partition in Windows or macOS).
• You organize items by creating subfolders under the root.
• You can move or copy items from one folder to another.
• You can create "links" or "shortcuts" for items to make them accessible from within other directories.
• Each item has a "filename" and an absolute "path" that is determined by its location on a particular branch of the repository tree. For example, the path to an item named widget in the folder products would be /products/widget.

The content repository adds an additional twist to a traditional filesystem: any 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 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.

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.

An Example

Consider a simple repository structure with the following contents:

Note the following:

• The root folder of the content repository has a special ID which is returned by the function content_item.get_root_folder.
• Regular content items such as index and about may be stored directly under the root folder.
• The "About Us" page has a photo as a child item. Note that the path to the photo is /about/photo. Internally, the photo's parent_id (in the cr_items table) is set to the item_id of the "About Us" page.
• The "Press" folder contains two items. Internally, the parent_id of the "Press Index" and "Release One" items are set to the item_id of the "Press" folder.

Note that the same effective organization could have been achieved by creating the "Press Index" item under the root, and having press releases as its children. Using the folder approach may have the following advantages:

• Content management systems can take advantage of the folder structure to implement an intuitive user interface analogous to familiar desktop tools (Windows Explorer, macOS Finder, etc.).
• You can use the content repository API to constraint the type of content that a folder may contain (except for the index page). For example, it is possible to limit the contents of the "Press" folder to items of type "Press Release." See the Content Folder API for more details.

Using your own root

By default, the content repository has one root folder for content items and one for templates. In some situations, that is not enough. For example, a package that can be instantiated several times might wish to store the content for each instance in its own content root. Creating your own content (and template) root also has the advantage that you will not accidentally access another package's content nor will another package access your content. Note that could do any harm, because you have secured all your content through appropriate permissions.

We only talk about creating content roots from here on — creating template roots is completely analogous. You create your own content root by calling content_folder.new in PL/SQL:

declare
  v_my_content_root integer;
begin
  v_my_content_root := content_folder.new(
     name => 'my_root', 
     label => 'My Root', 
     parent_id => 0
  );
  -- Store v_my_content_root in a safe place
end;
/ 

The important point is that you have to pass in 0 for the parent_id. This parent_id is special in that it indicates folders with no parent.

The content repository does not keep track of who created what root folders. You have to do that yourself. In the above example, you need to store the value v_my_content_root somewhere, for example a table that is specific for your package, otherwise you won't have a reliable way of accessing your new content root.

With multiple content roots, there can be many items with item_path'/news/article' and you need to tell the content repository which root you are talking about. For example, to retrieve content through content_item.get_id, you pass the id of your content root as the root_folder_id parameter to specify the content root under which the item_path should be resolved.

---

karlg@arsdigita.com
Last Modified: $‌Id: file-system.html,v 1.4.2.1 2021/04/05 19:49:49 gustafn Exp $