<html>
<head>
<title>Address Book Design Documentation</title>
</head>
<body bgcolor=white>
<h2>Address Book Design Documentation</h2>
by John Mileham
<hr>
<h3>I. Essentials</h3>
<ul>
<li> <a href=/api-doc/procs-file-view?path=packages/address-book/tcl/address-book-procs.tcl>address-book-procs.tcl</a> <i>provides all Tcl API</i> </li>
<li> <a href=/doc/sql/display-sql?url=address-book-create.sql&package_key=address-book>address-book-create.sql</a> <i>provides all data model and PL/SQL API</i> </li>
<p>
<li> <a href=requirements>Address Book Requirements</a> </li>
</ul>
<h3>II. Introduction</h3>
<p>Address Book is an application/service hybrid. It allows the end user to create and store contact information
in a collaborative web environment according to permissions set through the standard ACS permissions API. As a service,
it also allows application programmers to leverage its extensible contact storage mechanism for other applications,
such as an e-commerce order fulfillment system.
<p>
Address book stores basic identity information about each contact. Each contact may store an arbitrary number of custom
attributes that may be used to contain phone numbers, notes and email addresses. Address Book relies on the places
service to provide storage of an arbitrary number of street addresses per contact. The end result is a superset of the
attribute and address storage provided by Palm-OS's address book application. This will enable us to write a full-featured
synchronization conduit in the future.
<h3>III. Historical Considerations</h3>
<p>
Address Book evolved out of an ACS3.x package of the same name. The original address-book provided specific storage of
all attributes, which was very limiting. A given entry could only support the number of email or street addresses
originally planned when programming the application. It also provided a reminder service for birthdays. An address-book
itself should not be date aware. The 4.x model is to integrate applications as completely as possible, especially
considering the public APIs that are now standard with 4.x packages. This functionality should be handled by the calendar
or even a new birthday reminder application that has the capability to link address-book contacts with calendar reminders.
<p>
Another disadvantage of the 3.x model of address-book was that there was no canonical storage mechanism for street
addresses. Another application hoping to derive meaning from the address book data would have to be programmed to interact
specifically with the table and column names of the address-book application. By using the places service for street
address storage, address-book opens the storage of addresses to other applications. If a mapping package were written
for ACS, it could be passed the address_id of the addresses associated with a contact and know exactly how to display a
map for it. Contact addresses can even be used directly for radius searches using the places service.
<h3>IV. Competitive Analysis</h3>
<p>
Address Book was designed to take the functionality of the Palm application of the same name as a starting point.
It goes from there to provide arbitrary numbers of attributes and addresses, which means greatly reducing the headache
involved in keeping track of complex entries (such as a contact having home and work addresses, or many telephone
numbers and email addresses). Address Book also supports single-step creation of a basic contact. There is no extra
complexity just because of the more robust storage mechanism. You get the same ease-of-use of the Palm application
with fully extensible storage sitting behind it.
<h3>V. Design Tradeoffs</h3>
<p>
There were two areas of address-book that were identified as focal points from the beginning of design. First, it was
to be flexible. We met this requirement by providing extensible attribute and address storage. Second, it had to be
easy to use. At every phase of design and development, the user experience was taken into account. Initially, there
was a significant amount of JavaScript automation in the user interface. It did appear very slick, and allowed users
to swap attribute locations on the page on the edit page without waiting for a page load. The problem was that it could
be confusing to users unaware of the state of the actual data. The interface was pared down to the minimum. Swapping
still exists, but all swaps are done on the server side in a quick operation rather than on the browser side. Forms
are less confusing because there is only one committal action that can be taken per form. That is clicking on the submit
button. Rather than incorporating confusing functionality on a single edit form, the user may choose to modify what
they want through a number of intuitive actions directly from the view page. An additional benefit of removing JavaScript
is a decreased dependence on client-side robustness. Many businesses and higher security institutions disable JavaScript
on all workstations for security reasons. By eliminating this frivolous dependency, Address Book becomes fully functional
on older and more unusual platforms.
<h3>VI. API</h3>
<ul>
<li><h4><code>ab_contact_attr_type</code>: Contact Attribute Type - <i>subtype of</i> <code>acs_object</code></h4>
<ul>
<li> <h5>PL/SQL API</h5>
<ul>
<li>Provides standard <code>new</code>/<code>delete</code>
functionality.</li>
<li>Provides a <code>name</code> function that returns the pretty name of the attribute type.</li>
</ul>
</li>
<li> <h5>Tcl API</h5>
<ul>
<li><a href=/api-doc/proc-view?proc=ab%3a%3acontact_attr_type%3a%3aselect>ab::contact_attr_type::select</a> is
provided to offer a UI element to select an attribute type out of the defined attribute types (which include
types like work phone, home phone, e-mail, etc.).</li>
</ul>
</li>
</ul>
</li>
<li><h4><code>ab_contact_attr</code>: Contact Attribute - <i>subtype of</i> <code>acs_object</code></h4>
<ul>
<li> <h5>PL/SQL API</h5>
<ul>
<li>Provides standard <code>new</code>/<code>delete</code>
functionality. The new function does not directly take a value for <code>sort_key</code>.
It instead offers a <code>before_attr_id</code> argument so that the application programmer need not
worry about attribute values.</li>
<li>Provides a <code>swap_sort</code> procedure that takes two attribute IDs and swaps their sort keys.</li>
</ul>
</li>
<li> <h5>Tcl API</h5>
<ul>
<li><a href=/api-doc/proc-view?proc=ab%3a%3acontact_attr%3a%3amultirow>ab::contact_attr::multirow</a> is
provided to return a multirow datasource containing all of the attributes associated with a given contact.</li>
</ul>
</li>
</ul>
</li>
<li><h4><code>ab_contact_rel</code>: Contact Rel - <i>subtype of</i> <code>acs_rel</code></h4>
<ul>
<li> <h5>PL/SQL API</h5>
<ul>
<li>Provides standard <code>new</code>/<code>delete</code>
functionality.</li>
</ul>
</li>
</ul>
</li>
<li><h4><code>ab_contact</code>: Contact - <i>subtype of</i> <code>acs_object</code></h4>
<ul>
<li> <h5>PL/SQL API</h5>
<ul>
<li>Provides standard <code>new</code>/<code>delete</code>
functionality.</li>
<li>Provides a <code>name</code> function that returns the concatenation of <code>first_names</code>
and <code>last_name</code>.</li>
<li>Provides a number of functions returning the primary value of the field for each contact (or null if none
is specified).
<ul>
<li>work_phone
<li>home_phone
<li>fax
<li>other
<li>email
</ul>
</li>
</ul>
</li>
<li> <h5>Tcl API</h5>
<ul>
<li><a href=/api-doc/proc-view?proc=ab%3a%3acontact%3a%3a1row>ab::contact::1row</a> is
provided to create a 1row datasource containing all of the basic information in a contact.</li>
<li><a href=/api-doc/proc-view?proc=ab%3a%3acontact%3a%3adisplaywidget>ab::contact::displaywidget</a> is
provided to return a simple widget displaying all of the information in a contact (including all associated
addresses).</li>
</ul>
</li>
<li> <h5>Views</h5>
<ul>
<li><code>ab_contacts_complete</code> - A flat view of all contacts along with the primary work_phone, home_phone,
fax, other and email fields. Note that this does not attempt to join in a primary street address as this is
a complicated data structure best suited to custom logic.</li>
<li><code>ab_contacts_related</code> - A wrapper around <code>ab_contacts_complete</code> that returns all
contacts that are associated with other objects through contact_rels along with the <code>rel_id</code> and
associated <code>object_id</code>.
</ul>
</li>
</ul>
<h3>VII. Data Model Discussion</h3>
<p>
The tables associated with the object types above may be manipulated through standard legal ACS practices. Inserts and deletes should
be carried out through the PL/SQL API, but updates are allowed. Developers are advised to use the PL/SQL API to manipulate
<code>sort_key</code> fields unless they are willing to accept the responsibility of keeping <code>sort_key</code>s unique within a
contact in the multi-user environment (which can be a daunting task).
<h3>VIII. User Interface</h3>
<p>
The User Interface of Address Book is entirely targeted at the end user. It supports a single-step contact creation
to speed data entry, and a robust editing system in which the user may modify any basic information, attribute,
or address by selecting it on the view page. The address book listing page is fully sortable and searchable.</p>
<h3>IX. Configuration/Parameters</h3>
<p>
Address Book takes no special configuration.
</p>
<h3>X. Future Improvements/Areas of Likely Change</h3>
<p>
The most likely change to Address Book is a PalmOS synchronization
conduit. Other features may be added as found necessary.
</p>
<h3>XI. Authors</h3>
<ul>
<li> System creator: John Mileham (<a href=jmileham@arsdigita.com>jmileham@arsdigita.com</a>)
<li> System owner: John Mileham (<a href=jmileham@arsdigita.com>jmileham@arsdigita.com</a>)
<li> Documentation author John Mileham (<a href=jmileham@arsdigita.com>jmileham@arsdigita.com</a>)
</ul>
<h3>XII. Revision History</h3>
<table cellpadding=2 cellspacing=2 width=90% bgcolor=#efefef>
<tr bgcolor=#e0e0e0>
<th width=10%>Document Revision #</th>
<th width=50%>Action Taken, Notes</th>
<th>When?</th>
<th>By Whom?</th>
</tr>
<tr>
<td>0.1</td>
<td>Creation</td>
<td>01/05/2001</td>
<td>John Mileham</td>
</tr>
</table>
<p>
<hr>
<a href="mailto:jmileham@arsdigita.com">jmileham@arsdigita.com</a>
</body>
</html>