summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDaniel Wehner2011-03-21 22:21:13 (GMT)
committer Daniel Wehner2011-03-21 22:21:13 (GMT)
commitf62700ae425f989fcfe8b3a1bcc3452a083aab35 (patch)
tree263dc531c8c82f623ee9e6280c3d0fd01755828b
parent55f442c649d04e514ffdfaa400ec9d034c9f47d7 (diff)
#1100738 by bojanz: Extend upgrading docs to include info about argument changes and get_value/sanitize_value.
-rw-r--r--CHANGELOG.txt1
-rw-r--r--help/api-upgrading.html141
2 files changed, 127 insertions, 15 deletions
diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index eebf867..29933c6 100644
--- a/CHANGELOG.txt
+++ b/CHANGELOG.txt
@@ -126,6 +126,7 @@ by dereine: Allow to expose sorts again.
#557160 by joachim: Move docs/docs.php to views.api.php to match the drupal standard of hook documentation.
#1100052 by michielnugter: Fix strict warning of views_handler_argument::get_value.
#1023456 by dereine: Fix many_to_one_helper condition buidling.
+#1100738 by bojanz: Extend upgrading docs to include info about argument changes and get_value/sanitize_value.
Views 3.x-7.x-alpha1 (05-Jan-2011)
==================================
diff --git a/help/api-upgrading.html b/help/api-upgrading.html
index 1a2540d..d8e7598 100644
--- a/help/api-upgrading.html
+++ b/help/api-upgrading.html
@@ -33,22 +33,22 @@ The only thing you have to do is to remove views_process_dependency.
<h3>Changed add_where api</h3>
If your field is a plain sql field:
-<code>
- $this->query->add_where($this->options['group'], "$this->table_alias.$this->real_field " . $this->operator . " '%s'", $this->value);
-</code>
+<pre>
+$this->query->add_where($this->options['group'], "$this->table_alias.$this->real_field " . $this->operator . " '%s'", $this->value);
+</pre>
has to be converted to
-<code>
- $this->query->add_where($this->options['group'], "$this->table_alias.$this->real_field", $this->value, $this->operator);
-</code>
+<pre>
+$this->query->add_where($this->options['group'], "$this->table_alias.$this->real_field", $this->value, $this->operator);
+</pre>
If your field is a complex where condition:
-<code>
- $this->query->add_where($this->options['group'], "$upper($field) NOT LIKE $upper('%%%s')", $this->value);
-</code>
+<pre>
+$this->query->add_where($this->options['group'], "$upper($field) NOT LIKE $upper('%%%s')", $this->value);
+</pre>
has to be converted to
-<code>
- $placeholder = $this->placeholder();
- $this->query->add_where_expression($this->options['group'], "$field LIKE $placeholder", array($placeholder => '%' . db_like($this->value)));
-</code>
+<pre>
+$placeholder = $this->placeholder();
+$this->query->add_where_expression($this->options['group'], "$field LIKE $placeholder", array($placeholder => '%' . db_like($this->value)));
+</pre>
placeholder() generates a automatic unique placeholder for you.
add_where with operator 'formula' can be converted to add_where_expression.
@@ -57,7 +57,7 @@ add_having with operator 'formula' can be converted to add_having_expression.
<h3>Changed place for display specific settings</h3>
In the new ui the new place for display settings is at the top of the second column.
Therefore use something like this code in your display plugin:
-<code>
+<pre>
$categories['block'] = array(
'title' => t('Block settings'),
'column' => 'second',
@@ -65,9 +65,120 @@ $categories['block'] = array(
'#weight' => -10,
),
);
-</code>
+</pre>
<h3>Changed filter settings and associated class variables</h3>
'optional' and 'single' are now 'required' and 'multiple', the logic is now opposite.
Also, the 'no_single' and 'no_optional' class variables (known as "object flags" in the API docs)
are now 'always_multiple' and 'always_required'.
+
+<h3>Changed argument settings</h3>
+See the init() function in views_handler_argument for an overview of everything
+that changed.
+
+1. The default actions 'summary asc', 'summary desc', 'summary asc by count', 'summary asc by count'
+have been replaced by a single 'summary' action (which takes the sort order and type as options).
+2. Wildcards are now called exceptions.
+<pre>
+$this->options['exception']['value'] = $options['wildcard'];
+$this->options['exception']['title'] = $options['wildcard_substitution'];
+</pre>
+3. Summary plugin options are now stored in 'summary_options' instead of 'style_options'
+<pre>
+$this->options['summary_options'] = $options['style_options'];
+</pre>
+4. The selected summary plugin is no longer stored in 'style_plugin'.
+<pre>
+$this->options['summary']['format'] = $options['style_plugin'];
+</pre>
+5. The validator options have been moved.
+<pre>
+$options['validate']['type'] = $options['validate_type'];
+$options['validate']['fail'] = $options['validate_fail'];
+</pre>
+6. The validator settings have been moved from $form['argument_validate'] to ['validate_options']
+This means that dependent code in validate plugins needs to change.
+Example change for views_plugin_argument_validate_user:
+<pre>
+ $form['roles'] = array(
+ '#dependency' => array(
+- 'edit-options-argument-validate-user-restrict-roles' => array(1),
++ 'edit-options-validate-options-user-restrict-roles' => array(1),
+ ),
+</pre>
+
+<h3>The introduction of get_value() and sanitize_value()</h3>
+The views_handler class got two new functions:
+<pre>
+/**
+ * Get the value that's supposed to be rendered.
+ *
+ * @param $values
+ * An object containing all retrieved values.
+ * @param $field
+ * Optional name of the field where the value is stored.
+ */
+function get_value($values, $field = NULL) {
+ $alias = isset($field) ? $this->aliases[$field] : $this->field_alias;
+ if (isset($values->{$alias})) {
+ return $values->{$alias};
+ }
+}
+
+/**
+ * Sanitize the value for output.
+ *
+ * @param $value
+ * The value being rendered.
+ * @param $type
+ * The type of sanitization needed. If not provided, check_plain() is used.
+ */
+function sanitize_value($value, $type = NULL) {
+ switch ($type) {
+ case 'xss':
+ $value = filter_xss($value);
+ break;
+ case 'url':
+ $value = check_url($value);
+ break;
+ default:
+ $value = check_plain($value);
+ break;
+ }
+ return $value;
+}
+</pre>
+These functions are meant to be used in the render() functions of field handlers,
+for fetching data (usually by alias) from the $values object, and for sanitizing values.
+
+The abstraction of fetching data from rendering data is important because
+different query backends have different ways of storing data in $values, and the field alias
+is a SQL specific thing. So instead of overriding the whole render() function and copying
+all of the logic there (as well as having to constantly keep up with upstream Views changes),
+the backend can just override get_values(), which is significantly less code.
+
+Of course, different ways of fetching and displaying data might require different
+ways of sanitizing it, hence the usage of the sanitize_value() function.
+
+Examples of converting render() field handler implementations:
+<pre>
+// This
+$value = $values->{$this->field_alias};
+// Becomes this
+$value = $this->get_value($values);
+
+// And this
+$format = $values->{$this->aliases['format']};
+// Becomes this
+$format = $this->get_values($values, 'format');
+
+// Instead of this:
+return check_plain($value);
+// We write:
+return $this->sanitize_value($value);
+
+// Since sanitize_value() supports different sanitization functions, this:
+return filter_xss($value);
+// Can become:
+return $this->sanitize_value($value, 'xss');
+</pre>