The subset element is used for restricting the results shown by listings, filters or entity-type properties. A subset is defined as a portion of a set of elements, the set being in this case all the records for a particular entity. Subsets may specify the properties to retrieve from the database for each record and the order in which the records should be listed.
It can be understood also by comparing it to SQL languages or Relational Algebra:
- Conditions that filter the list of records (selection)
- Specification of properties (database columns) to be shown (projection)
Subsets select the listed records using conditions and restrictions. Conditions operate with property values and restrictions specify more advanced expressions like HQL queries. Both conditions and restrictions can be grouped using the or and and tags to get extra restriction logic.
Each subset will provide an associated web service and method that will return only the specified records with the specified properties.
As said above, subsets restrict results shown by listings. A listing without a subset will show all the records present in the database for the entity. A listing which specifies a subset can return all, none or some instances of the entity. In other words, a listing that specifies a subset only shows the records that meet the specified conditions and/or restrictions for the subset.
Subsets allow the developer to override default entity order and display properties through the use of the order and displayproperties attributes.
A basesubset attribute can be used to extend form another subset. The subset used as basesubset cannot receive parameters. The new subset will inherit every condition and restriction present in the basesubset, but not the order or displayproperties.
To do it through the JRapid Designer, in the Entity Diagram look for the entity to which you want to add the subset, move the mouse pointer over the (+) button and click on the Subset option.
<subset name = NAME displayproperties = COMA_SEPARATED_PROPERTIES order = ORDER basesubset = SUBSET (restrict?, (param|condition|and|or|restriction)*) />
A simple example for a subset defines a condition to filter records that have a certain value in a property. If the value is constant, then there is no need to specify parameters.
A Company entity, with a boolean property active can be defined as follows, including a subset to retrieve only the active records ordered by name, and a listing that uses the subset to see the outcome.
<entity label="Company" menu="Company" name="Company"> <listing name="listingActive" subset="forActive"/> <subset name="forActive" order="name"> <condition field="active" value="true"/> </subset> <property display="primary" label="Name" name="name" required="required"/> <property display="secondary" label="Active" name="active" type="boolean"/> </entity>
And the resulting listings look like this.
The same subset may be used to restrict the records shown by an entity-type property in another entity's form.
<entity label="Contact" menu="Contact" name="Contact"> <property display="primary" label="First Name" name="name" required="required"/> <property display="primary" label="Last Name" name="lastName" required="required"/> <property display="secondary" entity="Company" label="Company" name="company" subset="forActive"/> </entity>
The company property in the Contact form only lists the active companies. This pictures show how the property select box behaves without and with the subset.
- subset (attribute of property)
- subset (attribute of listing child of entity)
- subsetparams (attribute of property)
- basesubset (attribute of subset)