¬Associations

The relationship between a user-interface object (or display object) and enterprise object values is managed by an EOAssociation object, whichs bind aspects of the display object to class properties, or keys, of the enterprise objects in one or more EODisplayGroups. The association typicially makes the display object show the value for the selected enterprise object's property, but can also enable or disable the display object, set a list of potential values, or otherwise control the display object's state based on the enterprise objects selected.

Different association subclasses offer different behaviors in displaying values and responding to actions initiated by the display object. Some merely display values; some set values when the display object's value changes; some insert a new object or change a relationship when the display object is acted on. Each specific subclass can work with different kinds of display objectsÐInterface Builder presents the compatible association subclasses in its Connections Inspector.

Enterprise Objects Framework 2.0 introduces multi-aspect associations, which allow several different properties, potentially from different display groups, to be bound to a single display object. For example, the associations for user interface controls such as text fields, buttons, and radio buttons have the aspects ªvalueº and ªenabledº. You can associate ªvalueº with a key in an enterprise object and ªenabledº with a key in an enterprise object whose value determines whether or not that control should be enabled.

EOF 2.0 provides the following associations:

EOControlAssociation, EOActionCellAssociation

Display objects: Any NSControl subclass, any NSActionCell subclass

The EOControlAssociation and EOActionCellAssociation classes bind a control or cell to properties of the selected EO in an EODisplayGroup.

Aspect	Binding and Use
value	property of the EO to be displayed in the column
enabled	BOOL property of EO indicating whether control should be enabled

These associations communicate with their display objects using setObjectValue: and objectValue, which allows them to work with NSImageView and NSImageCell.

EOColumnAssociation 

Display objects: NSTableColumn

EOColumnAssociation links a single column of an NSTableView to a property of all EOs in an EODisplayGroup. The EOColumnAssociations take over the column identifiers to point to themselves. All of the EOColumnAssociations associated with a given NSTableView must be bound to the same EODisplayGroup.

Aspect	Binding and Use
value	Property of the EO to be displayed in the column.
enabled	BOOL property of EO indicating whether cell should be enabled

EOTextAssociation

Display objects: NSText, NSCStringText, NSTextView

The EOTextAssociation binds a text object to a property of an EO containing plain or rich text.

Aspect	Binding and Use
value	Text property of EO to be displayed in text view
editable	BOOL property of EO indicating whether the user should be allowed to modify the text.

The EOTextAssociation can be bound to either plain text (NSString), RTF (encoded in an NSData) or RTFD (also NSData). The type is determined by examining signature bytes in the beginning of the data. When the user modifies the text, the type to write back to the EO is determined by the settings in the text object.

Multiple Fonts	Allows Graphics	Type in EO
NO	NO	NSString text
YES	NO	NSData containing RTF
YES	YES	NSData containing RTFD

Note that in EOF 1.x, RTF was encoded in an NSString. EOF 2.0 uses an NSData for consistency with the NSText OpenStep API.

EOPopUpAssociation

Display objects: NSPopUpButton

EOPopUpAssociations are typically used to set to-one relationship properties. You do this by binding the ªtitlesº aspect to the destination entity's EODisplayGroup and one of the ªselectedXxxº aspects to the source entity's EODisplayGroup. See below for examples.

Aspect	Binding and Use
titles	Any property with unique values representable as a string. Makes a uniqued list of the values for the bound key in the display group, and sets the pop-up list's titles to these values. If not bound, the title list already in the popup is undisturbed.
selectedTitle	String property of the EO containing the title to select in the popup. When the pop-up list's selection changes, the EO's property is set to the new title. When the selected EO changes, the pop-up list item with a matching title is selected.
selectedTag	Integer property of the EO containing the tag to select in the popup. When the popup selection changes, the EO's property is set to the new tag. This might be useful for localization purposes. Titles are usually set in Interface Builder, not with the ªtitlesº aspect. When the selected EO changes, the pop-up list item with a matching tag is selected. You can add a single temporary tag for ªotherº values using setTagValueForOther:.
selectedObject	Relationship property of the EO containing the EO to select from the display group bound to ªtitlesº. When the selected EO changes, the pop-up list item with a matching relationship destination is selected. ªselectedObjectº is usually mutually exclusive with ªselectedTitleº.
enabled	BOOL property of EO indicating whether the pop-up button should be enabled.

Examples:

Selecting a string from a static list: Given a display group of Movies, the goal is to provide a pop-up list for setting the rating. Assume the rating is a string propery of the Movie object rather than a relationship to a Rating EO. In this case you type the list of ratings into the pop-up list in Interface Builder, and then bind the ªselectedTitleº aspect to the ªratingº property of the Movie display group.

Selecting a string from a dynamic list: As above, but we want to fill the popup from the ªratingStringº property of a display group containing an array of Rating objects fetched from an external source. In this case you bind the ªtitlesº aspect to the ªratingStringº property of the Ratings display group, and bind the ªselectedTitleº aspect to the ªratingº property of the Movie display group.

Selecting an EO to assign to a to-one relationship: Given a list of employees, the goal is to assign the department each employee belongs to. In terms of the object model, we want to assign a Department EO to the ªdepartmentº property of an Employee EO. In this case you bind the ªtitlesº aspect to the ªnameº property of a Department display group, and bind the ªselectedObjectº aspect to the ªdepartmentº relationship property of the Employee display group.

EOActionAssociation

Display objects: NSControl, NSActionCell

Upon receiving an action message from its object, the EOActionAssociation invokes a method named by its ªactionº aspect on all EOs selected in the display group to which it is bound. This is most often used to bind a button to a method in an EO.

Aspect	Binding and Use
action	The name of the method to invoke, typically added in Interface Builder to the properties of the display group.
editable	BOOL property of EOs indicating whether the object should be enabled

EODetailSelectionAssociation

Display objects: EODisplayGroup

An EODetailSelectionAssociation manages a to-many relationship from one display group to another. When the selection changes in the master display group (the object established using initWithObject:), the values of the to-many relationship are selected in the detail display group (the one bound using bindAspect:displayGroup:key:).

Aspect	Binding and Use
selectedObjects	Relationship property of the EO containing objects to be selected in the bound display group.

Examples:

Suppose we have a display group for Employee objects, each of which has a ªtoProjectsº property that lists the project the employee is working on. Binding an EODetailAssociation from the Employee display group to the Project display group on the ªtoProjectsº key causes the Project display group to change its selection to match the projects of the employee selected in the Employee display group. Changing the selection in ths Project display group correspondingly adds or remove objects from the ªtoProjectsº relationship of the selected employee.

EOMasterDetailAssociation

Display objects: EODisplayGroups whose data sources are EODetailDataSources

EOMasterDetailAssociation binds a detail display group to a relationship property of the selected object in a master display group. The detail display group's data source must be an EODetailDataSource, getting its objects through the master rather than on its own. This limits the keys that can be bound to class properties of the master display group's entity. When the selection changes in the master display group, or when the contents of the bound property change in the selected object, the detail display group is sent a qualifyWithRelationshipKey:ofObject: message to change its qualifier and a fetch message to retrieve the new data to display.

Aspect	Binding and Use
parent	The property key in the master object to display in the detail.

EOMasterPeerAssociation

Display objects: EODisplayGroups whose data sources are not EODetailDataSources

EOMasterPeerAssociation binds a detail display group to a relationship property of the selected object in a master display group. It differs from EOMasterDetailAssociation in that the detail display group's data source gets values on its own, so it isn't limited to class properties of the master. This is called a ªqualified peerº configuration. In this configuration, the master and detail operate independently, so changes to one don't appear in the other. For example, adding an employee to a detail display group in this configuration doesn't automatically update the Department display group or assign foreign keys in the enterprise objects. In general, qualified peer configurations should be used hen no insertions and deletions will be performed in the detail.

When the selection changes in the master display group, or when the contents of the bound property change in the selected object, the detail display group is sent a qualifyWithRelationshipKey:ofObject: message to change its qualifier and a fetch message to retrieve the new data to display.

Aspect	Binding and Use
parent	The property key in the master object to display in the detail.

EOActionInsertionAssociation

Display objects: any that respond to setAction:

EOActionInsertionAssociation inserts the selected objects from a source display group into a destination display group when its display object invokes its action method. It automatically disables the display object if possible when there are no objects selected in the source and not exactly one selected in the destination.

Aspect	Binding and Use
source	The display group that objects should be copied from. The key named in the source binding is irrelevant. 
destination	A relationship property in the display group to add source EOs to.

Example:

Suppose we have a display group containing Talents (actors and directors), and one containing Movies, and a button with an EOActionInsertionAssociation bound to the Talent display group as the source and the ªdirectorsº property of the Movies display group as the destination. Clicking the button causes the selected Talent EOs to be inserted into the ªdirectorsº property of the selected Movie EO.

See also: ªMaking Connectionsº in Chapter 4 of the current EOF 2.0 Developer's Guide. It refers to the EOActionInsertionAssociation demonstrated in the ªMovie.nibº of the Movie example.

EORadioMatrixAssociation

Display objects: NSMatrix (see below)

The EORadioMatrixAssociation binds titles or tags of an NSMatrix in radio mode to string or integer attributes.
	
Aspect	Binding and Use
selectedTitle	String property of the selected EO. When the radio matrix selection changes, the title of the new selection is assigned to this property. When the selected EO changes, the matrix cell with a matching title is selected.
selectedTag	Integer property of the EO. When the radio matrix selection changes, the tag of the new selection is assigned to this property. This might be useful for localization purposes. When the selected EO changes, the matrix cell with a matching tag is selected. You can add a single temporary tag for ªotherº values using setTagValueForOther:. If this aspect is used, radio button titles should always be set manually using Interface Builder.
enabled	BOOL property of EO indicating whether the radio matrix should be enabled.

EOPickTextAssociation

Display objects: NSControl

The EOPickTextAssociation applies a qualifier to a display group based on the contents of its text control. Up to three different LIKE qualifiers can be formed from the value in the text control.

Aspect	Binding and Use
matchKey1	Key to match field text to with LIKE qualifier.
matchKey2	Key to match field text to with LIKE qualifier
matchKey3	Key to match field text to with LIKE qualifier

When the text of the association's control changes, a qualifier is contructed of the form:

(<matchKey1> LIKE "*<text>*") OR (<matchKey2> LIKE "*<text>*") OR (<matchKey3> LIKE "*<text>*")

For example, in a list of people matchKey1 and matchKey2 might be bound to ªlastNameº and ªfirstNameº. If the user then types ªBiº in the field, the association applies the following qualifier to the display group:

(lastName LIKE "*Bi*") OR (firstName LIKE "*Bi>*")

which might match ªBill Smithº and ªJoe Biggsº.