EmbeddedListing elements are usually based on parameterized subsets, so the containing form may filter the records shown according to the context.
For example, when two entities are connected by a parent-child relationship, there are two common solutions.
- Use an embedded collection if:
- The relationship is weak (the children may not exist without the parent).
- The children are simple entities with a few fields so they could be presented embedded.
- There will be few children (less than 10) for each parent.
- Use an embeddedlisting if:
- The relationship is strong (children may survive with no parent).
- The children are complex entities so they should be opened in a new window.
- There could be a lot of children for a single parent (10+).
<entity ... > ... <embeddedlisting name = NAME label = LABEL entity = ENTITY listing = LISTING subset = SUBSET subsetparams = PARAMS /> </entity>
Suppose we have a Company entity and a Sale entity, where each sale record belongs to one company. Let see how we may embed a listing of sales inside the Company form, filtering the sales shown to the corresponding company. We use a subset on the Sale entity for this. The subset receives a Company as a parameter.
A custom listing is also created for the Sale entity and used in the embeddedlisting element. This allows not only the use of the subset but the customization of the properties to be shown in the embedded listing. Note that the default display primary properties for the Sale entity are the sale date, the company and the amount, and the properties shown in the embeddedlisting are the ones included in the displayproperties attribute of the emebedded listing.
We also use a defaultset on the Sale entity that receives a Company as a parameter. This allows the new created Sale records from within the embeddedlisting to be initialized with the corresponding company value.
<entity label="Company" menu="People" name="Company"> <property display="primary" label="Name" name="name"/> <embeddedlisting defaultset="defForCompany" defaultsetparams="." entity="Sale" label="Sales" listing="forCompanyListing" name="sales" subset="forCompany" subsetparams="."/> </entity> <entity label="Sale" menu="Sales" name="Sale"> <listing displayproperties="saleDate,amount" name="forCompanyListing" subset="forCompany"/> <defaultset name="defForCompany"> <param entity="Company" name="companyParam"/> <default name="company" value="companyParam"/> </defaultset> <subset name="forCompany"> <param entity="Company" name="companyParam"/> <condition field="company" value="companyParam"/> </subset> <property display="primary" type="date" label="Date" name="saleDate" widget="jdatepicker"/> <property display="primary" entity="Company" label="Company" name="company"/> <property display="primary" label="Amount" name="amount" type="double"/> </entity>
The generated Company form includes a sales listing. This listing shows the sale records corresponding to the Company being edited.