Merge branch 'trunk'

.gitignore

@@ -63,3 +63,6 @@ ocular.phar
 
 # PHPunit config
 phpunit.xml
+
+# General
+NOTES.md

CHANGELOG.md

@@ -3,7 +3,36 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased][unreleased]
 
-*
+* 
+
+## 2.0.6 - 2015-04-30
+
+### Enhancements
+
+* New metabox/form parameter, `show_on_cb`, allows you to conditionally display a cmb metabox/form via a callback. The `$cmb` object gets passed as a parameter to the callback. This complements the `'show_on_cb'` parameter that already exists for individual fields. Using this callback is similar to using the `'cmb2_show_on'` filter, but only applies to that specific metabox and it is recommended to use this callback instead as it minimizes th risk that your filter will affect other metaboxes.
+* Taxonomy types no longer save a value. The value getting saved was causing confusion and is not meant to be used. To use the saved taxonomy data, you need to use the WordPress term api, `get_the_terms `, `get_the_term_list`, etc.
+* Add `'multiple'` field parameter to store values in individual rows instead of serialized array. Will only work if field is not repeatable or a repeatable group. Props [JohnyGoerend](https://github.com/JohnyGoerend). ([#262](https://github.com/WebDevStudios/CMB2/pull/262), [#206](https://github.com/WebDevStudios/CMB2/issues/206), [#45](https://github.com/WebDevStudios/CMB2/issues/45)).
+* Portuguese (Brazil) translation provided by [@lucascdsilva](https://github.com/lucascdsilva) - [#293](https://github.com/WebDevStudios/CMB2/pull/293).
+* Spanish (Spain) translation updated by [@yivi](https://github.com/yivi) - [#272](https://github.com/WebDevStudios/CMB2/pull/272).
+* Added group field callback parameters, `'before_group'`, `'before_group_row'`, `'after_group_row'`, `'after_group'` to complement the `'before_row'`, `'before'`, `'after'`, `'after_row'` field parameters.
+* Better styling for `title` fields and `title` descriptions on options pages.
+* Add a `sanitization_cb` field parameter check for the `group` field type.
+* Better function/file doc-blocks to provide better documentation for automated documentation tools. See: [cmb2.io/api](http://cmb2.io/api/).
+* `cmb2_print_metabox_form`, `cmb2_metabox_form`, and `cmb2_get_metabox_form` helper functions now accept two new parameters:
+	* an `'object_type'` parameter to explictly set that in the `$cmb` object.
+	* an `'enqueue_js'` parameter to explicitly disable the CMB JS enqueue. This is handy if you're not planning on using any of the fields which require JS (like color/date pickers, wysiwyg, file, etc).
+
+### Bug Fixes
+
+* Fix issue with oembed fields in repeatable groups where changing video changed it for all fields in a group.
+* Fix empty arrays (like in the group field) saving as a value.
+* Move `'cmb2_override_meta_value'` and `"cmb2_override_{$field_id}_meta_value"` filters to the `CMB2_Field::get_data()` method so that the filters are applied every time the data is requested. **THIS IS A BREAKING CHANGE:** The parameters for those filters have changed a bit. Previously, the filters accepted 5 arguments, `$value`, `$object_id`, `$field_args`, `$object_type`, `$field`. They have changed to accept 4 arguments instead, `$value`, `$object_id`, `$args`, `$field`, where `$args` is an array that contains the following:
+	* @type string $type     The current object type
+	* @type int    $id       The current object ID
+	* @type string $field_id The ID of the field being requested
+	* @type bool   $repeat   Whether current field is repeatable
+	* @type bool   $single   Whether current field is a single database row
+
 
 ## 2.0.5 - 2015-03-17
 

bootstrap.php

@@ -1,4 +1,13 @@
 <?php
+/**
+ * Bootstraps the CMB2 process
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
+ */
 
 /**
  * Fires when CMB2 is included/loaded

css/cmb2.css

@@ -742,7 +742,7 @@ Misc.
 	margin: 0;
 }
 
-/* line 13, sass/partials/_misc.scss */
+/* line 12, sass/partials/_misc.scss */
 
 .edit-tags-php .cmb2-metabox-title,
 .profile-php .cmb2-metabox-title,
@@ -752,6 +752,20 @@ Misc.
 
 /* line 18, sass/partials/_misc.scss */
 
+.cmb2-options-page .cmb2-metabox-title {
+	font-size: 1.3em;
+	margin: 1em 0;
+}
+
+/* line 21, sass/partials/_misc.scss */
+
+.cmb2-options-page .cmb2-metabox-title + p.cmb2-metabox-description {
+	margin-top: -1.6em;
+	margin-bottom: .8em;
+}
+
+/* line 27, sass/partials/_misc.scss */
+
 .postbox .cmb-spinner {
 	float: left;
 }

css/sass/cmb2.scss

@@ -1,5 +1,5 @@
 /**
- * CMB Styling
+ * CMB2 Styling
  */
 
 @import "partials/variables";

css/sass/partials/_misc.scss

@@ -9,12 +9,21 @@ Misc.
 .edit-tags-php,
 .profile-php,
 .user-edit-php {
-
 	.cmb2-metabox-title {
 		font-size: 1.4em;
 	}
 }
 
+.cmb2-options-page {
+	.cmb2-metabox-title {
+		font-size: 1.3em;
+		margin: 1em 0;
+		+ p.cmb2-metabox-description {
+			margin-top: -1.6em;
+			margin-bottom: .8em;
+		}
+	}
+}
 .postbox .cmb-spinner {
 	float: left;
 }

example-functions.php

@@ -1,12 +1,12 @@
 <?php
 /**
- * Include and setup custom metaboxes and fields. (make sure you copy this file to outside the CMB directory)
+ * Include and setup custom metaboxes and fields. (make sure you copy this file to outside the CMB2 directory)
  *
  * Be sure to replace all instances of 'yourprefix_' with your project's prefix.
  * http://nacin.com/2010/05/11/in-wordpress-prefix-everything/
  *
  * @category YourThemeOrPlugin
- * @package  Metaboxes
+ * @package  Demo_CMB2
  * @license  http://www.opensource.org/licenses/gpl-license.php GPL v2.0 (or later)
  * @link     https://github.com/WebDevStudios/CMB2
  */
@@ -21,6 +21,21 @@
 	require_once dirname( __FILE__ ) . '/CMB2/init.php';
 }
 
+/**
+ * Conditionally displays a metabox when used as a callback in the 'show_on_cb' cmb2_box parameter
+ *
+ * @param  CMB2 object $cmb CMB2 object
+ *
+ * @return bool             True if metabox should show
+ */
+function yourprefix_show_if_front_page( $cmb ) {
+	// Don't show this metabox if it's the front page template
+	if ( $cmb->object_id !== get_option( 'page_on_front' ) ) {
+		return false;
+	}
+	return true;
+}
+
 /**
  * Conditionally displays a field when used as a callback in the 'show_on_cb' field parameter
  *
@@ -66,6 +81,7 @@ function yourprefix_register_demo_metabox() {
 		'id'            => $prefix . 'metabox',
 		'title'         => __( 'Test Metabox', 'cmb2' ),
 		'object_types'  => array( 'page', ), // Post type
+		'show_on_cb'    => 'yourprefix_show_if_front_page', // function should return a bool value
 		'context'       => 'normal',
 		'priority'      => 'high',
 		'show_names'    => true, // Show field names on the left
@@ -285,6 +301,7 @@ function yourprefix_register_demo_metabox() {
 		'desc'    => __( 'field description (optional)', 'cmb2' ),
 		'id'      => $prefix . 'multicheckbox',
 		'type'    => 'multicheck',
+		// 'multiple' => true, // Store values in individual rows
 		'options' => array(
 			'check1' => __( 'Check One', 'cmb2' ),
 			'check2' => __( 'Check Two', 'cmb2' ),
@@ -448,7 +465,7 @@ function yourprefix_register_user_profile_metabox() {
 	$cmb_user = new_cmb2_box( array(
 		'id'               => $prefix . 'edit',
 		'title'            => __( 'User Profile Metabox', 'cmb2' ),
-		'object_types'     => array( 'user' ), // Tells CMB to use user_meta vs post_meta
+		'object_types'     => array( 'user' ), // Tells CMB2 to use user_meta vs post_meta
 		'show_names'       => true,
 		'new_user_section' => 'add-new-user', // where form will show on new user page. 'add-existing-user' is only other valid option.
 	) );

includes/CMB2.php

@@ -1,6 +1,12 @@
 <?php
 /**
- * Create meta boxes
+ * CMB2 - The core metabox object
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
  *
  * @property-read string $cmb_id
  * @property-read array $meta_box
@@ -20,11 +26,11 @@ class CMB2 {
 	 * @var   array
 	 * @since 0.9.0
 	 */
-	protected $meta_box;
+	protected $meta_box = array();
 
 	/**
 	 * Object ID for metabox meta retrieving/saving
-	 * @var   int
+	 * @var   mixed
 	 * @since 1.0.0
 	 */
 	protected $object_id = 0;
@@ -63,7 +69,8 @@ class CMB2 {
 		'context'      => 'normal',
 		'priority'     => 'high',
 		'show_names'   => true, // Show field names on the left
-		'show_on'      => array(), // Specific post IDs or page templates to display this metabox
+		'show_on_cb'   => null, // Callback to determine if metabox should display.
+		'show_on'      => array(), // Post IDs or page templates to display this metabox. overrides 'show_on_cb'
 		'cmb_styles'   => true, // Include cmb bundled stylesheet
 		'fields'       => array(),
 		'hookup'       => true,
@@ -141,7 +148,7 @@ public function show_form( $object_id = 0, $object_type = '' ) {
 
 		$this->nonce_field();
 
-		echo "\n<!-- Begin CMB Fields -->\n";
+		echo "\n<!-- Begin CMB2 Fields -->\n";
 
 		/**
 		 * Hook before form table begins
@@ -231,7 +238,7 @@ public function show_form( $object_id = 0, $object_type = '' ) {
 		 */
 		do_action( "cmb2_after_{$object_type}_form_{$this->cmb_id}", $object_id, $this );
 
-		echo "\n<!-- End CMB Fields -->\n";
+		echo "\n<!-- End CMB2 Fields -->\n";
 
 	}
 
@@ -250,14 +257,16 @@ public function render_group( $args ) {
 			return;
 		}
 
-		$args['count']   = 0;
 		$field_group     = $this->get_field( $args );
 		$desc            = $field_group->args( 'description' );
 		$label           = $field_group->args( 'name' );
 		$sortable        = $field_group->options( 'sortable' ) ? ' sortable' : '';
 		$group_val       = (array) $field_group->value();
 		$nrows           = count( $group_val );
 		$remove_disabled = $nrows <= 1 ? 'disabled="disabled" ' : '';
+		$field_group->index = 0;
+
+		$field_group->peform_param_callback( 'before_group' );
 
 		echo '<div class="cmb-row cmb-repeat-group-wrap"><div class="cmb-td"><div id="', $field_group->id(), '_repeat" class="cmb-nested cmb-field-list cmb-repeatable-group', $sortable, '" style="width:100%;">';
 		if ( $desc || $label ) {
@@ -274,8 +283,9 @@ public function render_group( $args ) {
 
 		if ( ! empty( $group_val ) ) {
 
-			foreach ( $group_val as $field_group->index => $field_id ) {
+			foreach ( $group_val as $group_key => $field_id ) {
 				$this->render_group_row( $field_group, $remove_disabled );
+				$field_group->index++;
 			}
 		} else {
 			$this->render_group_row( $field_group, $remove_disabled );
@@ -285,6 +295,8 @@ public function render_group( $args ) {
 
 		echo '</div></div></div>';
 
+		$field_group->peform_param_callback( 'after_group' );
+
 	}
 
 	/**
@@ -295,8 +307,10 @@ public function render_group( $args ) {
 	 */
 	public function render_group_row( $field_group, $remove_disabled ) {
 
+		$field_group->peform_param_callback( 'before_group_row' );
+
 		echo '
-		<div class="postbox cmb-row cmb-repeatable-grouping" data-iterator="', $field_group->count(), '">
+		<div class="postbox cmb-row cmb-repeatable-grouping" data-iterator="', $field_group->index, '">
 
 			<button ', $remove_disabled, 'data-selector="', $field_group->id(), '_repeat" class="dashicons-before dashicons-no-alt cmb-remove-group-row"></button>
 			<div class="cmbhandle" title="' , __( 'Click to toggle', 'cmb2' ), '"><br></div>
@@ -332,7 +346,7 @@ public function render_group_row( $field_group, $remove_disabled ) {
 		</div>
 		';
 
-		$field_group->args['count']++;
+		$field_group->peform_param_callback( 'after_group_row' );
 	}
 
 	/**
@@ -489,7 +503,8 @@ public function save_group( $args ) {
 		) );
 		$base_id            = $field_group->id();
 		$old                = $field_group->get_data();
-		$group_vals         = $this->data_to_save[ $base_id ];
+		// Check if group field has sanitization_cb
+		$group_vals         = $field_group->sanitization_cb( $this->data_to_save[ $base_id ] );
 		$saved              = array();
 		$field_group->index = 0;
 
@@ -937,6 +952,8 @@ public function __get( $field ) {
 			case 'meta_box':
 			case 'updated':
 				return $this->{$field};
+			case 'object_id':
+				return $this->object_id();
 			default:
 				throw new Exception( 'Invalid ' . __CLASS__ . ' property: ' . $field );
 		}

includes/CMB2_Ajax.php

@@ -1,22 +1,25 @@
 <?php
 
 /**
- * CMB ajax methods
+ * CMB2 ajax methods
  * (i.e. a lot of work to get oEmbeds to work with non-post objects)
  *
  * @since  0.9.5
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
  */
 class CMB2_Ajax {
 
-
 	// Whether to hijack the oembed cache system
 	protected $hijack      = false;
 	protected $object_id   = 0;
 	protected $embed_args  = array();
 	protected $object_type = 'post';
 	protected $ajax_update = false;
 
-
 	/**
 	 * Handles our oEmbed ajax request
 	 * @since  0.9.5
@@ -60,7 +63,6 @@ public function oembed_handler() {
 		wp_send_json_success( $html );
 	}
 
-
 	/**
 	 * Retrieves oEmbed from url/object ID
 	 * @since  0.9.5
@@ -138,7 +140,6 @@ public function get_oembed( $args ) {
 
 	}
 
-
 	/**
 	 * Hijacks retrieving of cached oEmbed.
 	 * Returns cached data from relevant object metadata (vs postmeta)
@@ -166,7 +167,6 @@ public function hijack_oembed_cache_get( $check, $object_id, $meta_key ) {
 
 	}
 
-
 	/**
 	 * Hijacks saving of cached oEmbed.
 	 * Saves cached data to relevant object metadata (vs postmeta)
@@ -190,7 +190,6 @@ public function hijack_oembed_cache_set( $check, $object_id, $meta_key, $meta_va
 		return true;
 	}
 
-
 	/**
 	 * Saves the cached oEmbed value to relevant object metadata (vs postmeta)
 	 *