ExpressionEngine® 3 User Guide

Legacy Documentation

You are using the documentation for version 3.5.17. Go here for the latest version or check here for your available upgrades to the latest version.

Relationships Fieldtype Extension Hooks

relationships_display_field

relationships_display_field($entry_id, $field_id, $sql)

Allows developers to modify the existing query that retrieves related entries for the publish field or to perform their own queries to return related entries.

How it’s called:

if (ee()->extensions->active_hook('relationships_display_field') === TRUE)
{
    $related = ee()->extensions->call(
        'relationships_display_field',
        $entry_id,
        $this->field_id,
        ee()->db->_compile_select()
    );
}
else
{
    $related = ee()->db->get()->result_array();
}

Note

To use this hook, you can either add to the existing Active Record call, or call ee()->db->_reset_select() to cancel the Active Record call and start your own, or modify the passed compiled SQL.

Parameters:
  • $entry_id (int) – Entry ID of entry being edited.
  • $field_id (int) – Field ID of field currently being loaded.
  • $sql (string) – Compiled SQL about to be run to gather related entries.
Returns:

Result Array of query result.

Return type:

Array

New in version 2.6.0.

relationships_display_field_options

relationships_display_field_options($entry_id, $field_id, $sql)

Allows developers to add additional filters to the entries that populate the select options available to the relationship field.

How it’s called:

if (ee()->extensions->active_hook('relationships_display_field_options') === TRUE)
{
    ee()->extensions->call(
        'relationships_display_field_options',
        $entries,
        $this->field_id,
        $this->settings
    );
}
Parameters:
  • $entries (object) – ChannelEntry model object.
  • $field_id (int) – Field ID of field currently being loaded.
  • $settings (array) – The field settings for the field being loaded.
Return type:

Void

New in version 3.3.0.

relationships_post_save

relationships_post_save($ships, $entry_id, $field_id)

Allows developers to modify or add to the relationships array before saving.

How it’s called:

$ships = ee()->extensions->call('relationships_post_save', $ships, $entry_id, $field_id);
Parameters:
  • $ships (array) – Array of entry IDs to be related to the entry.
  • $entry_id (int) – Entry ID of entry being saved.
  • $field_id (int) – Field ID of field currently being saved.
Returns:

Array of relationships.

Return type:

Array

New in version 2.6.0.

relationships_query

relationships_query($field_name, $entry_ids, $depths, $sql)

Allows developers to modify the existing query that retrieves related entries for front end tag parsing or to perform their own queries to return related entries.

How it’s called:

if (ee()->extensions->active_hook('relationships_query') === TRUE)
{
    $result = ee()->extensions->call(
        'relationships_query',
        $node->field_name(),
        $entry_ids,
        $depths,
        $db->_compile_select()
    );
}
else
{
    $result = $db->get()->result_array();
}

Note

To use this hook, you can either add to the existing Active Record call, or call ee()->db->_reset_select() to cancel the Active Record call and start your own, or modify the passed compiled SQL.

Parameters:
  • $field_name (string) – Name of current node being parsed.
  • $entry_ids (int) – Entry IDs of entries being queried for.
  • $depths (array) – Depth of branches.
  • $sql (string) – Compiled SQL about to be run to gather related entries.
Returns:

Result Array of query result.

Return type:

Array

New in version 2.6.0.

relationships_query_result

relationships_query_result($entry_lookup)

Allows developers to modify or add columns to the relationships array. Do not use this hook to remove elements.

How it’s called:

$entry_lookup = ee()->extensions->call('relationships_query_result', $entry_lookup);
Parameters:
  • $entry_lookup (array) – Array of entry IDs to rows for all relationship tags.
Returns:

Array of entry IDs to rows.

Return type:

Array

New in version 2.7.1.

relationships_modify_rows

relationships_modify_rows($rows, $node)

Allows developers to modify or add to the relationship rows right before parsing happens.

How it’s called:

$rows = ee()->extensions->call('relationships_modify_rows', $rows, $node);
Parameters:
  • $rows (array) – Array of entry IDs to rows for this tag.
  • $node (ParseNode) – Parse node for the current relationships tag.
Returns:

Array of entry ids to rows for this tag.

Return type:

Array

New in version 2.7.1.