CMB2 2.7.0, Array enhancements, Bugfixes and compatibility.

Version 2.17.0 of WordPress Libs is now available for public use. This release focused on getting everything ready for CMB2 version 2.7.0. It also includes many bug fixes and compatibility improvements.

CMB2 2.7.0

CMB2 released version 2.7.0 back in January. Since it took a year for that release to be ready, we wanted to wait a while to make sure there were not going to be any quick follow-up bug fixes before we implemented it. Now that we are confident it is ready for prime time, we’ve added support for the new features.

display_class field parameter

The Field class now contains the display_class property to assign an entirely custom class to use for rendering within admin columns and likewise. As a custom display class should extend the CMB2_Field_Display class, we’ve typed this property appropriately.

register_rest_field_cb box paramter

The Box class now contains the register_rest_field_cb property to replace the registering of the rest fields for the particular box. Used when an entirely custom response is desired.

char_counter field parameters

A new char_counter method has been added to the Field class which takes care of the heavy lifting when adding a character counter to a field. Character counters are now supported on textarea, text, or wysiwyg type fields.

	/**
	 * Enable a character/word counter for a 'textarea', 'wysiwyg', or 'text' type field.
	 *
	 * @param bool $count_words – Count words instead of characters.
	 * @param null|int  $max – Show remaining character/words based on provided limit.
	 * @param bool  $enforce – Enforce max length using `maxlength` attribute when
	 *                       characters are counted.
	 * @param array $labels  – Override the default text strings associated with these
	 *                       parameters {
	 *                          'words_left_text' – Default: "Words left"
	 *                          'words_text' – Default: "Words"
	 *                          'characters_left_text' – Default: "Characters left"
	 *                          'characters_text' – Default: "Characters"
	 *                          'characters_truncated_text' – Default: "Your text may be truncated."
	 *                       }
	 *
	 * @notice Does not work with wysiwyg which are repeatable.
	 *
	 * @since CMB2 2.7.0
	 *
	 * @return Field
	 */
	public function char_counter( $count_words = false, $max = null, $enforce = false, $labels = [] ) : Field {
		$this->char_counter = $count_words ? 'words' : true;

		if ( $max ) {
			$this->char_max = $max;
			if ( $enforce ) {
				if ( 'words' === $this->char_counter ) {
					\_doing_it_wrong( 'char_counter', __( 'You cannot enforce max length when counting words', 'lipe' ), '2.17.0' );
				}
				$this->char_max_enforce = true;
			}
		}

		if ( ! empty( $labels ) ) {
			$this->text = array_merge( (array) $this->text, \array_intersect_key( $labels, array_flip( [
				'words_left_text',
				'words_text',
				'characters_left_text',
				'characters_text',
				'characters_truncated_text',
			] ) ) );
		}

		return $this;
	}

The method accepts the following arguments:

1. bool $count_words – By default the field will count characters; if you would like it to count words, pass true.
2. int $max – If set, this will count down the characters/words until maximum is reached.
3. bool $enforce – If we are counting characters, you may force the field to only allow the specified $max.
4. array $labels – Override the labels used for various states throughout the counting process.

Support taxonomy_select_hierarchical field type

The Field_Type class now contains mappings for the new taxonomy_select_hierarchical field. It functions the same as the previously existing taxonomy_select field except the hierarchy is indented on display.

/**
	 * A select field pre-populated with taxonomy terms and displayed hierarchical.
	 *
	 * @param string $taxonomy       – slug
	 * @param string $no_terms_text
	 * @param bool   $remove_default – remove default WP terms metabox
	 *
	 * @todo Add links once docs become available.
	 *
	 * @since CMB2 2.7.0
	 *
	 * @return Field
	 */
	public function taxonomy_select_hierarchical( $taxonomy, $no_terms_text = null, $remove_default = null ) : Field {
		$_args = $this->field_type_taxonomy( $this->taxonomy_select_hierarchical, $taxonomy, $no_terms_text, $remove_default );

		return $this->set( $_args, Repo::TAXONOMY_SINGULAR );
	}

Add disable_sorting parameter to column method

CMB2 now supports sorting the post list by column by default. This may be disabled per field by passing a disable_sortable to the column arguments. You may now set $disable_sorting to true using the method to disable sorting.

New array_map_assoc method

The Arrays class now contains an array_map_assoc method which automatically passes the array key as the second argument to the specified callback and preserves the original keys.

	/**
	 * Works the same as `array_map` except the array key is passed as the
	 * second argument to the callback and original keys are preserved.
	 *
	 *
	 * @param callable $callback
	 * @param array    $array
	 *
	 * @since 2.17.0
	 *
	 * @return array
	 */
	public function array_map_assoc( callable $callback, array $array ) : array {
		return array_combine( array_keys( $array ), array_map( $callback, $array, array_keys( $array ) ) );
	}

Settings Trait now supports a callback during update_option

Building off of the support already available with the Mutator_Trait you may now pass a callback as the $value argument of update_option. This callback will receive the previous value as an argument and should return the new value.