Creating Non-Shared Embedded Objects

This topic describes how to create an embedded link within an entity. The entity whose fields will be embedded is referred to as the embedded entity. The entity whose form will display the embedded fields is referred to as the container entity.

For illustrative purposes, the screen shots that accompany these instructions illustrate how to embed fields from a Vehicles entity (the embedded entity) on a Passenger Vehicles form (the container entity).

Follow these step to create a non-shared embedded link:

1. Plan out the design of your container entity (or entities) and the embedded entity.
   
   • This includes identifying the list of fields that will be associated with each entity, the security settings for each entity, and how the entities will link together.
      
2. Create an Entities record for the embedded entity, including its fields. See Creating a New Entity for instructions.
   
   • The following figure illustrates the standard Vehicles form. These are the fields that will be added to the Passenger Vehicles form using an embedded link.  
     
     
3. Create the first container entity, if it does not already exist. Again, see Creating a New Entity for details.
   
   
   • For this step, complete the top area of the Entities form, add security settings, and add entity fields (except for the embedded link).
   • Keep in mind that the security settings on the embedded entity and the container entity should meet the design requirements that you identified in Step 1.
      
4. Open a new Fields record for the embedded link.
5. Enter a Name for the embedded link.
   
   • Aptify's standard naming convention for linked fields is the name of the linked entity (in its singular form) and the linked entity field. For example, the name of a field linked to the Vehicles entity's ID field would be VehicleID.
   • The Display Name fills in automatically when you specify a name.
      
6. Select the embedded entity from the Linked Entity drop-down list.
7. Select ID from the Linked Field drop-down list.
8. Select Embedded from the Link Type drop-down list. Leave Mode set to None. 
   
    
9. Configure the embedded link's Is Required behavior.
   
   • If you want to require a user to specify a value for all of the required fields in the embedded entity, leave the Is Required option selected under the Validation tab.
   • If you want to allow users to save the container record without specifying all of the required embedded fields, clear the Is Required option on the Validation tab and select the Allow Null option on the General tab.
     • This creates a foreign key that supports null values for records where the embedded link is not required.
        
   • In the Passenger Vehicles example, the designer would specify the VehicleID field as required since an organization would not want a user to save a Passenger Vehicles record without specifying the relevant vehicle information.
      
10. Click OK to save and close the Fields record.
    
    • You do not want to enable the field's Show In Find or Default In View options since you want the link to be transparent to users.
    • The Aptify Entity Virtual Fields wizard appears automatically when you close an embedded link's Fields record.
       
11. Use the wizard to create a virtual field for each of fields in the embedded entity that you want to display on the container entity's form.
    
    • Select the Create check box for each field you want to embedded in the container entity. At a minimum, you must create a virtual field for each of the required fields in the embedded entity, except for ID. (Do not create a virtual field for the embedded entity's ID field.)
    • The Create check box is automatically selected for all required fields. In figure below, the ManufacturerID and Model fields are required fields in the Vehicles entity.
      
       
    • If you want the field to appear in views of the container entity by default, select the check box in the corresponding Default In View box.
    • Enter the name of the field in the Virtual Field column. The name cannot contains spaces or dashes. Aptify recommends the following naming convention: [Singular form of embedded entity name]ID_[Field Name]. For example, the Model virtual field in the figure below is VehicleID_Model.
      
      
       
    • Enter the name that will appear as this field's caption on the container entity's form and in views of the container entity. Typically this will be the field's name with appropriate spacing (such as, Engine Type).
    • Enter a Description for one or more virtual fields, if desired.  
      
      
12. Click OK to create the virtual fields.
    
    • Note that if the embedded link is not required, the virtual field's Join Type is Optional. If the embedded link is required, the virtual field's Join Type is Required. If you subsequently change the embedded link's Is Required field, the Join Type values for the related virtual fields update automatically when you save the entity. See Join Type.
    • A Virtual Field inherits the SQL Data Type of the Fields record it is linked to.
    • If applicable, a Virtual Field inherits the Values record and Default Value setting of the Fields record it is linked to. (Note that while the values appear in the drop-down list for the embedded field on a top-level form, the Values tab on the Virtual Field remains blank though.) 
      
      
13. If you want one or more of the virtual fields to appear on a tab other than General on the generated form, open the applicable Fields record and enter the tab name in the Category field.
14. Add any additional fields to the container entity, and configure the other entity settings as needed.
15. Save and close the Entities record.
16. Open the container entity's generated form.
    
    • The embedded virtual fields appear as fields on the container form. See Important Notes Concerning Embedded Objects for information on how to use forms that include embedded links.  
      
      
17. Repeat steps 3 to 16 to create additional container entities, as needed.