API page: http://api.drupal.org/api/drupal/includes%21entity.inc/function/EntityFi...

I'm having trouble working out how to use EntityFieldQuery's "tableSort" functionality. The docs refer to an "EFQ Header array" - even with the example provided in the comments (drawn from entity_query.test) it's not apparent how to build one of these, how it differs from a normal TableSort header, what the specifier/type keys are, or what to do to get the whole thing to work with theme_table.

I've had some success with simple properties, by simply including both (EFQ) specifier/type and (theme_table) field, like so:

  $header = array(
    'sku' => array(
      'data' => t('Product code'),
      'type' => 'property',
      'specifier' => 'sku',
      'field' => 'sku',
    ),
  );

... But this does not help me sort by field values or - heaven forfend - field values on referenced entities.

CommentFileSizeAuthor
#2 entity_tablesort_doc_fix-1924622-2.patch841 bytesbabruix
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

Category: feature » bug
Issue tags: +Novice

Yeah, that definitely needs better documentation -- thanks for filing this issue!

It looks like in Drupal 8 the equivalent function is documented on this interface:
http://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!Query!Query...
and the implementing method has essentially the same code as the d7 method:
http://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!Query!Query...

It says:
$headers: An array of headers of the same struucture as described in theme_table(). Use a 'specifier' in place of a 'field' to specify what to sort on. This can be an entity or a field as described in condition().

Looking at the functions called here to figure out how to sort, it does look like the documentation should be:

An array of headers of the same structure as described in theme_table().

Seems like a good Novice project to fix that documentation for D7.

babruix’s picture

Status: Active » Needs review
FileSize
841 bytes

Changed "An EFQ Header array based on which the order clause" to simple "An array of headers of the same structure as described in theme_table()." as suggested by jhodgdon.
Please, review.

jhodgdon’s picture

Assigned: Unassigned » jhodgdon
Status: Needs review » Reviewed & tested by the community

Thanks, looks good! I'll get this committed when it turns green (just in case).

kingandy’s picture

Status: Reviewed & tested by the community » Needs work

A theme_table header array is the one thing this is not. theme_table requires the 'field' element, whereas EFQ takes a 'type' and this arcane, unspecified 'specifier' entry which according to this example may be a string or an array of 'field' and 'column'. That's the part that needs documenting.

jhodgdon’s picture

Version: 7.x-dev » 8.x-dev
Status: Needs work » Active

In that case we need to fix the Drupal 8 documentation first.

kingandy’s picture

The Drupal 8 documentation does at least say to "Use a 'specifier' in place of a 'field' to specify what to sort on. This can be an entity or a field as described in condition()." I'm not sure why that was left out of the D7 patch.

It still needs some work, as I don't know what condition() is being referred to.

babruix’s picture

In D8 it has misspelling in tableSort @param $headers: "An array of headers of the same struucture".
For me is not clear, should I change D7 patch or how if we going to change D8 first, what exactly should be checked and changed?

jhodgdon’s picture

Assigned: jhodgdon » Unassigned
Issue tags: -Novice

We always fix problems in Drupal 8 before backporting them to Drupal 7. At this point, I'm pretty confused about what the Drupal 8 docs should say, so I am not sure how to fix them. I'm hoping that kingandy or someone else who understands what the inputs should be can fix the D8 docs so that they are clear.

kingandy’s picture

This is kind of the problem, I know it needs documenting because I was trying to find out how it works and I couldn't find any docs on it :D

As far as I can see, the D8 docs seem to be basically correct but we need to clarify what "an entity or a field as described in condition()" is referencing. My first thought was QueryInterface::condition(), but I can't see anything in there that maps to the 'specifier' element.

kristiaanvandeneynde’s picture

So far I've figured out that if you want to:

Sort on an entity's property, you use:

  $header = array(
    'title' => array(
      'data' => t('Entity title'),
      'type' => 'property',
      'specifier' => 'title',
    ),
  );

Sort on metadata of an entity (i.e. bundle, ...), you use:

  $header = array(
    'title' => array(
      'data' => t('Entity bundle'),
      'type' => 'entity',
      'specifier' => 'bundle',
    ),
  );

Sort on an entity's field, you use:

  $header = array(
    'title' => array(
      'data' => t('Entity field'),
      'type' => 'field',
      'specifier' => array('field' => 'field_name', 'column' => 'value'),
    ),
  );
kristiaanvandeneynde’s picture

Just noticed that all three 'known' types have an OrderBy counterpart method:

  • entityOrderBy
  • propertyOrderBy
  • fieldOrderBy

So it seems to me that those are the three only possible options.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.6 was released on August 1, 2018 and is the final bugfix release for the Drupal 8.5.x series. Drupal 8.5.x will not receive any further development aside from security fixes. Sites should prepare to update to 8.6.0 on September 5, 2018. (Drupal 8.6.0-rc1 is available for testing.)

Bug reports should be targeted against the 8.6.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.8.x-dev

Drupal 8.6.x will not receive any further development aside from security fixes. Bug reports should be targeted against the 8.8.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.9.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.7 was released on June 3, 2020 and is the final full bugfix release for the Drupal 8.8.x series. Drupal 8.8.x will not receive any further development aside from security fixes. Sites should prepare to update to Drupal 8.9.0 or Drupal 9.0.0 for ongoing support.

Bug reports should be targeted against the 8.9.x-dev branch from now on, and new development or disruptive changes should be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

catch’s picture

Title: Document EntityFieldQuery::tableSort usage » Document Drupa\Core\Entity\Query\QueryInterface::tableSort() usage
Version: 8.9.x-dev » 9.3.x-dev
Issue summary: View changes
Issue tags: +Needs issue summary update, +Bug Smash Initiative

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.