December 94 - Getting the Most out of AOCE Catalog Records
Getting the Most out of AOCE Catalog Records
CHRISTINE BUTTIN
Apple Open Collaboration Environment (AOCE) catalogs can contain any kind of data,
which users can browse and edit using the Finder. Developers and knowledgeable end
users can write AOCE templates, which add new record types to catalogs and tell the
Finder how to display the data. This article describes AOCE templates and provides an
example of using templates to extend PowerTalk's built-in User records to contain
your own data.
Personal computers are great for storing large amounts of related data. Databases
make it possible to organize data and to find individual items quickly, but it takes a
long time to set up a database and enter data into it. If you're a system administrator or
in-house developer and you want to provide a database for use by others, you also have
to worry about providing and maintaining the database software for everyone involved.
If you're using PowerTalk, however, you already have a way to store information:
AOCE catalogs. What's more, the related Catalogs Extension (CE) to the Finder allows
users to browse and edit catalog records with the Finder.
The Human Resources group at Apple Computer France wanted to create a directory of
Apple personnel that included each person's name, title, department, address, and a
list of keywords to identify areas of expertise. Furthermore, the group wanted to be
able to list everyone with a particular area of expertise. Since Human Resources uses
a PowerShare collaboration server, there was already a catalog with a User record
containing all of the information for everyone with an account on the server, except
for areas of expertise. What better way to create the directory than to add the new
keyword data to the User records? To list people related to a specific keyword, the
group could create keyword records by adding a new record type to the AOCE catalog in
which the data was stored.
The User records that are defined as part of the PowerTalk system software store
information such as a person's name, title, phone number, and electronic address.
PowerTalk uses AOCE templates -- resource files that go in the Extensions folder in
the System Folder -- to tell the CE how to store and display the data. This article
shows you how to write AOCE templates that extend User records to hold additional
information (keywords identifying areas of expertise) and templates that define a new
record type (keyword records). Although writing templates doesn't necessarily
require writing any code resources at all, you can do more by adding code resources to
your templates. This article goes on to demonstrate how to use a code resource to keep
records synchronized that refer to each other's data. You'll find all the example code on
this issue's CD. Even if you're not using a PowerShare server, you can use the
approach described in this article to store data in a personal catalog on your own
Macintosh.
A BIT ABOUT AOCE CATALOGS
To get the most out of this article, you should have PowerTalk installed on your
computer and have spent a little time playing with catalogs. Acatalog is a
hierarchically arranged store of data. The bottom level of the catalog hierarchy is
therecord , which is analogous to a file in the Macintosh hierarchical file system
(HFS). Unlike files, however, when the user double-clicks a record, the application
that opens the record is the Finder itself. How the contents of the record are stored in
the catalog and displayed to the user is determined by sets of resources in files known
asAOCE templates .
For the complete story on AOCE, see Inside Macintosh: AOCE Application
Interfaces.*
A PowerShare collaboration server stores the name and account information of each
entity (person, gateway, or whatever) that has an account on the AOCE server in a
server-based catalog. It uses User records for this purpose. A personal catalog looks
much like a server-based catalog but is, in fact, an HFS file on the local disk. There's
practically no difference between a record in a server-based catalog and one in a
personal catalog; AOCE templates work identically in both cases.
The data in records is organized intoattributes . Each attribute has a type (for
example, address or area of expertise) and any number of attribute values, which can
contain any sort of data. Each attribute type is defined by a template that specifies the
format for the data. You can write new templates to expand the types of attributes that
existing record types can contain -- that's precisely what this article does, in fact.
FROM RECORDS TO INFORMATION PAGES
When the user double-clicks an AOCE catalog record in the Finder, a window called
aninformation page window opens. An information page window can contain a single
information page, or several information pages, each with a pop-up menu listing the
other pages. Each information page displays data stored in the record. The window in
Figure 1 shows an information page that displays data stored in a User record.
The CE uses a two-step process to get from a record to an information page. Because
there's not necessarily a one-to-one correspondence between attribute values and the
data you want to display on an information page, the first step consists of parsing the
data in the attribute values into discrete units of data known asproperties . For
example, an address attribute value may contain street, city, and zip code properties.
The second step is to specify exactly where and how each property is displayed on the
information page.
Two types of AOCE templates specify how the CE performs each of these steps:
• An aspect template describes how the attribute values are to be parsed
into properties.
• An information page template specifies how the properties are to be
displayed on the information page.
These aspect and information page templates share a data structure in memory that
contains the properties. This data structure is called anaspect . The relationships
among records, aspect templates, aspects, information page templates, and information
pages are illustrated in Figure 2.
There are a few important things to note about these relationships:
• An aspect template does not have to deal with every attribute type in a
record. There can be any number of aspect templates that apply to a given
record type, and each can describe the parsing of some subset of attribute
types.
• An information page template does not have to use every property stored
in an aspect.
• More than one information page template can use properties from the
same aspect, but each information page template can use properties from only
one aspect.
• The process works in reverse as well. When the user enters data into an
information page, the information page template defines which property that
data belongs to and the aspect template describes how the data should be stored
in an attribute value.
Figure 1. An information page window
Figure 2. Getting from a record to an information page
WHAT'S IN A TEMPLATE
specifies some other template characteristics. In addition, there are other resources
that are required for every template (such as the template name resource), resources
that are required for specific template types, and a variety of optional resources that
you can include if needed.
The CE identifies each resource by its resource type and by the offset of its resource ID
from the resource ID of the signature resource. For example, the template name
resource and the record type resource (which specifies what type of record the
template applies to) are both 'rstr' resources; the CE can distinguish between them
because the template name resource's ID is equal to the signatureresource's ID plus the
constant value kDETTemplateName, while the record type resource has an ID offset of
kDETRecordType.
Aspect templates contain a resource called alookup table . The lookup table contains the
instructions to the CE for parsing attribute values into properties and properties into
attribute values. If the CE needs a property that has a property number in the range 0
to 249, and it doesn't find a value for that property that the lookup table constructed
from an attribute value, it looks for a resource with an ID offset equal to the property
number. This means that in the aspect template itself you can provide property values
to be used as default values, initial values, or constant values for properties.
Information page templates contain one or more resources calledview lists , which
specify the views that appear on the information page. Aview is an item or a field on
an information page displaying one or more property values (for example, a text field
or a radio button).
Unlike the ID of other template resources, a view list's resource ID isn't related to the
signature resource's ID. Instead, the information page template's signature resource
includes references to all the view lists for that template. For each view list, the
signature resource includes two property numbers that identify properties associated
with that view list. The view list is active only if the values of its two associated
properties are equal. You can use this feature to implementconditional views , that is,
information-page features that the CE displays only under certain circumstances.
MAIN VIEWS, SUBLISTS, AND MAIN ASPECTS
Figure 3 shows another common feature of information pages -- asublist . A sublist is
a portion of the information page that contains a list of attribute values or records. In
Figure 3, the sublist holds two records (actually, it holds aliases to the records).
Typically, when the user double- clicks an item in a sublist, the same two-step
process as described earlier in the section "From Records to Information Pages
occurs; as a result, another information page opens and displays the information
associated with the attribute or record represented by the selected item. For example,
double-clicking the AOCE item in Figure 3 opens an information page displaying all
people with that expertise (as shown in Figure 4 later in this article).
Figure 3. Information page with a sublist
All the property values displayed on an information page outside the sublist come from
a single aspect, called themain view aspect . This aspect also provides the list of items
to be included in the sublist (if any).
Each item in a sublist has its own aspect, called amain aspect , which provides the
property values necessary to display the item in the sublist (such as the name of a
record or the kind of attribute value). A main aspect can contain other property values
as well; in fact, a main aspect can also serve as the main view aspect for an
information page. If you want to create a new information page for an existing record,
you must provide a main view aspect template for that information page. If you're
defining a new record type to be displayed in a sublist, you need to provide a main
aspect template for that record type. The example in this article demonstrates how to
create a main view aspect template and an information page template that extend the