TweetFollow Us on Twitter

December 94 - Getting the Most out of AOCE Catalog Records

Getting the Most out of AOCE Catalog Records


[IMAGE 005-024_Buttin_final_htm1.GIF]

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.


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.


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.

[IMAGE 005-024_Buttin_final_htm2.GIF]

Figure 1. An information page window

[IMAGE 005-024_Buttin_final_htm3.GIF]

Figure 2. Getting from a record to an information page


Every template contains asignature resource that indicates the type of the template and 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.


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).

[IMAGE 005-024_Buttin_final_htm4.GIF]

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 User record to hold keywords. It then shows how to create the main aspect template needed in order to list keyword records in the new User record information page sublist.


Now we're ready to define the aspect template for the new information page, which is a main view aspect template. The main view aspect template serves as the aspect template for everything on the new User record information page except for the content of the sublist items. Aspect templates contain a signature resource, a name resource, a record type resource, resources that specify how to handle objects dropped on the information page, resources for handling the View menu and Balloon Help, and the all-important lookup table.

The ID of the aspect template signature resource, of type 'deta', provides the base resource ID for the other aspect template resources. The signature resource also makes some settings related to drag and drop operations, as discussed in the next section, and specifies whether this template is a main aspect template.

resource 'deta' (kEInfoPageAspect, purgeable) {
    0,                  // Drop-operation order
    dropCheckAlways,    // Drop-check flag
    notMainAspect       // Not the main aspect template

In our example, the aspect template defines the properties for the new information page being added to an existing record type -- "aoce User." Because User records already have a main aspect template provided as part of the PowerTalk system software, you don't have to provide one yourself. In fact, declaring a template to be the main aspect template for User records would cause a conflict and the User records would no longer work correctly.

To replace an existing main aspect template, you use a killer template, which is not covered in this article. See Inside Macintosh: AOCE Application Interfaces for more on killer templates.*

Aspect templates, like other templates, have a name that must be unique to be identified by other templates. To guarantee uniqueness, start the names of all your templates (as well as all the new record types and attribute types for which you provide main aspect templates) with your four- character application signature as registered with Apple's Developer Support Center. Here's our aspect template name resource:

resource 'rstr' (kEInfoPageAspect+kDETTemplateName, purgeable) {
    "ACFC InfoPage aspect"

The record type resource identifies the record that the aspect applies to, in this case the User record:

resource 'rstr' (kEInfoPageAspect+kDETRecordType, purgeable) {
    "aoce User"

Although we're going to be defining a new attribute type that goes in User records, we don't provide a resource (of type kDETAttributeType) to specify that attribute type for the aspect template. In fact, if an attribute type were specified for the aspect template, the CE could use the template only for that attribute type and could not use it to modify the User record itself. (If the new attribute type were in a sublist and we provided a main aspect template to describe how that attribute should appear in the sublist, that main aspect template would contain a kDETAttributeType resource, as shown in the sample code on this issue's CD.)*

The aspect template drag and drop resources in the sample code make it possible for users to drag keyword records and drop them either on a closed User record or directly on a sublist on an information page, thereby adding those records to the sublist.

The kDETAspectRecordDragIn resource specifies what types of records can be dropped on a sublist. Because the CE can't actually store a record in a record, it adds to the sublist an attribute containing an alias to the dropped record. For each type of record the user can drag in, you also need to specify the type of attribute to store the alias in. The following resource indicates that aliases to keyword records should be stored as attribute type "ACFC Alias keyword":

resource 'rst#' (kEInfoPageAspect+kDETAspectRecordDragIn,
     purgeable) {
        "ACFC Keywords", "ACFC Alias keyword"

The drop-operation order and drop-check flag in the aspect template signature resource (shown in the previous section) come into play during these drag and drop operations, as follows:

  • The drop-check flag controls when the user will be prompted for confirmation upon performing the drag and drop. Setting this flag to dropCheckAlways indicates that the prompt message should always appear. Setting it to dropCheckConflicts limits its appearance to times when the user drops a record on a closed User record and more than one information page contains a sublist that accepts that record type. In this case, the CE would have to determine which information page should have the record added to its sublist. If you set the drop- check flag to dropCheckConflicts, the user is prompted for confirmation only if such a conflict arises.
  • Setting the drop-operation order to 0 indicates that you want the highest possible priority in case of the conflict just described. If the conflicting template also set its drop-operation order to 0, the CE makes an arbitrary decision about which sublist to add the record to. The user can always avoid the conflict by opening the desired information page and dropping the object directly on the desired sublist.

You also need to define the prompt message, which can include parameters (token^2 is the destination's name, and token^3 is the dragged record's name).

resource 'rstr' (kEInfoPageAspect+kDETAspectDragInString,
    purgeable) {
    "Do you want to add %3%"^3"%the selected items% to the "
    "company info for "^2"?"

In this example, dragging the keyword record named "AppleScript" onto John's business card produces the message "Do you want to add AppleScript to the company info for John?" If the user drags several items at once, the CE substitutes "the selected items" for the name of the dragged item.

When a template contains a sublist, the user determines how data is sorted in the sublist by choosing from the Finder's View menu (for example, "by Name" or "by Kind") or by clicking the labels above the sublist ("Name" and "Kind" in Figure 3). For these features to work, you have to provide the items for the View menu and specify which properties are used for sorting in each case. Our example uses the metaproperties (properties that are provided by the CE and that don't correspond to specific attribute values): kDETPrName (the record's name) and kDETPrKind (the record's kind).

resource 'detm' (kEInfoPageAspect+kDETAspectViewMenu, purgeable) {
    kDETPrName, "by Name";
    kDETPrKind, "by Kind";

You also need to add Balloon Help strings for properties. Each property has two strings: the first one is displayed if the property is editable, the second one if it's not. The first pair of text strings corresponds to the first property, the second pair to the second property, and so on. In our example, there's only one property (the employee's job description):

resource 'rst#' (kEInfoPageAspect+kDETAspectBalloons, purgeable) {
    "Description of the employee's job", "Description :"
    " Uneditable because the record is locked or access controlled."

As mentioned earlier, the lookup table tells the CE how to parse attribute values into properties and how to convert property values into attributes. For each property that you want to use on an information page, the lookup table must contain an entry that describes how to process the property's associated attribute. An attribute is identified by an attribute type and an attribute value tag:

  • The attribute type is a string that describes the contents of the attribute (such as "ACFC Alias keyword" or "aoce Member").
  • The attribute value tag is a 4-byte code that specifies the data format of the attribute value (such as typePackedDSSpec or typeBinary).

A single lookup table entry can specify how to parse more than one attribute type, but only if they have the same attribute value tag. You can provide separate lookup table entries for input (that is, translating attribute values to properties) and output (translating properties to attribute values), but you must provide both.

Each lookup table entry contains a set of flags that indicate the following:

  • whether the entry is used for translating attribute values to properties (useForInput)
  • whether the entry is used for translating properties to attribute values (useForOutput)
  • whether the attribute value is to be used in a sublist
  • whether the resulting entry in the sublist is an alias

The entry also includes elements that specify what to do with the attribute. Each element consists of three parts: a format that drives the parsing process, a property number, and an extra parameter used in certain types of elements. The format can be a simple data type that specifies how many bytes of data to take from the attribute and how to store it in the property. For example, a format of type 'word' takes the next two bytes from the attribute value and puts it in a number-type property. In the other direction, it would take two bytes from a number-type property and store it in an attribute value.

Lookup tables are complex and can be used in more ways than described here. For more information, see Inside Macintosh: AOCE Application Interfaces.*

In our example, there are two attribute types: one contains the description of an employee's job (attribute type "ACFC Company Empext Function"); the second is multivalued and contains the list of keywords or users (contact people, not discussed in this article), which are records in the catalog. There are two entries in the lookup table, one for each attribute type: the first one maps the attribute value to a string property (kFunction, defined on the CD); the second is for sublist items, each of which is a record of type "ACFC Alias keyword." The notForOutput and notForInputflags are set for the items in the sublist because sublist items are described in their own main aspects, not in the main view aspect that defines the sublist.

resource 'dett' (kEInfoPageAspect+kDETAspectLookup, purgeable) {
    {"ACFC Company Empext Function"}, typeBinary,
        useForInput, useForOutput, notInSublist, isNotAlias,
        'rstr', kFunction, 0;               // An element
    {"ACFC Alias keyword"}, typePackedDSSpec,
        notForInput, notForOutput, useInSublist, isAlias,


As described earlier in "What's in a Template," an information page template specifiesthe contents and layout of an information page. It includes one or more view lists, which describe the different views on the page, such as text fields or radio buttons. When your information page contains a sublist, you must include a view list describing an entry in the sublist. The CE uses this view list to display appropriate information for each item of the sublist, such as an icon and the name of the item.

The information page template signature resource provides the resource IDs of the view lists associated with the information page, as well as two property numbers for each view list. As discussed earlier, if the values of these two properties are not equal, the CE doesn't display the views described by the view list.

The signature resource also specifies the sort-order number of the information page, the presence or absence of a sublist in the information page, and the rectangle that contains the sublist (if any). The CE displays the information pages in the sequence indicated by their sort-order numbers.

resource 'deti' (kEInfoPage, purgeable) {
    4000,                       // Sort-order number
    {kSublistTop, kSublistLeft, kSublistBottom, kSublistRight},
            // Don't automatically select the first editable 
            // text field when the information page is opened.
    kDETNoProperty, kDETNoProperty, kEInfoPage;
    kDETNoProperty, kDETNoProperty, kEInfoPage+1;

As with the aspect template, you need to include resources that provide the template name and the type of record the template applies to:

resource 'rstr' (kEInfoPage+kDETTemplateName, purgeable) {
    "ACFC 1stInfoPage"

resource 'rstr' (kEInfoPage+kDETRecordType, purgeable) {
    "aoce User"

Because there's more than one information page for the User record, you need to provide the string that gets displayed in the information page pop-up menu used for changing to a different page:

resource 'rstr' (kEInfoPage+kDETInfoPageName, purgeable) {
    "Company Info"

You also need to provide the name of the aspect template that defines the properties used by the information page:

resource 'rstr' (kEInfoPage+kDETInfoPageMainViewAspect, purgeable) {
    "ACFC InfoPage aspect"

VIEW LISTSOur example has two view lists: the first describes the views (graphical elements) of the information page, and the second describes an entry in the sublist. To complete the information page template, you need to define these view lists (see Listing 1). A view list contains the following information for each view:

  • the view's bounds
  • the view's type (such as button or editable text field)
  • the property associated with this view, if any
  • information specific to the type of view

Listing 1. Defining the view lists

resource 'detv' (kEInfoPage, purgeable) {
    // Icon
    {6, 156, 22, 172}, kDETNoFlags, kDETAspectMainBitmap, 
        Bitmap {kDETSmallIcon}; 
    // Static text
    {kFunctionTop, kFunctionLeft, kFunctionBottom, kFunctionRight}, 
        kDETNoFlags, kDETNoProperty, 
        StaticTextFromView {kDETApplicationFont, kDETApplicationFontSize, 
            kDETRight, kDETBold, 
        "Job description"};
    // Editable text
    {kTEFunctionTop, kTEFunctionLeft, kTEFunctionBottom, 
        kTEFunctionRight}, kDETMultiLine, kFunction, 
        EditText {kDETApplicationFont, kDETApplicationFontSize, 
            kDETLeft, kDETNormal};
    // Sublist label: "Name"
    {kSublistSeeAlsoTop, kSublistSeeAlsoLeft,   
            kSublistSeeAlsoBottom, kSublistSeeAlsoRight},
        kDETNoFlags, kDETPrName, 
        StaticCommandTextFromView {kDETDefaultFont, 
            kDETDefaultFontSize, kDETLeft, kDETUnderline,
        "Name", kDETChangeViewCommand, -1};
    // Sublist label: "Kind"
    {kSublistKindTop, kSublistKindLeft, 
            kSublistKindBottom, kSublistKindRight}, 
        kDETNoFlags, kDETPrKind, 
        StaticCommandTextFromView {kDETDefaultFont, 
            kDETDefaultFontSize, kDETLeft, kDETNormal, 
        "Kind", kDETChangeViewCommand, -2};
    // Sublist box
    {kSublistTop-1, kSublistLeft-1, 
            kSublistBottom+1, kSublistRight+1}, kDETNoFlags,
        kDETNoProperty, Box {kDETUnused};    

// Sublist view list -- description of an entry in the sublist
resource 'detv' (kEInfoPage+1, purgeable) {
    // Icon
    {kDETSublistEntryTop, kDETSublistIconColumnLeft, 
            kDETSublistEntryBottom, kDETSublistIconColumnRight}, 
        kDETEnabled, kDETAspectMainBitmap, Bitmap {kDETMiniIcon};
    // Record's name
    {kDETSublistEntryTop, kSeeAlsoColumnLeft, 
            kDETSublistEntryBottom, kSeeAlsoColumnRight},
        kDETEnabled+kDETDynamicSize, kDETPrName, 
        EditText {kDETDefaultFont, kDETDefaultFontSize, 
            kDETLeft, kDETItalic};
    // Record's type
    {kDETSublistEntryTop, kKindColumnLeft, 
            kDETSublistEntryBottom, kKindColumnRight},
        kDETEnabled+kDETDynamicSize, kDETPrKind, 
        EditText {kDETDefaultFont, kDETDefaultFontSize,
            kDETLeft, kDETNormal};


The aspect and information page templates are now defined, adding a new information page for User records. However, there's still work to do before the user can create keyword records -- you need to provide aspect and information page templates for this new record type.

Since the new record type appears in a sublist, you need to provide a main aspect template (as shown in Listing 2).

A main aspect template is similar to the aspect template defined earlier, but it includes some additional resources:

  • the menu item text for the Finder's Catalog menu for creating keyword records
  • the name the CE should assign to newly created records of this type
  • an icon family for the icon, the record kind, and the kind of an alias to a record, as they are to be displayed in a sublist
  • one or more categories that this record type belongs to
  • Balloon Help strings for the record and for aliases to the record

Listing 2. Main aspect template for keyword records

resource 'deta' (kKeywordAspect, purgeable) {
    0,                  // Drop-operation order
    dropCheckAlways,    // Drop-check flag
    isMainAspect        // Is the main aspect

resource 'rstr' (kKeywordAspect+kDETTemplateName, purgeable) {
    "ACFC Keywords Aspect"

resource 'rstr' (kKeywordAspect+kDETRecordType, purgeable) {
    "ACFC Keywords"

resource 'rstr' (kKeywordAspect+kDETAspectKind, purgeable) {

resource 'rst#' (kKeywordAspect+kDETAspectCategory, purgeable) {

// Icons
include "Keywords.rsrcs" 'ICN#'(128) as
    'ICN#'(kKeywordAspect+kDETAspectMainBitmap, purgeable);
include "Keywords.rsrcs" 'icl4'(128) as
    'icl4'(kKeywordAspect+kDETAspectMainBitmap, purgeable);
include "Keywords.rsrcs" 'icl8'(128) as
    'icl8'(kKeywordAspect+kDETAspectMainBitmap, purgeable);
include "Keywords.rsrcs" 'ics#'(128) as
    'ics#'(kKeywordAspect+kDETAspectMainBitmap, purgeable);
include "Keywords.rsrcs" 'ics4'(128) as
    'ics4'(kKeywordAspect+kDETAspectMainBitmap, purgeable);
include "Keywords.rsrcs" 'ics8'(128) as
    'ics8'(kKeywordAspect+kDETAspectMainBitmap, purgeable);
include "Keywords.rsrcs" 'SICN'(128) as
    'SICN'(kKeywordAspect+kDETAspectMainBitmap, purgeable);

include "KeywordsInfoPageAspect.code" 'code'(1) as
    'detc'(kKeywordAspect+kDETAspectCode, purgeable);

// Drag and drop resources
resource 'rstr' (kKeywordAspect+kDETAspectDragInString, purgeable) {
    "Add “^3” to “^2”?"

resource 'rst#' (kKeywordAspect+kDETAspectRecordDragIn, purgeable) {
    "aoce User", kMemberAttrTypeBody

// View menu and Balloon Help resources
resource 'rstr' (kKeywordAspect+kDETAspectNewMenuName, purgeable) {
    "New Keyword"

resource 'rstr' (kKeywordAspect+kDETAspectNewEntryName, purgeable) {
    "Untitled Keyword"

resource 'rst#' (kKeywordAspect+kDETAspectBalloons, purgeable) {
    "Keyword description", "Keyword description : uneditable because"
    " the record is locked or access controlled."

resource 'rst#' (kKeywordAspect+kDETWhatIs, purgeable) {
    "Keyword \n \nA keyword record. Open this icon to see a"
    " description of this keyword and a list of people who have"
    " this job skill."

resource 'rst#' (kKeywordAspect+kDETAliasWhatIs, purgeable) {
    "Keyword alias \n \nAn alias to a keyword record. Open this"
    " alias to see a description of this keyword and a list of"
    " people who have this job skill."

resource 'detm' (kKeywordAspect+kDETAspectViewMenu, purgeable) {
    kDETPrName, "by Name";
    kDETPrKind, "by Kind";

// Lookup table
resource 'dett' (kKeywordAspect+kDETAspectLookup, purgeable) {
    {"ACFC Keyword Description"}, typeRString, 
        useForInput, useForOutput, notInSublist, isNotAlias,
        {'rstr', prDescription, 0};
    {kMemberAttrTypeBody}, typePackedDSSpec,
        notForInput, notForOutput, useInSublist, isAlias,

Upon double-clicking a keyword record, the user expects an information page to appear, as shown in Figure 4. Defining the information page template for the keyword record is similar to defining the information page template for the User record, as described earlier. You include signature, name, type, and optional resources along with the view lists. The resource definitions are provided on this issue's CD.

[IMAGE 005-024_Buttin_final_htm5.GIF]

Figure 4. Keyword record information page


As illustrated earlier in Figure 3, the sublist in the new User record information page lists the areas of expertise of the employee described by that record. Each area of expertise is represented by an alias to a keyword record. The sublist in a keyword record lists all the employees who have expertise in the area described by that keyword record (as shown in Figure 4). To keep these two lists synchronized, both the aspect template for the new information page we added to the user template and the keyword record's aspect template include a code resource. Each time someone adds a User record to a keyword record's sublist, the keyword record's code resource adds that keyword to the User record's sublist; each time someone adds a keyword record to a User record's sublist, the User record's code resource adds that user to the keyword record's sublist.

The code resources of the two templates are exactly the same because the structure of the attributes in both the records is identical, as described in the lookup table entry of the two aspect templates.

The following line adds the code resource to the aspect template:

include "UserInfoPageAspect.code" 'code'(1) as
    'detc'(kEInfoPageAspect+kDETAspectCode, purgeable);

The CE calls code resources when certain events occur, such as a change in an attribute or a drag and drop action. If the code resource doesn't handle the event, it must return a kDETDidNotHandle result code; if it successfully handles the event, it returns noErr. The CE calls the code resource's main routine, passing it a pointer to a parameter block (see Listing 3). This call block indicates which event occurred and contains additional parameters specific to the event.

The CE calls your code routine with a drop-query command (that is, with the kDETcmdDropQuery selector) when the user drops an object on the object that your aspect template applies to. If you want your code resource to handle the drop operation, return a value that's in the developer property-value range (that is, kDETFirstDevProperty through 249) in the commandID field of the call block.

Listing 3. The code resource's main routine

#define prChangeRec  kDETFirstDevProperty

/* Entry point called by the CE */
pascal OSErr KeywordsIP (DETCallBlock* callBlockPtr)
    OSErr   err = noErr;

    if (callBlockPtr-> == kDETSelf || 
            callBlockPtr-> ==
        switch (callBlockPtr->protoCall.reqFunction) {
            case kDETcmdInit: 
                /* Call-for masks */
                callBlockPtr->init.newCallFors =
                    kDETCallForCommands + kDETCallForDrops; 
            case kDETcmdDropQuery: 
                err = DoDropQuery(callBlockPtr); 
            case kDETcmdPropertyCommand: 
                err = DoCommand(callBlockPtr); 
                err = kDETDidNotHandle; 
    else err = kDETDidNotHandle; 
    return err; 

In our example (shown in Listing 4), we accept a record when the user drops it on a record that the template applies to by checking the commandID parameter provided by the CE and accepting drops only when the commandID value is kDETAlias. For other values, we inform the CE that we don't manage these cases by returning the constant kDETDidNotHandle. When we accept the drop operation, DoDropQuery returns the value prChangeRec in response to the drop-query command. When it receives a property number in response to the drop-query command, the CE calls the code resource again, this time with a property command (that is, with the selector kDETcmdPropertyCommand).

The property command's call block includes the property number specified in response to the drop- query command. The property-command code can use this property number as a routine selector. In our example, DoCommand checks to make sure the property number is prChangeRec. If it is, DoCommand calls DoAddRecord (more on this in a moment).

Most of the time, a resource doesn't handle all the CE events; therefore, to avoid the overhead resulting from frequent calls to the code resource, each template has a "call-for" mask that indicates which events to invoke it for. You must return the call-for mask when the CE calls the code resource with the kDETcmdInit selector. The kDETcmdInit case of the switch statement in Listing 3 returns a call-for mask that indicates that the code resource should be called only for property commands and drop queries.

Listing 4. DoDropQuery and DoCommand

/* Called when an object is dropped onto a record. Just set up a
    property number (prChangeRec) to be sent to the target aspect. */
OSErr DoDropQuery (DETCallBlock* callBlockPtr) 
    DETTargetSelector theDET;
    /* What is the best guess of the CE regarding the dropped */
    /* object? */
    if (((DETDropQueryBlock*)callBlockPtr)->commandID == kDETAlias) {
        /* Make an alias of the dropped object. */
        ((DETDropQueryBlock*)callBlockPtr)->copyToHFS = false;
        ((DETDropQueryBlock*)callBlockPtr)->commandID = prChangeRec;
        return noErr;
        return kDETDidNotHandle;

/* Called when the CE sends a property command. We check that it's 
    the property we expect. */
OSErr DoCommand (DETCallBlock* callBlockPtr)
    OSErr   err = noErr; 
    /* Check whether called for the prChangeRec command. */ 
    switch (((DETPropertyCommandBlock*)callBlockPtr)->property) {
        case prChangeRec: 
            err = DoAddRecord(callBlockPtr); 
            err = kDETDidNotHandle; 
    return err;

When the CE calls DoCommand with the property number prChangeRec, DoCommand calls DoAddRecord (Listing 5). DoAddRecord needs to add data to a record, so it must first identify which record is the target of the drop. To do so, it calls the CE's kDETcmdGetDSSpec callback routine, passing it the kDETSelf target selector. DoAddRecord then extracts the reference number of the personal catalog and the record ID from the record's DSSpec that was returned by the callback routine. To find out how many objects were dropped (that is, for how many dropped objects the drop-query routine returned the same property number), DoAddRecord calls the CE's kDETcmdGetCommandSelectionCount callback routine.

Listing 5. DoAddRecord

/* When record A is dragged onto record B, this function updates
    record A to store an alias to record B and updates record B to
    store an alias to record A. Updates occur only if records are of
    the required type. */
OSErr DoAddRecord (DETCallBlock* callBlockPtr)
    DETCallBackBlock    cbb, cbb1, cbb2;
    short               PABrefNum;
    RecordID            targetRID, receivedRID;
    LocalIdentity       userLocalId;
    PackedDSSpec        *targetDSSpec, *droppedDSSpec;
    DSSpec              dsp, dsp1;
    OSErr               err;
    long                count, i;
    Str255              targetAttrType, droppedAttrType;

#ifdef USER
    Str255              theStr = "ACFC Keywords";
    RString             recType;
    OCECToRString(theStr, smRoman, &recType, kRStringMaxBytes);

    /* Find out target record DSSpec. */ = kDETSelf;
    cbb.getDSSpec.reqFunction = kDETcmdGetDSSpec;
    err = CallBackDET(callBlockPtr, &cbb);
    if (err != noErr) 
        return err;
    HLock((Handle) cbb.getDSSpec.dsSpec);
    targetDSSpec = *(cbb.getDSSpec.dsSpec);
    /* Get record ID. */
    PABrefNum = cbb.getDSSpec.refNum;
    userLocalId = cbb.getDSSpec.identity;
    OCEUnpackDSSpec(targetDSSpec, &dsp, &targetRID);
    /* Find out how many records have been dropped. */
    cbb1.getCommandSelectionCount.reqFunction =
    err = CallBackDET(callBlockPtr, &cbb1);
    if (err != noErr) {
        DisposeHandle((Handle) cbb.getDSSpec.dsSpec);
        return err;
    count = cbb1.getCommandSelectionCount.count;
    for (i = 1; i <= count; i++) {
        /* Get the DSSpec of dropped record. */
        cbb1.getCommandItemN.reqFunction = kDETcmdGetCommandItemN;
        cbb1.getCommandItemN.itemNumber = i;
        cbb1.getCommandItemN.itemType = kDETDSType; 
        err = CallBackDET(callBlockPtr, &cbb1);
        if (err == noErr) {
            HLock((Handle) cbb1.getCommandItemN.item.ds.dsSpec);
            droppedDSSpec = *(cbb1.getCommandItemN.item.ds.dsSpec);
            OCEUnpackDSSpec(droppedDSSpec, &dsp1, &receivedRID);
            /* Check type of record. */
#ifdef USER
            if (OCEEqualRString(receivedRID.local.recordType,
                    &recType, kOCERecordType)) {
                strcpy(targetAttrType, kMemberAttrTypeBody);
                strcpy(droppedAttrType, "ACFC Alias keyword");
            if (OCEEqualRString(receivedRID.local.recordType,
                   kOCERecordType)) {
                strcpy(targetAttrType, "ACFC Alias keyword");
                strcpy(droppedAttrType, kMemberAttrTypeBody);
                /* Update target record to set up dropped record as
                   an attribute of this record. */
                AddRecordAsAttribute(userLocalId, droppedDSSpec,
                    &targetRID, PABrefNum, droppedAttrType);
                /* Update dropped record to set up target record as
                   an attribute of the dropped record. */
                AddRecordAsAttribute(userLocalId, targetDSSpec,
                    &receivedRID, PABrefNum, targetAttrType);
            HUnlock((Handle) cbb1.getCommandItemN.item.ds.dsSpec);
                ((Handle) cbb1.getCommandItemN.item.ds.dsSpec);
    if (err == noErr) {
        /* Ask for immediate update. */ = 
        cbb2.requestSync.reqFunction = kDETcmdRequestSync;
        err = CallBackDET(callBlockPtr, &cbb2); 
    DisposeHandle((Handle) cbb.getDSSpec.dsSpec);
    return err;

DoAddRecord calls the CE's kDETcmdGetCommandItemN callback routine for each object dropped. Dropped objects can be of different types, such as catalog items, files, and letters. In our example, the only kind of objects we want to add to our sublist are keyword records and User records, so DoAddRecord requests only information of type kDETDSType to get a packed DSSpec for each dropped record. If the targeted record is a User record, DoAddRecord checks to make sure the dropped record is a keyword record. If the targeted record is a keyword record, DoAddRecord checks to make sure the dropped record is a User record. It uses the AOCE utility routine OCEEqualRString to check the record type.

If the dropped record is the right type, DoAddRecord calls AddRecordAsAttribute, which is shown in Listing 6. AddRecordAsAttribute calls the Catalog Manager's DirAddAttributeValue routine to add the dropped object to the record. The parameter block for DirAddAttributeValue includes parameters that identify the catalog containing the record to be modified, the record itself, and the attribute to be added. The attribute specification includes the attribute type, the attribute value tag, and the attribute value.

Listing 6. AddRecordAsAttribute

/* This routine adds an attribute as a DSSpec to a record. */
void AddRecordAsAttribute(LocalIdentity userLocalId,
         PackedDSSpec* theDSSpec, RecordIDPtr updatedRecord,
         short refNum, Ptr attrType)
    OSErr           err;
    Attribute       theAttribute;
    DirParamBlock   dspb;
    AttributeType   kwRType;

    /* Prepare the attribute; set up its type and the data within
       the attribute. */
    OCECToRString(attrType, smRoman, (RString *) &kwRType,
    theAttribute.attributeType = kwRType;
    theAttribute.value.tag = typePackedDSSpec;
    theAttribute.value.dataLength = 
    theAttribute.value.bytes = (Ptr) theDSSpec;
    /* Prepare the parameter block used by the Catalog Manager to
       add an attribute. */
    *(long *)&dspb.addAttributeValuePB.serverHint = nil;
    dspb.addAttributeValuePB.dsRefNum = refNum; 
                                   /* refNum of a personal catalog */
    dspb.addAttributeValuePB.identity = userLocalId;
    dspb.addAttributeValuePB.aRecord = updatedRecord;
                                   /* Record to be modified */
    dspb.addAttributeValuePB.attr = &theAttribute;
                                   /* Attribute to be added */
    dspb.addAttributeValuePB.clientData = 0;
    err = DirAddAttributeValue(&dspb, false);

To maintain the synchronization between the User record and the keyword record, you also need to update the dropped record, adding the target record as an attribute of the dropped one. You can use the same routine -- AddRecordAsAttribute -- because the structure of the attributes in the two records is the same -- the record to be updated is now the dropped record and the attribute value is the DSSpec of the target record.

To summarize what happens when a drag and drop action occurs:

  1. The user drops a bunch of icons on a closed record or an information page. If the drop is on an information page, that page is the only possible destination; if it's a closed record, all the information pages are potential destinations.
  2. For each icon/possible-destination-aspect pair, the CE looks at the template resources and calls the code resource (if there is one).
  3. Based on the information returned by the code resources and any drag and drop resources present, the CE decides what operation is desired for each pair.
  4. Based on the drop-operation order number, the CE picks one destination and one operation for each icon.
  5. For each group of icons with the same destination and operation, the CE performs that operation at that destination. If the operation is copy, move, or make alias, the CE handles it. If the operation is a property command (as in this article), the CE calls the code resource to perform the operation.


When you compile the templates, you get a PowerTalk extension that can be installed in the Extensions folder of the System Folder. Users who install these templates can display and edit new information about users in User records in their personal catalogs. The system administrator or anyone who has sufficient access privileges can use the new keyword records and the new User record information page to maintain this information for everyone who has a PowerShare account.

The benefit in extending User records is that all the information regarding a person is stored in the same place and therefore is very easy to retrieve. The work involved in developing this customized solution is much less than that typically involved in developing a database. What's more, AOCE catalogs are part of system software -- why pay more for new database software and servers?


This article has shown a relatively easy way to extend the templates that come built into PowerTalk. As you become more familiar with AOCE templates, you'll undoubtedly think of more complex things you can do with templates and template code resources.

The next article, "Exploring Advanced AOCE Templates Through Celestial Mechanics," describes one imaginative use of templates. Another use might be to define different kinds of templates for different people, giving them access to different types of data in the same catalog.

Imagine a traditional library using a catalog to store references to books: A specializedtemplate could provide information on a book, including keywords related to the topics in the book. A keyword template would let users browse the catalog and find all the books available on a specific topic. And to dream a bit further, the catalog could be a very large database on a distant system that you access by dialing up. It would contain all the references in the world of existing books, and you could consult it from your home, just by browsing the catalog through the Finder. The book information page might even contain a button that could open the electronic version of the book.

So go ahead and take advantage of AOCE catalogs. Apply what you've learned about expanding records through AOCE templates and begin building the world of connectivity and information sharing that you dream about.

CHRISTINE BUTTIN has worked in Developer Technical Support for Apple since 1989, first for Apple Computer Europe and now for Apple France. At the office, they call her the talkative woman, not only because she enjoys chatting, but also because she mainly supports technologies that enable communication (such as AppleTalk, AppleScript, AOCE). When not talking, she spends most of her time practicing Aikido or traveling (she has a special love for the Sahara Desert, where she's sure to be far away from computers). An extra benefit of her job is that she can regularly visit the U.S., where she has made many good friends. Visiting her American friends might not be as restful as a trip to the Sahara Desert, but it certainly is a lot of fun.*

Thanks to our technical reviewers David Akhond, Paul Black, Harry Chesley, and Steve Falkenburg. Special thanks to Paul Black for writing the background material on AOCE catalogs and templates. *

Apple Inc.
Microsoft Corpora
Google Inc.

MacTech Search:
Community Search:

Software Updates via MacUpdate

Apple iOS 8.1 - The latest version of Ap...
The latest version of iOS can be downloaded through iTunes. Apple iOS 8 comes with big updates to apps you use every day, like Messages and Photos. A whole new way to share content with your family.... Read more
TechTool Pro 7.0.5 - Hard drive and syst...
TechTool Pro is now 7, and this is the most advanced version of the acclaimed Macintosh troubleshooting utility created in its 20-year history. Micromat has redeveloped TechTool Pro 7 to be fully 64... Read more
PDFKey Pro 4.0.2 - Edit and print passwo...
PDFKey Pro can unlock PDF documents protected for printing and copying when you've forgotten your password. It can now also protect your PDF files with a password to prevent unauthorized access and/... Read more
Yasu 2.9.1 - System maintenance app; per...
Yasu was originally created with System Administrators who service large groups of workstations in mind, Yasu (Yet Another System Utility) was made to do a specific group of maintenance tasks... Read more
Hazel 3.3 - Create rules for organizing...
Hazel is your personal housekeeper, organizing and cleaning folders based on rules you define. Hazel can also manage your trash and uninstall your applications. Organize your files using a... Read more
Autopano Giga 3.7 - Stitch multiple imag...
Autopano Giga allows you to stitch 2, 20, or 2,000 images. Version 3.0 integrates impressive new features that will definitely make you adopt Autopano Pro or Autopano Giga: Choose between 9... Read more
MenuMeters 1.8 - CPU, memory, disk, and...
MenuMeters is a set of CPU, memory, disk, and network monitoring tools for Mac OS X. Although there are numerous other programs which do the same thing, none had quite the feature set I was looking... Read more
Coda 2.5 - One-window Web development su...
Coda is a powerful Web editor that puts everything in one place. An editor. Terminal. CSS. Files. With Coda 2, we went beyond expectations. With loads of new, much-requested features, a few... Read more
Arq 4.6.1 - Online backup to Google Driv...
Arq is super-easy online backup for the Mac. Back up to your own Google Drive storage (15GB free storage), your own Amazon Glacier ($.01/GB per month storage) or S3, or any SFTP server. Arq backs up... Read more
Airfoil 4.8.10 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more

Latest Forum Discussions

See All

This Week at 148Apps: October 13-17, 201...
Expert App Reviewers   So little time and so very many apps. What’s a poor iPhone/iPad lover to do? Fortunately, 148Apps is here to give you the rundown on the latest and greatest releases. And we even have a tremendous back catalog of reviews; just... | Read more »
Angry Birds Transformers Review
Angry Birds Transformers Review By Jennifer Allen on October 20th, 2014 Our Rating: :: TRANSFORMED BIRDSUniversal App - Designed for iPhone and iPad Transformed in a way you wouldn’t expect, Angry Birds Transformers is a quite... | Read more »
GAMEVIL Announces the Upcoming Launch of...
GAMEVIL Announces the Upcoming Launch of Mark of the Dragon Posted by Jessica Fisher on October 20th, 2014 [ permalink ] Mark of the Dragon, by GAMEVIL, put | Read more »
Interview With the Angry Birds Transform...
Angry Birds Transformers recently transformed and rolled out worldwide. This run-and-gun title is a hit with young Transformers fans, but the ample references to classic Transformers fandom has also earned it a place in the hearts of long-time... | Read more »
Find Free Food on Campus with Ypay
Find Free Food on Campus with Ypay Posted by Jessica Fisher on October 20th, 2014 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »
Strung Along Review
Strung Along Review By Jordan Minor on October 20th, 2014 Our Rating: :: GOT NO STRINGSUniversal App - Designed for iPhone and iPad A cool gimmick and a great art style keep Strung Along from completely falling apart.   | Read more »
P2P file transferring app Send Anywhere...
File sharing services like Dropbox have security issues. Email attachments can be problematic when it comes to sharing large files. USB dongles don’t fit into your phone. Send Anywhere, a peer-to-peer file transferring application, solves all of... | Read more »
Zero Age Review
Zero Age Review By Jordan Minor on October 20th, 2014 Our Rating: :: MORE THAN ZEROiPad Only App - Designed for the iPad With its mind-bending puzzles and spellbinding visuals, Zero Age has it all.   | Read more »
Hay Ewe Review
Hay Ewe Review By Campbell Bird on October 20th, 2014 Our Rating: :: SAVE YOUR SHEEPLEUniversal App - Designed for iPhone and iPad Pave the way for your flock in this line drawing puzzle game from the creators of Worms.   | Read more »
My Very Hungry Caterpillar (Education)
My Very Hungry Caterpillar 1.0.0 Device: iOS Universal Category: Education Price: $3.99, Version: 1.0.0 (iTunes) Description: Care for your very own Very Hungry Caterpillar! My Very Hungry Caterpillar will captivate you as he crawls... | Read more »

Price Scanner via

2013 15-inch 2.0GHz Retina MacBook Pro availa...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros now available for $1599 including free shipping plus NY sales tax only. Their price is $400 off original MSRP. B&H... Read more
Updated iPad Prices
We’ve updated our iPad Air Price Tracker and our iPad mini Price Tracker with the latest information on prices and availability from Apple and other resellers, including the new iPad Air 2 and the... Read more
Apple Pay Available to Millions of Visa Cardh...
Visa Inc. brings secure, convenient payments to iPad Air 2 and iPad mini 3as well as iPhone 6 and 6 Plus. Starting October 20th, eligible Visa cardholders in the U.S. will be able to use Apple Pay,... Read more
Textkraft Pocket – the missing TextEdit for i...
infovole GmbH has announced the release and immediate availability of Textkraft Pocket 1.0, a professional text editor and note taking app for Apple’s iPhone. In March 2014 rumors were all about... Read more
C Spire to offer iPad Air 2 and iPad mini 3,...
C Spire on Friday announced that it will offer iPad Air 2 and iPad mini 3, both with Wi-Fi + Cellular, on its 4G+ LTE network in the coming weeks. C Spire will offer the new iPads with a range of... Read more
Belkin Announces Full Line of Keyboards and C...
Belkin International has unveiled a new lineup of keyboard cases and accessories for Apple’s newest iPads, featuring three QODE keyboards and a collection of thin, lightweight folios for both the... Read more
Verizon offers new iPad Air 2 preorders for $...
Verizon Wireless is accepting preorders for the new iPad Air 2, cellular models, for $100 off MSRP with a 2-year service agreement: - 16GB iPad Air 2 WiFi + Cellular: $529.99 - 64GB iPad Air 2 WiFi... Read more
Price drops on refurbished Mac minis, now ava...
The Apple Store has dropped prices on Apple Certified Refurbished previous-generation Mac minis, with models now available starting at $419. Apple’s one-year warranty is included with each mini, and... Read more
Apple refurbished 2014 MacBook Airs available...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
Refurbished 2013 MacBook Pros available for u...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available starting at $929. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros (4GB RAM/... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** At the Apple Store, you connect business professionals and entrepreneurs with the tools they need in order to put Apple solutions to work in their Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** The Apple Store is a retail environment like no other - uniquely focused on delivering amazing customer experiences. As an Expert, you introduce people Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** As businesses discover the power of Apple computers and mobile devices, it's your job - as a Solutions Engineer - to show them how to introduce these Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.