How to use 'displayproperties'

06/10/2008. Evangelina Martinez Ruiz Moreno

Using it as a property attribute

Let's say we have a 'Collector' entity and a 'Record' entity as defined below.

<entity name="Collector" label="Collector" >
    <property name="firstName" label="First Name" display="primary"/>
    <property name="lastName" label="Last Name" display="primary"/>
    <property name="record" entity="Record" label="Record" display="primary"/>
</entity>

<entity name="Record" label="Record" >
    <property name="title" label="Title" display="primary" />
    <property name="artist" label="Artist" display="primary"/>
    <property name="year" label="Year" type="integer" display="primary" />
</entity>

Right now in the listings of the 'Collector' entity all of the properties of the 'Record' entity are displayed, but it seems unnecessary to display the year of the record, so we restrict the display properties on the 'Collector' entity using the displayproperties attribute:

<entity name="Collector" label="Collector" >
    <property name="firstName" label="First Name" display="primary"/>
    <property name="lastName" label="Last Name" display="primary"/>
    <property name="record" entity="Record" label="Record" displaylayproperties="title, artist" />
</entity>

Notice that we have also changed the order of the properties displayed.

Using it on subsets and listings

If you see yourself repeating the same displayproperties attribute on some entity it is a sign that you should be using a subset. In a subset you can define which properties of the entity to display, and then use that listing on all the properties that you were using displayproperties. This approach is better since it avoids repetition of code and it's easier to maintain.
Let's define a subset for the 'Collector' entity and use it on two other entities:

<entity name="Record" label="Record" >
    <subset name="noYear" displayproperties="artist, title" />
    <property name="title" label="Title" display="primary" />
    <property name="artist" label="Artist" display="primary"/>
    <property name="year" label="Year" display="primary" />
</entity>

<entity name="Collector" label="Collector" >
    <property name="firstName" label="First Name" display="primary" />
    <property name="lastName" label="Last Name" display="primary" />
    <property name="record" entity="Record" label="Record" subset="noYear" />
</entity>

<entity name="Rating" label="Rating" >
    <property name="record" entity="Record" label="Record" subset="noYear" display="primary"/>
    <property name="collector" entity="Collector" label="Collector" display="primary"/>
    <property name="year" label="rating" display="primary" />
</entity>

Subsets can do a lot more that just changing the display properties, you can read the article Using Subsets for more information.

In a similar way, the displayproperties attribute can be added to listings and these in turn can be embedded on another entity using the embeddedlisting element or, if it's the only listing needed for the entity, set the listing as the default listing for the entity. Again, listings were made to do much more than just change the display properties; you can read  Using Listings to find out more.

In the following example we make a listing for the Record entity that sets the display properties that we want, and make this listing the default for the entity.

<entity name="Record" label="Record" defaultlisting="noYear">
    <listing name="noYear" displayproperties="artist, title" />
    <property name="title" label="Title" display="primary" />
    <property name="artist" label="Artist" display="primary"/>
    <property name="year" label="Year" display="primary" />
</entity>

<entity name="Collector" label="Collector" >
    <property name="firstName" label="First Name" display="primary" />
    <property name="lastName" label="Last Name" display="primary" />
    <property name="record" entity="Record" label="Record" />
</entity>

There is nothing to add to the 'record' property in the 'Collector' entity since the listing was set as the default.

Accessing Entities

If a property is of an entity type, its inner fields may be accessed to be selected as displayable properties. To do this, when writing the ?displayproperties? you can use a ?.? to access an entity. In the following example we create a listing for the Collector entity that displays inner fields of the Record entity.

Conclusion

The displayproperties attribute allows us to change what properties to display for an entity and the order to display them in. It may be used directly on a property if needed, but if it turns out that the same displayproperties have to be written more than once for an entity it is recommended to make a subset or a listing for that entity