Reusing the same Express entity in multiple associations

Concrete CMS supports the reuse of Express Associations to create complex data structures. The key to accomplish this task is to ensure each association is named with a unique handles to avoid conflicts.

In this example, we will set up and test a data object named "Boardroom" with multiple associations to an "Atomik Employee" object.

Step 1: Define Your Data Objects

First, ensure you have at least two data objects to associate. In our example, we have "Boardroom" and "Employee".

1. Atomik Employee Object: This object is created automatically by the Atomik theme when its documentation is installed. If the object cannot be found, go to Dashboard > Pages & Themes > Themes and select Create Documentation from the Atomik theme settings menu. We will use this object to represent the members of the boardroom.
2. Boardroom Object: Go to Dashboard > Express and select Add Object. Name the object "Boardroom" with the handle boardroom and the plural handle boardrooms.

Step 2: Establish Associations

We will create multiple associations to the Employee object from the Boardroom object:

1. Chairperson Association:

   • Add a new association and select "Atomik Employee" as the target object.
   • Choose the association type "Many to One".
   • Change the default Target Property Name from atomik_employee to chairperson by ticking the checkbox and editing the value. Although the default value is often sufficient, in this case, a unique property name describing the association must be set in order to allow for more than one association between the Boardroom and Atomik Employees object.

2. Secretary Association:

   • Add another association and select "Atomik Employee" again.
   • Set the association type to "Many to One".
   • Name this association secretary.

3. Members Association:

   • Add another association and select "Atomik Employee" again.
   • Set the association type to "One to Many".
   • Name this association members.

Step 3: Add the associations to a forms

1. Make note of the order of the associations in the Boardroom object's Associations section. If it's not clear what the name of each association is, select each one to see the details. This is important because the target property name is not shown in this view nor in the edit form view. In the screenshot below, the first association is secretary, followed by members, and then chairperson.
2. Go to the Boardroom object's Forms section and create or edit a form for the Boardroom.
3. Add form controls to select the associations created. The order displayed in this view is the same as that shown in the first step above.
4. As you add each association to the form, add a Custom Label to clearly differentiate the form controls in the UI.

Step 4: Testing

1. Navigate to the Boardroom entries.
2. Test creating a Boardroom record by selecting an Employee for the Chairperson and other Employees for Members:
3. Save the form and verify that the associations are correctly listed in the Boardroom's details page:

Step 5: Programmatic Access

Developers can access these associations in custom code through the use of Magic Methods on the object. For example, getChairperson() accesses the chairperson association and getMembers() access the members association, both of which are Atomik Employee records.

Step 6: Debugging and Validation

If you encounter issues: - Check that each association has a unique handle. - Verify that the form controls are properly configured and saved. - Use logging and debugging tools to trace any errors during the association process.