Related Objects Picker Control

Layouts

By default, the Related Objects Picker Control can be used only in the Dialog page layout.

Layout Designer 

Your next step is to set up the Related Object Picker control in Layout Designer:

• Locate an existing Related Object Picker on the canvas in Layout Designer, add a new one from the Toolbox, or drag&drop necessary Data Model attribute that has suitable for the Related Object Picker control data type (Object Reference). The controls added from the Data Model are suggested as follows:

• Click the control on the canvas to open up its properties in the right-hand panel. Properties that the Related Object Picker has in Layout Designer are defined in the Related Object Picker Control Descriptor.

Minimal required property settings   

These properties are enough for the correct displaying of the object picker field in the application. Other properties can be adjusted as described below.

The following data model properties are minimum required for the objects picker display in the runtime:

• Value: the field that serves at the same time as a source of the suggested in the related object picker values and as the attribute of the Data Definition that stores the chosen from the picker values. Only Object Reference attributes can be used;
• Label: the title of the displayed field.

Additionally, you may need to configure:

• Display expression: if the reference to the Data Definition (see Value property) does not have the default Display Expression, specify an ASQL expression for correct displaying of the suggested object names in the related objects picker list.
• Column definition: a set of columns that are displayed on the Select Object(s) page when the user clicks Show More link or the lookup icon.

Value (Model)

The main property of the Control keeps the data about selected objects. The data structure principle is fully identical to the structure of the Value of the Objects Relation Grid.  All the associated related objects are stored in the Database and directly retrieved by the control for display, and are not reflected in the Value data. Value data stores only the changes in relations, e.g. which Objects have been added or removed in comparison with the persisted state (related objects stored in the Database).  On submitting the Dialog with such control the affected changes (added or removed objects) are applied on the server.

The following example demonstrates the Value structure:

{
    AddedRelations:['{id1}', '{id2}'],
    RemovedRelations:['{id3}']
}
// where {id1}, {id2}, {id3} - unique objects identificators (guid)

The Value property includes both Entity Class and Relation Attribute Name. Both attributes specify the schema relation which is handled in the Control.

Entity Class is the name of the Data Definition which owns the relation, and the Relation Attribute Name is the name of the schema relation.
For example, for the relation which stores the members of the Role, the Entity Class = "SPSSecurityClassRole", the Relation Attribute Name = "Memebers"

Object Id (Model)

Sets the Id of the Object which owns the Relation. When control is used on Dialog, the setting of the Property is optional, as the ID is automatically detected from the Dialog context. 

Selected Items (Model)

Specify the attribute of the data model that will store the following data from the items that have been selected in the application run time:

• Id
• ObjectId
• EntityType
• DisplayString

Selected IDs (Model)

Specify the attribute of the data model that will store the IDs of the fragments that have been selected in the application run time.

Other Properties

For the rest of the Properties see relating Object Picker control, which has quite the same properties and settings, with the only difference, it picks a single object only.