Index: openacs-4/packages/acs-content-repository/www/doc/guide/file-system.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/file-system.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-content-repository/www/doc/guide/file-system.adp 27 Oct 2014 16:39:15 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/guide/file-system.adp 7 Aug 2017 23:47:47 -0000 1.3 @@ -1,68 +1,89 @@ -{/doc/acs-content-repository {Content Repository}} {Content Repository Developer Guide: Organizing Content +{/doc/acs-content-repository {ACS Content Repository}} {Content Repository Developer Guide: Organizing Content Items} Content Repository Developer Guide: Organizing Content Items - - -

Organizing Content Items

The content repository organizes content items in a hierarchical +

Organizing Content Items

+ +ACS Documentation : Content Repository : Developer Guide +

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:

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 "file name" 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 +"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 "file name" 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:

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_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 analagous to +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 +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. Not -that 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 — +package's content nor will another package access your content. +Not that 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:

+own content root by calling content_folder.new in
+PL/SQL:
+ declare
   v_my_content_root integer;
 begin
@@ -74,20 +95,27 @@
   -- 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
+

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, +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.1.1.1 2001/03/13 22:59:26 -ben Exp $ - +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.1.1.1.30.2 2017/04/21 +14:53:08 gustafn Exp $