Index: openacs-4/packages/acs-core-docs/www/objects.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v diff -u -r1.52.2.12 -r1.52.2.13 --- openacs-4/packages/acs-core-docs/www/objects.html 19 Nov 2016 09:21:54 -0000 1.52.2.12 +++ openacs-4/packages/acs-core-docs/www/objects.html 6 Jan 2017 09:18:42 -0000 1.52.2.13 @@ -21,16 +21,16 @@ body varchar(1024) )

-We've omitted constraint names for the purpose of clarity. +We've omitted constraint names for the purpose of clarity.

Thinking further ahead, we can imagine doing any of the following things with Notes as well: -

+

In OpenACS, the key to enabling these types of services on your application data is to take advantage of the Object System. The first question, then, is "Just what are objects, and what do you use them for anyway?". The short answer: objects are anything -represented in the application's data model that will need to be +represented in the application's data model that will need to be managed by any central service in OpenACS, or that may be reusable in the context of future applications. Every object in the system is represented using a row in the acs_objects table. This @@ -53,7 +53,7 @@ a general-comments replacement to personalized ranking - will become available to your application "for free."

How to Use Objects

-Using ACS objects is straightforward: all that's required are a few +Using ACS objects is straightforward: all that's required are a few extra steps in the design of your application data model.

In order to hook our Notes application into the object system, we @@ -72,14 +72,14 @@ inherit attributes from a parent type, so the type system forms a hierarchy. Unlike Java, Oracle does not support this inheritance transparently, so we have to make sure we add our own bookkeeping code to -keep everything consistent. Below you'll find the code needed to describe a +keep everything consistent. Below you'll find the code needed to describe a new object type called notes in your system.

Fire up your text editor and open the ROOT/packages/notes/sql/oracle/notes-create.sql (ROOT/packages/notes/sql/postgresql/notes-create.sql for the PG version) file created when we created the package. Then, do the following: -

Describe the new type to the type system

+

Describe the new type to the type system

First, add an entry to the acs_object_types table with the following PL/SQL call: 

 begin  
@@ -100,14 +100,14 @@
 note. This type is a subtype of the 
 acs_object type, which means that we want to inherit all
 of the basic attributes of all ACS objects. As mentioned, it will take
-some work on our part to make this happen, since Oracle can't do it
+some work on our part to make this happen, since Oracle can't do it
 automatically.  In general, most basic applications will define types
 that are simple subtypes of acs_object.
 

 Add entries to the acs_attributes table to describe
 the data attributes of the new type. This data can eventually be used
 to do things like automatically generate user interfaces to manipulate
-the notes table, though that functionality isn't yet
+the notes table, though that functionality isn't yet
 available.
 
 declare 
@@ -139,7 +139,7 @@
 because the new type note is a subtype of
 acs_object, it will inherit these attributes, so there is
 no need for us to define them.
-

Define a table in which to store your objects

+

Define a table in which to store your objects

The next thing we do is make a small modification to the data model to reflect the fact that each row in the notes table represents something that is not only an object of type @@ -164,7 +164,7 @@ use the acs_objects table to find objects will transparently find any objects that are instances of any subtype of acs_objects. -

Define a package for type specific procedures

+

Define a package for type specific procedures

The next step is to define a PL/SQL package for your new type, and write some basic procedures to create and delete objects. Here is a package definition for our new type: @@ -193,9 +193,9 @@ show errors

You might be wondering what all the extra parameters are to these -calls, since we haven't mentioned them before. These parameters are +calls, since we haven't mentioned them before. These parameters are needed to fill out information that will be stored about the object -that's not stored directly in the table you defined. The OpenACS Object +that's not stored directly in the table you defined. The OpenACS Object System defines these attributes on the type acs_object since all objects should have these attributes. Internally, there are tables that store this information for you. Most of the data is pretty @@ -210,9 +210,9 @@ then the object inherits its permissions from the context. For example, if I had told you how to use the permissions system to specify that an object OBJ was "read only", then any other object that used OBJ as its -context would also be "read only" by default. We'll talk about this more +context would also be "read only" by default. We'll talk about this more later. -

Define a package body for type specific procedures

+

Define a package body for type specific procedures

The PL/SQL package body contains the implementations of the procedures defined above. The only subtle thing going on here is that we must use acs_object.new to insert a row into @@ -272,15 +272,15 @@ / show errors;

-That's pretty much it! As long as you use the note.new +That's pretty much it! As long as you use the note.new function to create notes, and the note.delete function to -delete them, you'll be assured that the relationship each +delete them, you'll be assured that the relationship each note has with its corresponding acs_object is preserved.

The last thing to do is to make a file -ROOT/packages/notes/sql/notes-drop.sql so it's easy to -drop the data model when, say, you're testing: +ROOT/packages/notes/sql/notes-drop.sql so it's easy to +drop the data model when, say, you're testing: 

 begin 
   acs_object_type.drop_type ('note'); 
@@ -306,7 +306,7 @@
 For example, for most applications, you will want to use objects to
 represent the data in your application that is user visible and thus
 requires access control. But other internal tables, views, mapping
-tables and so on probably don't need to be objects. As before, this
+tables and so on probably don't need to be objects. As before, this
 kind of design decision is mostly made on an
 application-by-application basis, but this is a good baseline from
 which to start.
@@ -333,7 +333,7 @@
 field in any other way whatsoever is guaranteed to make your
 application act strangely.
 

-As we'll see later, the Notes example will point each note object's
+As we'll see later, the Notes example will point each note object's
 context_id to the package instance in which the note was
 created. The idea will be that in a real site, the administrator would
 create one package instance for every separate set of Notes (say, one
@@ -362,9 +362,9 @@
 are careful to define our own attribute for owner_id
 rather than overloading creation_user from the objects
 table. But, since we will probably use creation_date and
-so on for their intended purposes, we don't bother to define our own
+so on for their intended purposes, we don't bother to define our own
 attributes to store that data again. This will entail joins with
-acs_objects but that's OK because it makes the overall
+acs_objects but that's OK because it makes the overall
 data model cleaner. The real lesson is that deciding exactly how and
 when to use inherited attributes is fairly straightforward, but
 requires a good amount of thought at design time even for simple