Collection (attribute of property)

From JRapid

Jump to: navigation, search

collection is an attribute of property.

This attribute may take the values:


Contents

Description

The collection attribute enables a property to make reference to more than one value. These may be built-in or entity type values.

When used with entity type properties, collection properties allow you to create one-to-many and many-to-many relationships between entities.



Collection properties behave in different ways depending on their kind (list, set, sortedset), and the embedded and extendable attributes.

When a collection makes reference to an entity of which a large number of records exist, you may use the comboproperty to define a filtering criteria in order to narrow down the number of options when choosing.

Properties of collection type may use the subset and subsetparams attributes to restrict the records that may be referenced in that property.

Types of collection

List

Lists are simple collections of items that permit all elements, including null values.

This kind of collection adds a hidden column n to the table that models the relationship when used for primitive data types, such as collection of strings or integers. This column is used for storing the order of the items in the collection.

When a list collection is of entity type, the entity must define a property of type integer to be used as index. This property must be specified on the collection property using the listindex attribute.

Set

Sets are collections that contain no duplicated items.

Sortedset

Sortedset is a set of elements to which an order can be applied.

Usage

<property
               ...
               collection = "set | list | sortedset"
               embedded = "inline | detail | grid"
               extendable = "extendable"
               ...
/>

Example

  • Many-to-many relationships:

The following Industry entity represents the different types of industries.

 <entity label="Industry" name="Industry">
        <property display="primary" label="Industry" name="name"/>
 </entity>

If a prospect belongs to several industries, the Prospect entity should specify an industries collection property of entity type Industry.

 <entity label="Prospect" name="Prospect">
        <property display="primary" label="Name" name="name"/>
        <property collection="set" entity="Industry" label="Industries" name="industries"/>
 </entity>

In this case, a many-to-many relationship is created. This means that many prospects may belong to many industries.

The default generated widget is known as selectmultiple. It shows a list with the selected items and an Add button. This button opens a pop-up list with all the available options. Items can be selected or removed by double clicking, or by using the Add and Remove buttons. When using a collection type where order matters, the up and down arrow keys may be used to change the order.

Collection set

The underlying database tables generated to support this relationship are shown here.

Many-to.many relationship


In order to make a large set of options easier to handle, we can add the comboproperty attribute and define the search criteria to use for narrowing down the industries listed. In this case, we use the name property. Note that you must create a filter on the name property as well.

<entity label="Industry" name="Industry">
        <filter display="primary" label="Name" name="name" property="name"/>
        <property display="primary" label="Name" name="name"/>
</entity>

<entity label="Prospect" name="Prospect">
        <property display="primary" label="Name" name="name"/>
        <property collection="set" comboproperty="name" entity="Industry" label="Industries" name="industries"/>
</entity>

And the resulting widget now includes a filter.

Selectmultiple with filter

Imagine that the Industry entity has a boolean Active property and that we want the industries collection in the Prospect entity to show only the active records. We create the corresponding subset for the Industry entity and then we set the subset attribute for the industries property in the Prospect entity.

<entity label="Industry" name="Industry">
        <subset name="forActive">
            <condition field="active" value="true"/>
        </subset>
        <filter display="primary" label="Name" name="name" property="name"/>
        <property display="primary" label="Name" name="name"/>
        <property display="secondary" label="Active" name="active" type="boolean"/>
</entity>

<entity label="Prospect" name="Prospect">
        <property display="primary" label="Name" name="name"/>
        <property collection="set" comboproperty="name" entity="Industry" label="Industries" name="industries" subset="forActive"/>
</entity>

After making this changes, the selectmultiple widget shows only the industry records marked as active.

Selectmultiple with subset


  • One-to-many relationships:

One-to-many relationships are created when the embedded attribute is set for a collection property and a childproperty attribute is specified. The childproperty attribute defines the property on the related entity that will hold the reference to its parent entity.

In this example, the Company entity acts as the parent entity, holding a collection of Employee records. The Employee entity has a company property that specifies the Company to which the employee belongs. This company property is specified as the childproperty for the collection of Employee in the Company entity.

 
 <entity label="Company" name="Company">
        <property name="name" label="Name" display="primary" />
        <property embedded="inline" childproperty="company" collection="set" entity="Employee"
                  label="Employees" name="employees" extendable="extendable" />
 </entity>

 <entity label="Employee" name="Employee">
        <property name="firstName" label="First Name" display="primary" />
        <property name="lastName" label="Last Name" display="primary" />
        <property entity="Company" label="Company" name="company" display="primary" />
 </entity>

The result of the above code will be a one-to-many relationship from Company to Employee. One Company can have many Employees and each employee can belong only to one Company.

Collection embedded inline

The following diagram shows the tables generated to support this kind of collection.

Collection embedded inline resulting tables


  • Collection of built-in types:

A more simple collection is one that stores values of built-in type, such as strings, integers, etc.

 <entity label="Student" name="Student">
        <property display="primary" label="Name" name="name"/>
        <property collection="set" label="Sports" name="sports"/>
 </entity>

The generated form looks like the following image.

String collection set

And the underlying tables are genertated as shown below.

String collection set database tables

See also

Personal tools