Skip Navigation

Dev FAQs

What exactly do left and right relationships means when using the entity selector?

When using entity selectors, it can be confusing, especially for new reason programmers, to know which of these methods to use in a given situation:

  • add_left_relationship
  • add_left_relationship_field
  • add_right_relationship
  • add_right_relationship_field

Why the Confusion???

The confusion typically revolves around whether to use the "left" or "right" versions of these methods. The words "left" or "right" in entity selector methods refer to which side of the relationship the type of entity being selected exists. Following these two rules should set you straight:

  1. If the type you are selecting with your entity selector is on the right side of the relationship that you are referencing in the function, use the right hand version of the function.
  2. If the type you are selecting with your entity selector is on the left side of the relationship that your are referencing in the function, use the left hand version of the function.

A Couple Examples

Example 1:

I am writing an entity selector which selects images attached to a page. The relationship I'm selecting the images across is the minisite_page_to_image relationship. From the naming convention used for relationship names, I know that the minisite_page_to_image relationship has minisite_pages on the left, and images on the right. I use the method add_right_relationship. The entity selector would look like this:

$es = new entity_selector($site_id);
$es->add_type(id_of('image'));
$es->add_right_relationship($page_id, relationship_id_of('minisite_page_to_image'));
$result = $es->run_one();

Example 2:

I am writing an entity selector to grab all the pages in a site that have images, along with the image ids. So - I want to select page entities, augmented with the image ids. The relationship I'm selecting across is minisite_page_to_image. In this relationship, pages are on the left side, images on the right. I'm going to use the method add_left_relationship_field since the type the entity selector is grabbing is on the left side of the relationship. The entity selector would look like this:

$es = new entity_selector($site_id);
$es->add_type(id_of('minisite_page'));
$es->enable_multivalue_results();
$es->add_left_relationship_field('minisite_page_to_image', 'entity', 'id', 'image_id');
$result = $es->run_one();

Something To Ponder

Interestingly, the entity selector could (and probably should) be reworked to have singular methods for adding a relationship or relationship_field. In the above example, I know I am selecting pages. I also know the relationship I am selecting over. It can be determined programatically that add_left_relationship_field is needed in this case, since pages are on the left side of the relationship. The only situation where the selection is ambiguous is when the relationship is between two items of the same type. Makes the brain hum.

  • Nathan White, 19 June 2008
  • Keywords: entity selector, reason, relationships

Other FAQs