Sugar 5.1 brought many improvements to the Sugar application framework. In this release, we introduced a new method for creating custom relationships in Studio and Module Builder called the Relationship Editor. This new editor consolidates the functionality of the old “relationship fields” which worked as basic one-to-many relationships as well as the many-to-many relationships that are produced from creating relationships in the 5.0 Module Builder.
As there have been questions regarding how to use this new editor and how exactly it works, this article will cover the inner workings of the Relationship Editor.
Using the 5.1 Relationship Editor:
When you open up the new Relationships view in Studio, all the relationships involving the current module are listed including the out-of-the-box relationships. Custom relationships are given an asterisk next to their name. None of the out-of-the-box relationships are editable or removable from Studio and are only listed for reference. However new custom relationships can be created.
In Module Builder, all relationships are fully editable. Clicking the “Add Relationship” button will bring up the new Relationship Editor.
Here you can select the type of relationship as well as the related module, the label to use on any SubPanels, and what SubPanel definition to use.
Now let’s dig into some of the details behind the scenes for SubPanels. The available SubPanels are stored in “modules/<module_name>/metadata/subpanels”. An important thing to keep in mind is where the SubPanel definition actually resides. For instance, the Opportunity SubPanel shown in the Contact’s DetailView is stored in the Opportunity directory and not the Contact directory.
When in Studio or Module Builder, the primary module field is always the module you are currently working in. Changing the type of the relationship changes what options are available for SubPanels and modules. (Not all modules support all relationship types.)
An important tip to keep in mind is that the best practice is to create relationships involving a custom module in Module Builder and not in Studio. This produces a cleaner set of metadata definitions in the custom directory, keeps changes consistent, and can help minimize the chance of problems when upgrading or uninstalling custom modules.
With 5.1, a question that comes up quite often is, “when to use the relationship field in the field editor?” The answer is “almost never“. It was left in for backwards compatibility with custom modules created in 5.0 and loaded into 5.1’s Module Builder/Studio.
Going under the hood:
The custom relationship system actually uses a couple of mechanisms in order to build and install these relationships into both the metadata and the database.
The first step when the system creates a new relationship is to save a temporary metadata file describing the relationship. If you are working in Module Builder, this file is created in “custom/modulebuilder/packages/
/modules/<module_name>/relationships.php” and for Studio look in “custom/working/modules/<module_name>/relationships.php”. This file contains a complete description of the relationships for this module including modules, ids, tables, and SubPanels.
When you deploy/install a custom module or deploy a custom relationship from Studio, the Module Loader reads this file and generates the necessary extension and layout files for the relationships. The relevant files are:
- custom/metedata/<relationship_name>MetaData.php - The dictionary metadata entries for this relationship
- custom/Extension/modules/<module_name>/Ext/Vardefs/<relationship_name>.php - Fields required for this relationship.
- custom/Extension/modules/<module_name>/Ext/Language/<relationship_name>.php - Labels used in this relationship.
- custom/Extension/applications/Ext/Language/TableDictionary/<relationship_name>.php - File used to ensure dictionary metadata is included in the TableDictionary
- custom/Extension/modules/relationships/language/<module_name>.php – If the relationship was one-to-many or one-to-one, field labels will be added to these files.
- custom/Extension/modules/relationships – A set of the above files used by the Module Loader but not used when rebuilding extensions.
If for some reason you have issues with your Sugar system after removing custom relationships, you can check to see if any of the files remain. Removing these files from the file system will remove the custom relationship from the application. If you remove these files or make any manual changes, be sure to run Quick Repair and Rebuild from the Repair administration screen.
In addition to these files, a new linking table will be created in 5.1 to store the relationship data no matter what type of relationship is selected. This is a major difference between 5.1 relationships and 5.0 relationship fields. Even if a one-to-one or one-to-many relationship is created, a new column is no longer created in the module’s table or _cstm table as in 5.0 but rather the linking table is used.
Hopefully this gives you a good idea of how custom relationships function in SugarCRM 5.1. Feel free to post questions or comments.