Custom Relationships

Overview

This page needs an overview

Creating Custom Relationships

Relationships are initially defined in the module's vardefs file under the relationships array. For reference, you can find them using the vardef path as follows:

./modules/<module>/vardefs.php

Custom relationships are created in a different way using the Extension Framework. The process requires two steps which are explained in the following sections:

Defining the Relationship MetaData
Defining the Relationship in the TableDictionary

Defining the Relationship MetaData

The definitions for custom relationships will be found in a path similar to:

./custom/metadata/<relatonship name>MetaData.php

This file will contain the $dictionary information needed for the system to generate the relationship. The $dictionary array will contain the following:

Index	Type	Description
true_relationship_type	String	The relationship's structure (possible values: 'one-to-many' or 'many-to-many')
from_studio	Boolean	Whether the relationship was created in Studio
table	String	The name of the table that is created in the database to contain the link ids
fields	Array	An array of fields to be created on the relationship join table
indices	Array	The list of indexes to be created
relationships	Array	An array defining relationships
relationships.<rel>	Array	The array defining the relationship
relationships.<rel>.lhs_module	String	Left-hand module (should match $beanList index)
relationships.<rel>.lhs_table	String	Left-hand table name
relationships.<rel>.lhs_key	String	The key to use from the table on the left
relationships.<rel>.rhs_module	String	Right-hand module (should match $beanList index)
relationships.<rel>.rhs_table	String	Right-hand table name
relationships.<rel>.rhs_key	String	The key to use from the table on the right
relationships.<rel>.relationship_type	String	The relationship type, typically stored as 'many-to-many'
relationships.<rel>.join_table	String	The join table
relationships.<rel>.join_key_lhs	String	Left table key, should exist in table field definitions above
relationships.<rel>.join_key_rhs	String	Right table key, should exist in table field definitions above

MetaData Example

Creating a custom 1:M relationship between Accounts and Contacts will yield the following metadata file:

./custom/metadata/accounts_contacts_1MetaData.php

<?php

// created: 2013-09-20 15:15:47

$dictionary["accounts_contacts_1"] = array (
  'true_relationship_type' => 'one-to-many',
  'from_studio' => true,
  'relationships' =>
  array (
    'accounts_contacts_1' =>
    array (
      'lhs_module' => 'Accounts',
      'lhs_table' => 'accounts',
      'lhs_key' => 'id',
      'rhs_module' => 'Contacts',
      'rhs_table' => 'contacts',
      'rhs_key' => 'id',
      'relationship_type' => 'many-to-many',
      'join_table' => 'accounts_contacts_1_c',
      'join_key_lhs' => 'accounts_contacts_1accounts_ida',
      'join_key_rhs' => 'accounts_contacts_1contacts_idb',
    ),
  ),
  'table' => 'accounts_contacts_1_c',
  'fields' =>
  array (
    0 =>
    array (
      'name' => 'id',
      'type' => 'varchar',
      'len' => 36,
    ),
    1 =>
    array (
      'name' => 'date_modified',
      'type' => 'datetime',
    ),
    2 =>
    array (
      'name' => 'deleted',
      'type' => 'bool',
      'len' => '1',
      'default' => '0',
      'required' => true,
    ),
    3 =>
    array (
      'name' => 'accounts_contacts_1accounts_ida',
      'type' => 'varchar',
      'len' => 36,
    ),
    4 =>
    array (
      'name' => 'accounts_contacts_1contacts_idb',
      'type' => 'varchar',
      'len' => 36,
    ),
  ),
  'indices' =>
  array (
    0 =>
    array (
      'name' => 'accounts_contacts_1spk',
      'type' => 'primary',
      'fields' =>
      array (
        0 => 'id',
      ),
    ),
    1 =>
    array (
      'name' => 'accounts_contacts_1_ida1',
      'type' => 'index',
      'fields' =>
      array (
        0 => 'accounts_contacts_1accounts_ida',
      ),
    ),
    2 =>
    array (
      'name' => 'accounts_contacts_1_alt',
      'type' => 'alternate_key',
      'fields' =>
      array (
        0 => 'accounts_contacts_1contacts_idb',
      ),
    ),
  ),
);

Defining the Relationship in the TableDictionary

Once a relationship's metadata has been created, the metadata file will have a reference placed in the TableDictionary:

./custom/Extension/application/Ext/TableDictionary/<relationship name>.php

This file will contain an 'include' reference to the metadata file:

<?php

    include('custom/metadata/<relationship name>MetaData.php');

?>

TableDictionary Example

The custom 1:M relationship between Accounts and Contacts will yield the following TableDictionary file:

./custom/Extension/application/Ext/TableDictionary/accounts_contacts_1.php

<?php

    //WARNING: The contents of this file are auto-generated

    include('custom/metadata/accounts_contacts_1MetaData.php');

?>

If you have created the relationship through Studio, the files above will be automatically created. If you are manually creating the files, run a Quick Repair and Rebuild and run any SQL scripts generated. The Quick Repair and Rebuild will rebuild the file map and relationship cache as well as populate the relationship in the relationships table.