Merge pull request #401 from alleyinteractive/core-term-meta

Add support for core term meta

Author: mboynes

fieldmanager.php

@@ -3,22 +3,22 @@
  * Fieldmanager Base Plugin File.
  *
  * @package Fieldmanager
- * @version 1.0.0-beta.2
+ * @version 1.0.0-beta.3
  */
 
 /*
 Plugin Name: Fieldmanager
 Plugin URI: https://github.com/alleyinteractive/wordpress-fieldmanager
 Description: Add fields to content types programatically.
 Author: Austin Smith
-Version: 1.0.0-beta.2
+Version: 1.0.0-beta.3
 Author URI: http://www.alleyinteractive.com/
 */
 
 /**
  * Current version of Fieldmanager.
  */
-define( 'FM_VERSION', '1.0.0-beta.2' );
+define( 'FM_VERSION', '1.0.0-beta.3' );
 
 /**
  * Filesystem path to Fieldmanager.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "Fieldmanager",
   "description": "Fieldmanager is a comprehensive toolkit for building forms, metaboxes, and custom admin screens for WordPress.",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "repository" : {
     "type" : "git",
     "url" : "https://github.com/alleyinteractive/wordpress-fieldmanager"

php/class-fieldmanager-field.php

@@ -971,7 +971,11 @@ public function add_page_form( $uniqid ) {
 
 	/**
 	 * Add a form on a term add/edit page
+	 *
+	 * @deprecated 1.0.0-beta.3 Replaced by {@see Fieldmanager_Field::add_term_meta_box()}.
+	 *
 	 * @see Fieldmanager_Context_Term
+	 *
 	 * @param string $title
 	 * @param string|array $taxonomies The taxonomies on which to display this form
 	 * @param boolean $show_on_add Whether or not to show the fields on the add term form
@@ -980,7 +984,46 @@ public function add_page_form( $uniqid ) {
 	 */
 	public function add_term_form( $title, $taxonomies, $show_on_add = true, $show_on_edit = true, $parent = '' ) {
 		$this->require_base();
-		return new Fieldmanager_Context_Term( $title, $taxonomies, $show_on_add, $show_on_edit, $parent, $this );
+		return new Fieldmanager_Context_Term( array(
+			'title'        => $title,
+			'taxonomies'   => $taxonomies,
+			'show_on_add'  => $show_on_add,
+			'show_on_edit' => $show_on_edit,
+			'parent'       => $parent,
+			// Use the deprecated FM Term Meta instead of core's term meta
+			'use_fm_meta'  => true,
+			'field'        => $this,
+		) );
+	}
+
+	/**
+	 * Add fields to the term add/edit page
+	 *
+	 * @see Fieldmanager_Context_Term
+	 *
+	 * @param string $title
+	 * @param string|array $taxonomies The taxonomies on which to display this form
+	 * @param boolean $show_on_add Whether or not to show the fields on the add term form
+	 * @param boolean $show_on_edit Whether or not to show the fields on the edit term form
+	 * @param int $parent Only show this field on child terms of this parent term ID
+	 */
+	public function add_term_meta_box( $title, $taxonomies, $show_on_add = true, $show_on_edit = true, $parent = '' ) {
+		// Bail if term meta table is not installed.
+		if ( get_option( 'db_version' ) < 34370 ) {
+			_doing_it_wrong( __METHOD__, esc_html__( 'This method requires WordPress 4.4 or above', 'fieldmanager' ), 'Fieldmanager-1.0.0-beta.3' );
+			return false;
+		}
+
+		$this->require_base();
+		return new Fieldmanager_Context_Term( array(
+			'title'        => $title,
+			'taxonomies'   => $taxonomies,
+			'show_on_add'  => $show_on_add,
+			'show_on_edit' => $show_on_edit,
+			'parent'       => $parent,
+			'use_fm_meta'  => false,
+			'field'        => $this,
+		) );
 	}
 
 	/**

php/context/class-fieldmanager-context-term.php

@@ -45,8 +45,22 @@ class Fieldmanager_Context_Term extends Fieldmanager_Context_Storable {
 	public $reserved_fields = array( 'name', 'slug', 'description' );
 
 	/**
-	 * @var Fieldmanager_Group
+	 * Use FM term meta or WordPres core term meta. The default is a bit
+	 * confusing: technically, it's to use core's term meta, but if the class is
+	 * instantiated using the now-deprecated separated arguments, this gets set
+	 * to true for backwards-compatibility purposes.
+	 *
+	 * This should be false whenever possible to instead use core's built-in
+	 * term meta (introduced in WordPress 4.4).
+	 *
+	 * @var boolean
+	 */
+	public $use_fm_meta = false;
+
+	/**
 	 * Base field
+	 *
+	 * @var Fieldmanager_Field
 	 */
 	public $fm = '';
 
@@ -58,29 +72,77 @@ class Fieldmanager_Context_Term extends Fieldmanager_Context_Storable {
 
 
 	/**
-	 * Add a context to a fieldmanager
-	 * @param string|string[] $taxonomies
-	 * @param boolean $show_on_add Whether or not to show the fields on the add term form
-	 * @param boolean $show_on_edit Whether or not to show the fields on the edit term form
-	 * @param Fieldmanager_Field $fm
+	 * Instantiate this context. You can either pass an array of all args
+	 * (preferred), or pass them individually (deprecated).
+	 *
+	 * @param array|string $args {
+	 *     Array of arguments.
+	 *
+	 *     If a string (deprecated), this will be used as the $title.
+	 *
+	 *     @type string $title The context/meta box title.
+	 *     @type string|array $taxonomies The taxonomy/taxonomies to which to
+	 *                                    add this field.
+	 *     @type bool $show_on_add Optional. Should this field show on the "Add
+	 *                             Term" screen? Defaults to yes (true).
+	 *     @type bool $show_on_edit Optional. Should this field show on the
+	 *                              "Edit Term" screen? Defaults to yes (true).
+	 *     @type int $parent Optional. Should this field only show if its parent
+	 *                       matches this term ID?
+	 *     @type bool $use_fm_meta Optional. Should this context store its data
+	 *                             using FM term meta (true, deprecated) or
+	 *                             WordPress core term meta (false). Defaults to
+	 *                             false.
+	 *     @type Fieldmanager_Field $field Optional. The field to which to
+	 *                                     attach this context.
+	 * }
+	 * @param string|array $taxonomies Optional. Deprecated. Required if $args
+	 *                                 is a string.
+	 * @param boolean $show_on_add Optional. Deprecated.
+	 * @param boolean $show_on_edit Optional. Deprecated.
+	 * @param string $parent Optional. Deprecated.
+	 * @param Fieldmanager_Field $fm Optional. Deprecated.
 	 */
-	public function __construct( $title, $taxonomies, $show_on_add = true, $show_on_edit = true, $parent = '', $fm = null ) {
-		// Populate the list of taxonomies for which to add this meta box with the given settings
-		if ( ! is_array( $taxonomies ) ) {
-			$taxonomies = array( $taxonomies );
-		}
+	public function __construct( $args, $taxonomies = array(), $show_on_add = true, $show_on_edit = true, $parent = '', $fm = null ) {
+		if ( is_array( $args ) ) {
+			$args = wp_parse_args( $args, array(
+				'show_on_add'  => true,
+				'show_on_edit' => true,
+				'parent'       => '',
+				'use_fm_meta'  => false,
+				'field'        => null,
+			) );
+			if ( ! isset( $args['title'], $args['taxonomies'] ) ) {
+				throw new FM_Developer_Exception( esc_html__( '"title" and "taxonomies" are required values for Fieldmanager_Context_Term', 'fieldmanager' ) );
+			}
 
-		// Set the class variables
-		$this->title = $title;
-		$this->taxonomies = $taxonomies;
-		$this->show_on_add = $show_on_add;
-		$this->show_on_edit = $show_on_edit;
-		$this->parent = $parent;
-		$this->fm = $fm;
+			$this->title        = $args['title'];
+			$this->taxonomies   = (array) $args['taxonomies'];
+			$this->show_on_add  = $args['show_on_add'];
+			$this->show_on_edit = $args['show_on_edit'];
+			$this->parent       = $args['parent'];
+			$this->use_fm_meta  = $args['use_fm_meta'];
+			$this->fm           = $args['field'];
+		} elseif ( empty( $taxonomies ) ) {
+			throw new FM_Developer_Exception( esc_html__( '"title" and "taxonomies" are required values for Fieldmanager_Context_Term', 'fieldmanager' ) );
+		} else {
+			// Instantiating Fieldmanager_Context_Term using individual
+			// arguments is deprecated as of Fieldmanager-1.0.0-beta.3; you
+			// should pass an array of arguments instead.
+
+			// Set the class variables
+			$this->title        = $args;
+			$this->taxonomies   = (array) $taxonomies;
+			$this->show_on_add  = $show_on_add;
+			$this->show_on_edit = $show_on_edit;
+			$this->parent       = $parent;
+			$this->use_fm_meta  = true;
+			$this->fm           = $fm;
+		}
 
 		// Iterate through the taxonomies and add the fields to the requested forms
 		// Also add handlers for saving the fields and which forms to validate (if enabled)
-		foreach ( $taxonomies as $taxonomy ) {
+		foreach ( $this->taxonomies as $taxonomy ) {
 			if ( $this->show_on_add ) {
 				add_action( $taxonomy . '_add_form_fields', array( $this, 'add_term_fields' ), 10, 1 );
 				add_action( 'created_term', array( $this, 'save_term_fields'), 10, 3 );
@@ -91,8 +153,10 @@ public function __construct( $title, $taxonomies, $show_on_add = true, $show_on_
 				add_action( 'edited_term', array( $this, 'save_term_fields'), 10, 3 );
 			}
 
-			// Also handle removing data when a term is deleted
-			add_action( 'delete_term', array( $this, 'delete_term_fields'), 10, 4 );
+			if ( $this->use_fm_meta ) {
+				// Handle removing FM term meta when a term is deleted
+				add_action( 'delete_term', array( $this, 'delete_term_fields'), 10, 4 );
+			}
 		}
 	}
 
@@ -229,14 +293,17 @@ public function save_to_term_meta( $term_id, $taxonomy, $data = null ) {
 	}
 
 	/**
-	 * Saves custom fields for the sport taxonomy
+	 * Saves custom fields for the sport taxonomy.
+	 *
+	 * @deprecated Fieldmanager-1.0.0-beta.3 This is not necessary if you're
+	 *                                       using core's term meta.
 	 *
 	 * @access public
+	 *
 	 * @param int $term_id
 	 * @param int $tt_id
 	 * @param string $taxonomy
 	 * @param WP_term $deleted_term
-	 * @return void
 	 */
 	public function delete_term_fields( $term_id, $tt_id, $taxonomy, $deleted_term ) {
 		// Get an instance of the term meta class
@@ -249,37 +316,57 @@ public function delete_term_fields( $term_id, $tt_id, $taxonomy, $deleted_term )
 	/**
 	 * Callback to get term meta for the given term ID and current taxonomy.
 	 *
-	 * @see Fieldmanager_Util_Term_Meta::get_term_meta()
+	 * @see get_term_meta().
+	 * @see Fieldmanager_Util_Term_Meta::get_term_meta() (Deprecated).
 	 */
 	protected function get_data( $term_id, $meta_key, $single = false ) {
-		return fm_get_term_meta( $term_id, $this->current_taxonomy, $meta_key, $single );
+		if ( $this->use_fm_meta ) {
+			return fm_get_term_meta( $term_id, $this->current_taxonomy, $meta_key, $single );
+		} else {
+			return get_term_meta( $term_id, $meta_key, $single );
+		}
 	}
 
 	/**
 	 * Callback to add term meta for the given term ID and current taxonomy.
 	 *
-	 * @see Fieldmanager_Util_Term_Meta::add_term_meta()
+	 * @see add_term_meta().
+	 * @see Fieldmanager_Util_Term_Meta::add_term_meta() (Deprecated).
 	 */
 	protected function add_data( $term_id, $meta_key, $meta_value, $unique = false ) {
-		return fm_add_term_meta( $term_id, $this->current_taxonomy, $meta_key, $meta_value, $unique );
+		if ( $this->use_fm_meta ) {
+			return fm_add_term_meta( $term_id, $this->current_taxonomy, $meta_key, $meta_value, $unique );
+		} else {
+			return add_term_meta( $term_id, $meta_key, $meta_value, $unique );
+		}
 	}
 
 	/**
 	 * Callback to update term meta for the given term ID and current taxonomy.
 	 *
-	 * @see Fieldmanager_Util_Term_Meta::update_term_meta()
+	 * @see update_term_meta().
+	 * @see Fieldmanager_Util_Term_Meta::update_term_meta() (Deprecated).
 	 */
 	protected function update_data( $term_id, $meta_key, $meta_value, $meta_prev_value = '' ) {
-		return fm_update_term_meta( $term_id, $this->current_taxonomy, $meta_key, $meta_value, $meta_prev_value );
+		if ( $this->use_fm_meta ) {
+			return fm_update_term_meta( $term_id, $this->current_taxonomy, $meta_key, $meta_value, $meta_prev_value );
+		} else {
+			return update_term_meta( $term_id, $meta_key, $meta_value, $meta_prev_value );
+		}
 	}
 
 	/**
 	 * Callback to delete term meta for the given term ID and current taxonomy.
 	 *
-	 * @see Fieldmanager_Util_Term_Meta::delete_term_meta()
+	 * @see delete_term_meta().
+	 * @see Fieldmanager_Util_Term_Meta::delete_term_meta() (Deprecated).
 	 */
 	protected function delete_data( $term_id, $meta_key, $meta_value = '' ) {
-		return fm_delete_term_meta( $term_id, $this->current_taxonomy, $meta_key, $meta_value );
+		if ( $this->use_fm_meta ) {
+			return fm_delete_term_meta( $term_id, $this->current_taxonomy, $meta_key, $meta_value );
+		} else {
+			return delete_term_meta( $term_id, $meta_key, $meta_value );
+		}
 	}
 
 }