Index: openacs-4/contrib/packages/bcms/www/doc/bcms_dev_doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/packages/bcms/www/doc/bcms_dev_doc.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/packages/bcms/www/doc/bcms_dev_doc.html 3 Dec 2003 16:39:45 -0000 1.1 @@ -0,0 +1,126 @@ + + +
+ +
+
+
This +document serves as a high-level overview why and how BCMS and BCDS is +designed and implemented. Though it is a developer document, it does +not go into the details to lessen the chances of the document being +irrelevant when implementation details are changed. Detailed +document can be seen in the api document.
+
+
+
BCMS and +BCDS goal is to help implement a CMS solution in a smaller time frame +than building your own CMS solution. Normally each organization will +have a different way of looking at how they want to use their CMS. +Therefore CMS UI will vary from one organization to another, even +though functionally they are similar. So BCMS tries to help the +developer to create varying UI. OpenACS was chosen as its platform +due to the fact that its Content Repository (a CMS core engine) is +sound and additional none-CMS functionality can easily be added.
+
+
+
BCMS is +made of 3 packages.
+
+
Basic +Content Management System (BCMS) - core tcl api that just exposes +Content Repository (CR) functions in Tcl. Makes CR more accessible. +For example to upload a file, in CR you will call about 2-3 plsql and +sql statements. Here you call one Tcl function. There is nothing +revolutionary about it BCMS.
+
+
BCMS uses +standard set of naming get_X, create_X, set_X, delete_X, list_Xs, +tree_Xs. See bcms standards document.
+
+
BCMS does +not discourage you to use the CR directly, it just gives you more +help in the common operations in CR.
+
+
BCMS-UI-* +- this packages are the package that calls the BCMS Tcl procs. It a +UI package. You set which folder you want to manage in CR, template +folder in CR and context. It is possible to manipulate the same data +in CR with 2 or more packages that has very different UI. This +package will contain forms, wizards, etc. that manages the content in +CR with a great help of BCMS Tcl procs.
+
+
BCDS - The +package that gets content out and displays it. Just like +BCMS-UI-* packages you tell the a BCDS package which folder in CR you +would like to serve and at what context. Caching of content items or +making portals are done in this package.
+
+
Its also +possible that both BCMS-UI-* and BCDS be implemented in a single +package.
+
+
+
Here is +currently a picture of CR that is managed by 2 BCMS-UI packages and 2 +BCDS packages. Bcms-ui-site-manager is the UI that manages the +public site for Company X. This is normally used by the marketing +group. Bcds-main-site is the package that renders the public site to +visitors of Company X site. Since the site is very heavy on graphics +and has lots of presentation another BCDS package renders the site +for the intranet. Which normally does not need eye candy. Also +bcds-intranet may present or retrieve differently, for example +Products and Services maybe displayed in a long functional table that +has sortable columns as opposed to the categorized and much simple +public site that is served by bcds-main-site. In Company X the +product management group works very differently from the marketing +group which handles Company X Site. The product management group +uses their own UI by using bcms-ui-product-management package. This +package is not able to publish a content, but a workflow is created +to be sent to a marketing group staff to publish a content to be seen +by bcds-main-site.
+
+
+
This +document gives a guideline what was used in bcms. There maybe +exceptions but more or less the following standards was followed.
+As much as +possible i used a standard set of names.
+create_X, +get_X, set_X, delete_X, list_Xs, tree_Xs.
+For +example: create_folder, get_folder, set_folder, delete_folder, +list_folders, tree_folders.
+
+
create_X – +is to create an object (e.g. Item, revision, folder, etc.)
+get_X – +is to get an object and its properties
+set_X – +is to modify/edit an object and its properties
+delete_X – +is to delete an object
+list_Xs – +is to list all objects under a particular item item. Like list all +folders under CR root folder.
+tree_Xs – +is similar to list_Xs but will list objects under sub folders too. +Normally there is a parameter to set how deep to traverse the +folders.
+
+
ad_procs's switches are used to pass +in parameters. This means ad_procs are defined this way:
+
+
ad_proc +mynamespace::myproc {
+{-param1:required}
+{-param2 +“default value”}
+{-abooleanparam:boolean}
+} {
+api +doc goes here
+}
+
+
get_X is used to get an object and +its properties. An array is returned. An example on using get_X is:
+
+
array +set one_page [bcms::item::get_item -item_id $page_id -revision +latest]
+
+
after this call you will now have +$one_page(title), $one_page(name), etc.
+
+
When create_X is called the object id +is normally returned. ex.
+
+
set +revision_id [bcms::revision::add_revision -item_id $page_id \
++ -title $title -content $content -description $description \
++ -mime_type "text/html" \
++ -creation_user_id $creation_user_id -creation_ip +$creation_ip]
+
+
Normally set_X and delete_X calls +will return a status. ex.
+
+
+if [bcms::folder::delete_folder -folder_id $folder_id] {
++ ad_returnredirect $return_url
+}
+
+
Using list_X and tree_X you have the +option to return a multirow or a list of ns_sets. By default it +returns a multirow, if if a -multirow_name is not supplied it uses a +default name.
+ex of multirow
+bcms::item::list_related_items +-item_id $page_id -relation_tag $relation_tag -revision latest +-multirow_name related_items
+ex of list of ns sets
+set +folder_option_list [bcms::widget::option_tree -list_of_ns_sets \
++ [bcms::folder::tree_folders -return_list] \
++ -value_column folder_id -display_columns label]
+
+
+
This document is to give an overview of +the Content Repository so enough knowledge about it can be used to +start developing on BCMS. Things stated here may not be what is in +real in fact on CR, but for simplicity sake and basic overview.
+Content Repository logically functions +as a file system. Content items can be stored in folders (Content +Folders). Content items are like files, and Content folders are +like... well folders. The difference between a file system and the +CR is that content items may have 1 or more revisions. For example +text content item may have 3 versions. A content item may also hold +a property / state, which version is a live version. Normally the +live version is the one that we publish or display on the public web +site. Essentially its a central place where we can stuff different +content, and since it the basic data model and functions are done. +Your content will inherit those abilities and properties, such as +versioning, categorization, relations, etc.
+
+
+
Note: omissions has been made on the +columns to simplify.
+
+
cr_items
+
+
+Column | Type +
+------------------+------------------------
++item_id | integer +
++parent_id | integer +
+name + | character varying(400) +
++live_revision | integer +
++latest_revision | integer +
++publish_status | character varying(40) +
++content_type | character varying(100) +
++storage_type | character varying(10) +
+
+
item_id +- is the unique id of an item on CR. Its the acs object id.
+parent_id +– normally this the item_id of the folder that stores the item.
+name – +normally use as a url part. Similar to filename on the file system.
+live_revision +– if a particular item has a live version, this field stores the +version id, which refers to cr_revisions table.
+latest_revision +– this the version id of the latest version, this is kept +automatically triggers.
+publish_status +– values are production, ready, live and expired.
+content_type +– can kind of type is this item
+storage_type +– the values are text, file and lob. If the value of the content +is stored on cr_revisions.content then the value is “text”. If +the content is store on a file on +acs_root/content-repository-content-files then the value is “file”. + The “lob” value is used if the content is stored in the db using +lobs.
+
+
cr_revisions
+
+
+Column | Type +
+----------------+--------------------------
++revision_id | integer +
++item_id | integer +
+title + | character varying(1000) +
++description | text +
++publish_date | timestamp with time zone +
++mime_type | character varying(200) +
++content | text +
+
+
revision_id +– a unique id for a version
+item_id +– which version does this revision belong to
+title – +title of the version
+description +– description of the content
+publish_date +– if the version has been publish, the date is stored here
+mime_type +– mime type of the content
+content +– this is where content is stored if cr_items.storage_type is set +to “text”
+
+
cr_folders
+
+
+Column | Type +
+--------------------+-------------------------
++folder_id | integer +
+label + | character varying(1000) +
++description | text +
+
+
folder_id +– a unique number for a folder, this is a foreign key for +cr_items.item_id. So a folder is a special type of content.
+label – +friendly/pretty name of a folder.
+Content Types are similar to file type. + In a conventional file system a .doc and .xls file differs on both +type and content. One is for a word processor another one is for a +spread sheet. The same way CR can accommodate different content +types. Normally we need to define our content type since the very +basic CR content types may not be enough. For example if we would +like to have a sub title field we need to create a custom content +type. This CR +object model diagram where custom content types in the ACS Object +model.
+
+
Normally you can insert on a view or +call a plsql calls to insert to CR. With bcms you can do the +following:
+
+
set my_new_item +[bcms::item::create_item -item_name “testing” -parent_id +$my_folder]
+# lets put our initial version
+bcms::revision::add_revision -item_id +$my_new_item -title “this is a test page” -description “this +page is to test adding content to CR” -content “blah....”
+
+
Although the following command above +can be wrapped and just simply use one call, for example:
+
+
bcms::create_page -page_name “testing” +-folder_id $my_folder -title “this is a test page” -description +“this page is to test adding content to CR” -page_body “blah....”
+There should be different ways to get +content. Since its basically a database one can select the values. +Normally in bcms or create a bcds. You do the following.
+
+
On a index.vuh file, you get the + url
+Use the following call:
+array set mycontent + [bcms::item::get_item_by_url -root_id $my_root_folder -url + $url_requested -revision live -resolve_index]
+on your adp file:
<html>
<title>@mycontent.title@</title>
+<body>
+<h1>@mycontent.title@</h1>
+<h3>@mycontent.description@</h3>
+@mycontent.content@
</body></html>