diff options
Diffstat (limited to 'sites/all/modules/views/handlers/views_handler_relationship_groupwise_max.inc')
| -rw-r--r-- | sites/all/modules/views/handlers/views_handler_relationship_groupwise_max.inc | 382 |
1 files changed, 382 insertions, 0 deletions
diff --git a/sites/all/modules/views/handlers/views_handler_relationship_groupwise_max.inc b/sites/all/modules/views/handlers/views_handler_relationship_groupwise_max.inc new file mode 100644 index 000000000..23198c603 --- /dev/null +++ b/sites/all/modules/views/handlers/views_handler_relationship_groupwise_max.inc @@ -0,0 +1,382 @@ +<?php + +/** + * @file + * Relationship for groupwise maximum handler. + */ + +/** + * Relationship handler that allows a groupwise maximum of the linked in table. + * For a definition, see: + * http://dev.mysql.com/doc/refman/5.0/en/example-maximum-column-group-row.html + * In lay terms, instead of joining to get all matching records in the linked + * table, we get only one record, a 'representative record' picked according + * to a given criteria. + * + * Example: + * Suppose we have a term view that gives us the terms: Horse, Cat, Aardvark. + * We wish to show for each term the most recent node of that term. + * What we want is some kind of relationship from term to node. + * But a regular relationship will give us all the nodes for each term, + * giving the view multiple rows per term. What we want is just one + * representative node per term, the node that is the 'best' in some way: + * eg, the most recent, the most commented on, the first in alphabetical order. + * + * This handler gives us that kind of relationship from term to node. + * The method of choosing the 'best' implemented with a sort + * that the user selects in the relationship settings. + * + * So if we want our term view to show the most commented node for each term, + * add the relationship and in its options, pick the 'Comment count' sort. + * + * Relationship definition + * - 'outer field': The outer field to substitute into the correlated subquery. + * This must be the full field name, not the alias. + * Eg: 'term_data.tid'. + * - 'argument table', + * 'argument field': These options define a views argument that the subquery + * must add to itself to filter by the main view. + * Example: the main view shows terms, this handler is being used to get to + * the nodes base table. Your argument must be 'term_node', 'tid', as this + * is the argument that should be added to a node view to filter on terms. + * + * A note on performance: + * This relationship uses a correlated subquery, which is expensive. + * Subsequent versions of this handler could also implement the alternative way + * of doing this, with a join -- though this looks like it could be pretty messy + * to implement. This is also an expensive method, so providing both methods and + * allowing the user to choose which one works fastest for their data might be + * the best way. + * If your use of this relationship handler is likely to result in large + * data sets, you might want to consider storing statistics in a separate table, + * in the same way as node_comment_statistics. + * + * @ingroup views_relationship_handlers + */ +class views_handler_relationship_groupwise_max extends views_handler_relationship { + + /** + * Defines default values for options. + */ + function option_definition() { + $options = parent::option_definition(); + + $options['subquery_sort'] = array('default' => NULL); + // Descending more useful. + $options['subquery_order'] = array('default' => 'DESC'); + $options['subquery_regenerate'] = array('default' => FALSE, 'bool' => TRUE); + $options['subquery_view'] = array('default' => FALSE); + $options['subquery_namespace'] = array('default' => FALSE); + + return $options; + } + + /** + * Extends the relationship's basic options, allowing the user to pick + * a sort and an order for it. + */ + function options_form(&$form, &$form_state) { + parent::options_form($form, $form_state); + + // Get the sorts that apply to our base. + $sorts = views_fetch_fields($this->definition['base'], 'sort'); + foreach ($sorts as $sort_id => $sort) { + $sort_options[$sort_id] = "$sort[group]: $sort[title]"; + } + $base_table_data = views_fetch_data($this->definition['base']); + + $form['subquery_sort'] = array( + '#type' => 'select', + '#title' => t('Representative sort criteria'), + // Provide the base field as sane default sort option. + '#default_value' => !empty($this->options['subquery_sort']) ? $this->options['subquery_sort'] : $this->definition['base'] . '.' . $base_table_data['table']['base']['field'], + '#options' => $sort_options, + '#description' => theme('advanced_help_topic', array('module' => 'views', 'topic' => 'relationship-representative')) . + t("The sort criteria is applied to the data brought in by the relationship to determine how a representative item is obtained for each row. For example, to show the most recent node for each user, pick 'Content: Updated date'."), + ); + + $form['subquery_order'] = array( + '#type' => 'radios', + '#title' => t('Representative sort order'), + '#description' => t("The ordering to use for the sort criteria selected above."), + '#options' => array('ASC' => t('Ascending'), 'DESC' => t('Descending')), + '#default_value' => $this->options['subquery_order'], + ); + + $form['subquery_namespace'] = array( + '#type' => 'textfield', + '#title' => t('Subquery namespace'), + '#description' => t('Advanced. Enter a namespace for the subquery used by this relationship.'), + '#default_value' => $this->options['subquery_namespace'], + ); + + + // WIP: This stuff doens't work yet: namespacing issues. + // A list of suitable views to pick one as the subview. + $views = array('' => '<none>'); + $all_views = views_get_all_views(); + foreach ($all_views as $view) { + // Only get views that are suitable: + // - base must the base that our relationship joins towards + // - must have fields. + if ($view->base_table == $this->definition['base'] && !empty($view->display['default']->display_options['fields'])) { + // TODO: check the field is the correct sort? + // or let users hang themselves at this stage and check later? + if ($view->type == 'Default') { + $views[t('Default Views')][$view->name] = $view->name; + } + else { + $views[t('Existing Views')][$view->name] = $view->name; + } + } + } + + $form['subquery_view'] = array( + '#type' => 'select', + '#title' => t('Representative view'), + '#default_value' => $this->options['subquery_view'], + '#options' => $views, + '#description' => t('Advanced. Use another view to generate the relationship subquery. This allows you to use filtering and more than one sort. If you pick a view here, the sort options above are ignored. Your view must have the ID of its base as its only field, and should have some kind of sorting.'), + ); + + $form['subquery_regenerate'] = array( + '#type' => 'checkbox', + '#title' => t('Generate subquery each time view is run.'), + '#default_value' => $this->options['subquery_regenerate'], + '#description' => t('Will re-generate the subquery for this relationship every time the view is run, instead of only when these options are saved. Use for testing if you are making changes elsewhere. WARNING: seriously impairs performance.'), + ); + } + + /** + * Helper function to create a pseudo view. + * + * We use this to obtain our subquery SQL. + */ + function get_temporary_view() { + views_include('view'); + $view = new view(); + $view->vid = 'new'; // @todo: what's this? + $view->base_table = $this->definition['base']; + $view->add_display('default'); + return $view; + } + + /** + * When the form is submitted, take sure to clear the subquery string cache. + */ + function options_form_submit(&$form, &$form_state) { + $cid = 'views_relationship_groupwise_max:' . $this->view->name . ':' . $this->view->current_display . ':' . $this->options['id']; + cache_clear_all($cid, 'cache_views_data'); + } + + /** + * Generate a subquery given the user options, as set in the options. + * These are passed in rather than picked up from the object because we + * generate the subquery when the options are saved, rather than when the view + * is run. This saves considerable time. + * + * @param $options + * An array of options: + * - subquery_sort: the id of a views sort. + * - subquery_order: either ASC or DESC. + * @return + * The subquery SQL string, ready for use in the main query. + */ + function left_query($options) { + // Either load another view, or create one on the fly. + if ($options['subquery_view']) { + $temp_view = views_get_view($options['subquery_view']); + // Remove all fields from default display + unset($temp_view->display['default']->display_options['fields']); + } + else { + // Create a new view object on the fly, which we use to generate a query + // object and then get the SQL we need for the subquery. + $temp_view = $this->get_temporary_view(); + + // Add the sort from the options to the default display. + // This is broken, in that the sort order field also gets added as a + // select field. See http://drupal.org/node/844910. + // We work around this further down. + $sort = $options['subquery_sort']; + list($sort_table, $sort_field) = explode('.', $sort); + $sort_options = array('order' => $options['subquery_order']); + $temp_view->add_item('default', 'sort', $sort_table, $sort_field, $sort_options); + } + + // Get the namespace string. + $temp_view->namespace = (!empty($options['subquery_namespace'])) ? '_'. $options['subquery_namespace'] : '_INNER'; + $this->subquery_namespace = (!empty($options['subquery_namespace'])) ? '_'. $options['subquery_namespace'] : 'INNER'; + + // The value we add here does nothing, but doing this adds the right tables + // and puts in a WHERE clause with a placeholder we can grab later. + $temp_view->args[] = '**CORRELATED**'; + + // Add the base table ID field. + $views_data = views_fetch_data($this->definition['base']); + $base_field = $views_data['table']['base']['field']; + $temp_view->add_item('default', 'field', $this->definition['base'], $this->definition['field']); + + // Add the correct argument for our relationship's base + // ie the 'how to get back to base' argument. + // The relationship definition tells us which one to use. + $temp_view->add_item( + 'default', + 'argument', + $this->definition['argument table'], // eg 'term_node', + $this->definition['argument field'] // eg 'tid' + ); + + // Build the view. The creates the query object and produces the query + // string but does not run any queries. + $temp_view->build(); + + // Now take the SelectQuery object the View has built and massage it + // somewhat so we can get the SQL query from it. + $subquery = $temp_view->build_info['query']; + + // Workaround until http://drupal.org/node/844910 is fixed: + // Remove all fields from the SELECT except the base id. + $fields =& $subquery->getFields(); + foreach (array_keys($fields) as $field_name) { + // The base id for this subquery is stored in our definition. + if ($field_name != $this->definition['field']) { + unset($fields[$field_name]); + } + } + + // Make every alias in the subquery safe within the outer query by + // appending a namespace to it, '_inner' by default. + $tables =& $subquery->getTables(); + foreach (array_keys($tables) as $table_name) { + $tables[$table_name]['alias'] .= $this->subquery_namespace; + // Namespace the join on every table. + if (isset($tables[$table_name]['condition'])) { + $tables[$table_name]['condition'] = $this->condition_namespace($tables[$table_name]['condition']); + } + } + // Namespace fields. + foreach (array_keys($fields) as $field_name) { + $fields[$field_name]['table'] .= $this->subquery_namespace; + $fields[$field_name]['alias'] .= $this->subquery_namespace; + } + // Namespace conditions. + $where =& $subquery->conditions(); + $this->alter_subquery_condition($subquery, $where); + // Not sure why, but our sort order clause doesn't have a table. + // TODO: the call to add_item() above to add the sort handler is probably + // wrong -- needs attention from someone who understands it. + // In the meantime, this works, but with a leap of faith... + $orders =& $subquery->getOrderBy(); + foreach ($orders as $order_key => $order) { + // But if we're using a whole view, we don't know what we have! + if ($options['subquery_view']) { + list($sort_table, $sort_field) = explode('.', $order_key); + } + $orders[$sort_table . $this->subquery_namespace . '.' . $sort_field] = $order; + unset($orders[$order_key]); + } + + // The query we get doesn't include the LIMIT, so add it here. + $subquery->range(0, 1); + + // Extract the SQL the temporary view built. + $subquery_sql = $subquery->__toString(); + + // Replace the placeholder with the outer, correlated field. + // Eg, change the placeholder ':users_uid' into the outer field 'users.uid'. + // We have to work directly with the SQL, because putting a name of a field + // into a SelectQuery that it does not recognize (because it's outer) just + // makes it treat it as a string. + $outer_placeholder = ':' . str_replace('.', '_', $this->definition['outer field']); + $subquery_sql = str_replace($outer_placeholder, $this->definition['outer field'], $subquery_sql); + + return $subquery_sql; + } + + /** + * Recursive helper to add a namespace to conditions. + * + * Similar to _views_query_tag_alter_condition(). + * + * (Though why is the condition we get in a simple query 3 levels deep???) + */ + function alter_subquery_condition(QueryAlterableInterface $query, &$conditions) { + foreach ($conditions as $condition_id => &$condition) { + // Skip the #conjunction element. + if (is_numeric($condition_id)) { + if (is_string($condition['field'])) { + $condition['field'] = $this->condition_namespace($condition['field']); + } + elseif (is_object($condition['field'])) { + $sub_conditions =& $condition['field']->conditions(); + $this->alter_subquery_condition($query, $sub_conditions); + } + } + } + } + + /** + * Helper function to namespace query pieces. + * + * Turns 'foo.bar' into 'foo_NAMESPACE.bar'. + */ + function condition_namespace($string) { + return str_replace('.', $this->subquery_namespace . '.', $string); + } + + /** + * Called to implement a relationship in a query. + * This is mostly a copy of our parent's query() except for this bit with + * the join class. + */ + function query() { + // Figure out what base table this relationship brings to the party. + $table_data = views_fetch_data($this->definition['base']); + $base_field = empty($this->definition['base field']) ? $table_data['table']['base']['field'] : $this->definition['base field']; + + $this->ensure_my_table(); + + $def = $this->definition; + $def['table'] = $this->definition['base']; + $def['field'] = $base_field; + $def['left_table'] = $this->table_alias; + $def['left_field'] = $this->field; + if (!empty($this->options['required'])) { + $def['type'] = 'INNER'; + } + + if ($this->options['subquery_regenerate']) { + // For testing only, regenerate the subquery each time. + $def['left_query'] = $this->left_query($this->options); + } + else { + // Get the stored subquery SQL string. + $cid = 'views_relationship_groupwise_max:' . $this->view->name . ':' . $this->view->current_display . ':' . $this->options['id']; + $cache = cache_get($cid, 'cache_views_data'); + if (isset($cache->data)) { + $def['left_query'] = $cache->data; + } + else { + $def['left_query'] = $this->left_query($this->options); + cache_set($cid, $def['left_query'], 'cache_views_data'); + } + } + + if (!empty($def['join_handler']) && class_exists($def['join_handler'])) { + $join = new $def['join_handler']; + } + else { + $join = new views_join_subquery(); + } + + $join->definition = $def; + $join->construct(); + $join->adjusted = TRUE; + + // use a short alias for this: + $alias = $def['table'] . '_' . $this->table; + + $this->alias = $this->query->add_relationship($alias, $join, $this->definition['base'], $this->relationship); + } +} |