Query extender for pager queries.

This is the "default" pager mechanism. It creates a paged query with a fixed number of entries per page.

Hierarchy

Expanded class hierarchy of PagerDefault

11 string references to 'PagerDefault'
blog_page_last in modules/blog/blog.pages.inc
Menu callback; displays a Drupal page containing recent blog entries of all users.
blog_page_user in modules/blog/blog.pages.inc
Menu callback; displays a Drupal page containing recent blog entries of a given user.
comment_get_thread in modules/comment/comment.module
Retrieve comments for a thread.
DatabaseSelectPagerDefaultTestCase::testHavingPagerQuery in modules/simpletest/tests/database_test.test
Confirm that a paging query with a having expression returns valid results.
DatabaseSelectPagerDefaultTestCase::testInnerPagerQuery in modules/simpletest/tests/database_test.test
Confirm that a pager query with inner pager query returns valid results.

... See full list

File

includes/pager.inc, line 15
Functions to aid in presenting database results as a set of pages.

View source
class PagerDefault extends SelectQueryExtender {

  /**
   * The highest element we've autogenerated so far.
   *
   * @var int
   */
  static $maxElement = 0;

  /**
   * The number of elements per page to allow.
   *
   * @var int
   */
  protected $limit = 10;

  /**
   * The unique ID of this pager on this page.
   *
   * @var int
   */
  protected $element = NULL;

  /**
   * The count query that will be used for this pager.
   *
   * @var SelectQueryInterface
   */
  protected $customCountQuery = FALSE;
  public function __construct(SelectQueryInterface $query, DatabaseConnection $connection) {
    parent::__construct($query, $connection);

    // Add pager tag. Do this here to ensure that it is always added before
    // preExecute() is called.
    $this
      ->addTag('pager');
  }

  /**
   * Override the execute method.
   *
   * Before we run the query, we need to add pager-based range() instructions
   * to it.
   */
  public function execute() {

    // Add convenience tag to mark that this is an extended query. We have to
    // do this in the constructor to ensure that it is set before preExecute()
    // gets called.
    if (!$this
      ->preExecute($this)) {
      return NULL;
    }

    // A NULL limit is the "kill switch" for pager queries.
    if (empty($this->limit)) {
      return;
    }
    $this
      ->ensureElement();
    $total_items = $this
      ->getCountQuery()
      ->execute()
      ->fetchField();
    $current_page = pager_default_initialize($total_items, $this->limit, $this->element);
    $this
      ->range($current_page * $this->limit, $this->limit);

    // Now that we've added our pager-based range instructions, run the query normally.
    return $this->query
      ->execute();
  }

  /**
   * Ensure that there is an element associated with this query.
   * If an element was not specified previously, then the value of the
   * $maxElement counter is taken, after which the counter is incremented.
   *
   * After running this method, access $this->element to get the element for this
   * query.
   */
  protected function ensureElement() {
    if (!isset($this->element)) {
      $this->element = self::$maxElement++;
    }
  }

  /**
   * Specify the count query object to use for this pager.
   *
   * You will rarely need to specify a count query directly.  If not specified,
   * one is generated off of the pager query itself.
   *
   * @param SelectQueryInterface $query
   *   The count query object.  It must return a single row with a single column,
   *   which is the total number of records.
   */
  public function setCountQuery(SelectQueryInterface $query) {
    $this->customCountQuery = $query;
  }

  /**
   * Retrieve the count query for this pager.
   *
   * The count query may be specified manually or, by default, taken from the
   * query we are extending.
   *
   * @return SelectQueryInterface
   *   A count query object.
   */
  public function getCountQuery() {
    if ($this->customCountQuery) {
      return $this->customCountQuery;
    }
    else {
      return $this->query
        ->countQuery();
    }
  }

  /**
   * Specify the maximum number of elements per page for this query.
   *
   * The default if not specified is 10 items per page.
   *
   * @param $limit
   *   An integer specifying the number of elements per page.  If passed a false
   *   value (FALSE, 0, NULL), the pager is disabled.
   */
  public function limit($limit = 10) {
    $this->limit = $limit;
    return $this;
  }

  /**
   * Specify the element ID for this pager query.
   *
   * The element is used to differentiate different pager queries on the same
   * page so that they may be operated independently.  If you do not specify an
   * element, every pager query on the page will get a unique element.  If for
   * whatever reason you want to explicitly define an element for a given query,
   * you may do so here.
   *
   * Setting the element here also increments the static $maxElement counter,
   * which is used for determining the $element when there's none specified.
   *
   * Note that no collision detection is done when setting an element ID
   * explicitly, so it is possible for two pagers to end up using the same ID
   * if both are set explicitly.
   *
   * @param $element
   */
  public function element($element) {
    $this->element = $element;
    if ($element >= self::$maxElement) {
      self::$maxElement = $element + 1;
    }
    return $this;
  }

}

Members

Contains filters are case sensitive
Namesort descending Modifiers Type Description Overrides
PagerDefault::$customCountQuery protected property The count query that will be used for this pager.
PagerDefault::$element protected property The unique ID of this pager on this page.
PagerDefault::$limit protected property The number of elements per page to allow.
PagerDefault::$maxElement static property The highest element we've autogenerated so far.
PagerDefault::element public function Specify the element ID for this pager query.
PagerDefault::ensureElement protected function Ensure that there is an element associated with this query. If an element was not specified previously, then the value of the $maxElement counter is taken, after which the counter is incremented.
PagerDefault::execute public function Override the execute method. Overrides SelectQueryExtender::execute
PagerDefault::getCountQuery public function Retrieve the count query for this pager.
PagerDefault::limit public function Specify the maximum number of elements per page for this query.
PagerDefault::setCountQuery public function Specify the count query object to use for this pager.
PagerDefault::__construct public function Overrides SelectQueryExtender::__construct
SelectQueryExtender::$connection protected property The connection object on which to run this query.
SelectQueryExtender::$placeholder protected property The placeholder counter.
SelectQueryExtender::$query protected property The SelectQuery object we are extending/decorating.
SelectQueryExtender::$uniqueIdentifier protected property A unique identifier for this query object.
SelectQueryExtender::addExpression public function Adds an expression to the list of "fields" to be SELECTed. Overrides SelectQueryInterface::addExpression
SelectQueryExtender::addField public function Adds a field to the list to be SELECTed. Overrides SelectQueryInterface::addField
SelectQueryExtender::addJoin public function Join against another table in the database. Overrides SelectQueryInterface::addJoin
SelectQueryExtender::addMetaData public function Adds additional metadata to the query. Overrides QueryAlterableInterface::addMetaData
SelectQueryExtender::addTag public function Adds a tag to a query. Overrides QueryAlterableInterface::addTag
SelectQueryExtender::arguments public function Gets a complete list of all values to insert into the prepared statement. Overrides QueryConditionInterface::arguments
SelectQueryExtender::compile public function Compiles the saved conditions for later retrieval. Overrides QueryConditionInterface::compile
SelectQueryExtender::compiled public function Check whether a condition has been previously compiled. Overrides QueryConditionInterface::compiled
SelectQueryExtender::condition public function Helper function: builds the most common conditional clauses. Overrides QueryConditionInterface::condition
SelectQueryExtender::conditions public function Gets a complete list of all conditions in this conditional clause. Overrides QueryConditionInterface::conditions
SelectQueryExtender::countQuery public function Get the equivalent COUNT query of this query as a new query object. Overrides SelectQueryInterface::countQuery
SelectQueryExtender::distinct public function Sets this query to be DISTINCT. Overrides SelectQueryInterface::distinct
SelectQueryExtender::exists public function Sets a condition that the specified subquery returns values. Overrides QueryConditionInterface::exists
SelectQueryExtender::extend public function Enhance this object by wrapping it in an extender object. Overrides QueryExtendableInterface::extend
SelectQueryExtender::fields public function Add multiple fields from the same table to be SELECTed. Overrides SelectQueryInterface::fields
SelectQueryExtender::forUpdate public function Add FOR UPDATE to the query. Overrides SelectQueryInterface::forUpdate
SelectQueryExtender::getArguments public function Compiles and returns an associative array of the arguments for this prepared statement. Overrides SelectQueryInterface::getArguments
SelectQueryExtender::getExpressions public function Returns a reference to the expressions array for this query. Overrides SelectQueryInterface::getExpressions
SelectQueryExtender::getFields public function Returns a reference to the fields array for this query. Overrides SelectQueryInterface::getFields
SelectQueryExtender::getGroupBy public function Returns a reference to the group-by array for this query. Overrides SelectQueryInterface::getGroupBy
SelectQueryExtender::getMetaData public function Retrieves a given piece of metadata. Overrides QueryAlterableInterface::getMetaData
SelectQueryExtender::getOrderBy public function Returns a reference to the order by array for this query. Overrides SelectQueryInterface::getOrderBy
SelectQueryExtender::getTables public function Returns a reference to the tables array for this query. Overrides SelectQueryInterface::getTables
SelectQueryExtender::getUnion public function Returns a reference to the union queries for this query. This include queries for UNION, UNION ALL, and UNION DISTINCT. Overrides SelectQueryInterface::getUnion
SelectQueryExtender::groupBy public function Groups the result set by the specified field. Overrides SelectQueryInterface::groupBy
SelectQueryExtender::hasAllTags public function Determines if a given query has all specified tags. Overrides QueryAlterableInterface::hasAllTags
SelectQueryExtender::hasAnyTag public function Determines if a given query has any specified tag. Overrides QueryAlterableInterface::hasAnyTag
SelectQueryExtender::hasTag public function Determines if a given query has a given tag. Overrides QueryAlterableInterface::hasTag
SelectQueryExtender::having public function
SelectQueryExtender::havingArguments public function
SelectQueryExtender::havingCompile public function
SelectQueryExtender::havingCondition public function Helper function to build most common HAVING conditional clauses. Overrides SelectQueryInterface::havingCondition
SelectQueryExtender::havingConditions public function
SelectQueryExtender::innerJoin public function Inner Join against another table in the database. Overrides SelectQueryInterface::innerJoin
SelectQueryExtender::isNotNull function Sets a condition that the specified field be NOT NULL. Overrides QueryConditionInterface::isNotNull
SelectQueryExtender::isNull function Sets a condition that the specified field be NULL. Overrides QueryConditionInterface::isNull
SelectQueryExtender::isPrepared public function Indicates if preExecute() has already been called on that object. Overrides SelectQueryInterface::isPrepared
SelectQueryExtender::join public function Default Join against another table in the database. Overrides SelectQueryInterface::join
SelectQueryExtender::leftJoin public function Left Outer Join against another table in the database. Overrides SelectQueryInterface::leftJoin
SelectQueryExtender::nextPlaceholder public function Implements QueryPlaceholderInterface::nextPlaceholder(). Overrides QueryPlaceholderInterface::nextPlaceholder
SelectQueryExtender::notExists public function Sets a condition that the specified subquery returns no values. Overrides QueryConditionInterface::notExists
SelectQueryExtender::orderBy public function Orders the result set by a given field. Overrides SelectQueryInterface::orderBy
SelectQueryExtender::orderRandom public function Orders the result set by a random value. Overrides SelectQueryInterface::orderRandom
SelectQueryExtender::preExecute public function Generic preparation and validation for a SELECT query. Overrides SelectQueryInterface::preExecute
SelectQueryExtender::range public function Restricts a query to a given range in the result set. Overrides SelectQueryInterface::range
SelectQueryExtender::rightJoin public function Right Outer Join against another table in the database. Overrides SelectQueryInterface::rightJoin
SelectQueryExtender::union public function Add another Select query to UNION to this one. Overrides SelectQueryInterface::union
SelectQueryExtender::uniqueIdentifier public function Implements QueryPlaceholderInterface::uniqueIdentifier(). Overrides QueryPlaceholderInterface::uniqueIdentifier
SelectQueryExtender::where public function Adds an arbitrary WHERE clause to the query. Overrides QueryConditionInterface::where
SelectQueryExtender::__call public function Magic override for undefined methods.
SelectQueryExtender::__clone public function Clone magic method. Overrides SelectQueryInterface::__clone
SelectQueryExtender::__toString public function

Comments

yurtboy’s picture

In using PagerDefault in my queries, what is the best way to also pass the total overall found?
For example the blog module blog.pages.inc line 59

  $query = db_select('node', 'n')->extend('PagerDefault');
  $nids = $query
    ->fields('n', array('nid', 'sticky', 'created'))
    ->condition('type', 'blog')
    ->condition('status', 1)
    ->orderBy('sticky', 'DESC')
    ->orderBy('created', 'DESC')
    ->limit(variable_get('default_nodes_main', 10))
    ->addTag('node_access')
    ->execute()
    ->fetchCol();

  if (!empty($nids)) {
    $nodes = node_load_multiple($nids);
    $build += node_view_multiple($nodes);
    $build['pager'] = array(
      '#theme' => 'pager',
      '#weight' => 5,
    );
  }

Is it possible to passback to the pager theme a Total found overall? Seems like the math is there ie Pages found etc.
Thanks

xgrommx’s picture

This code example is not corect work in Drupal 8.

Need use extend('Drupal\Core\Database\Query\PagerSelectExtender') instead of extend('PagerDefault').

For other examples see http://drupal.org/node/1621062

kingandy’s picture

Luckily, these are the Drupal 7 docs.

phponwebsites’s picture

I have made one dynamic query to get values from database.
I want to set offset for pager.
Below is my code

$companies_query = db_select('node', 'n');
$companies_query->leftJoin('field_data_field_company_industry', 'company_industry', 'company_industry.entity_id = n.nid');
$companies_query->leftJoin('field_data_field_company_logo', 'company_logo', 'company_logo.entity_id = n.nid');
$companies_query->Join('field_data_field_review_company_name', 'company_review', 'company_review.field_review_company_name_nid = n.nid');
$companies_query->Join('node', 'field_review_company_name_node', 'company_review.entity_id = field_review_company_name_node.nid');
$companies_query->addExpression("COUNT(n.nid)", 'review_count');

$companies_query1 = $companies_query
->fields('n', array('nid', 'title'))
->fields('company_logo', array('field_company_logo_fid'))
->condition('n.type', 'company', '=')
->condition('field_review_company_name_node.status', 1, '=')
->condition('company_industry.field_company_industry_tid', $tid, '=')
->groupBy('nid')
->orderBy('review_count', 'DESC')
->extend('TableSort')->extend('PagerDefault')->limit(20);

I want to get all values except first one. So i need to set offset here.
How can i set offset?
If i will try to use range(), then i can't get result as i want.