search

jtsternberg / Taxonomy_MetaData

WordPress Helper Class for saving pseudo-metadata for taxonomy terms
54 stars 10 forks source link

readme

Taxonomy_MetaData

YOU SHOULD NO LONGER USE THIS AS TERM META IS NOW IN CORE, AND CMB2 NOW SUPPORTS IT.

WordPress Helper Class for saving pseudo-metadata for taxonomy terms. This is not recommend if using on a very large number of terms, UNLESS using a plugin like wp-large-options. The third parameter is used to override the get/set/delete options callbacks so that you can use wp-large-options (or something like it).

Includes an extended class for using CMB2 to generate the actual form fields. This is handy if you need more advanced fields, or do not want to create your own field render_cbs.

Originally inspired by @williamsba. Read his article here: How To: Save Taxonomy Meta Data as an Options Array in WordPress.

Available methods for retrieving data:

To initate Taxonomy_MetaData and add fields to a taxonomy:

<?php

function taxonomy_meta_initiate() {

    require_once( 'Taxonomy_MetaData/Taxonomy_MetaData.php' );

    /**
     * Instantiate our taxonomy meta class
     */
    $cats = new Taxonomy_MetaData( 'category', array(
        // Term option key
        'about_text' => array(
            // Field label
            'label'    => __( 'About section for this term.', 'taxonomy-metadata' ),
            // Sanitization callback
            'sanitize_cb' => 'wp_kses_post',
            // Render callback
            'render_cb' => 'taxonomy_metadata_textarea',
        ),
    ), __( 'Category Settings', 'taxonomy-metadata' ) /* Settings heading */ );

    $tags = new Taxonomy_MetaData( 'post_tag', array(
        'arbitrary_text' => array(
            'label'       => __( 'Arbitrary text for tags', 'taxonomy-metadata' ),
            // Optional input description
            'desc'        => __( 'A description for this field', 'taxonomy-metadata' ),
            // Optional placeholder text if no value is saved
            'placeholder' => __( 'Placeholder text', 'taxonomy-metadata' ),
        ),
    ) );

}
taxonomy_meta_initiate();

/**
 * Textarea callback for Taxonomy_MetaData
 * @param  array  $field Field config
 * @param  mixed  $value Field value
 */
function taxonomy_metadata_textarea( $field, $value ) {
    echo '<textarea class="taxonomy-metadata-textarea" name="'. $field->id .'" id="'. $field->id .'">'. esc_textarea( $value ) .'</textarea>';
    if ( isset( $field->desc ) && $field->desc )
        echo "\n<p class=\"description\">{$field->desc}</p>\n";

}

To use wp_large_options (recommended):

<?php

function taxonomy_meta_initiate() {

    // Including Taxonomy_MetaData .php. Update to reflect your file structure
    if ( ! class_exists( 'Taxonomy_MetaData' ) ) {
        require_once( 'Taxonomy_MetaData/Taxonomy_MetaData.php' );
    }

    // Form title
    $title = __( 'Category Archive Options', 'taxonomy-metadata' );

    // Category fields
    $fields = array(
        'arbitrary_text' => array(
            'label'       => __( 'Arbitrary text for tags', 'taxonomy-metadata' ),
            'desc'        => __( 'A description for this field', 'taxonomy-metadata' ),
            'placeholder' => __( 'Placeholder text', 'taxonomy-metadata' ),
        ),
    );

    // (Recommended) Use wp-large-options
    if ( ! defined( 'wlo_update_option' ) ) {
        require_once( 'wp-large-options/wp-large-options.php' );
    }

    // get/set/delete overrides using wp-large-options
    $wlo_overrides = array(
        'get_option'    => 'wlo_get_option',
        'update_option' => 'wlo_update_option',
        'delete_option' => 'wlo_delete_option',
    );

    /**
     * Instantiate our taxonomy meta object
     */
    new Taxonomy_MetaData( 'category', $fields, $title, $wlo_overrides );
}
taxonomy_meta_initiate();

To use Taxonomy_MetaData with CMB2:

<?php

// Including CMB2's init file (unless you have CMB2 installed as a plugin)
require_once( 'CMB2/init.php' );

function taxonomy_metadata_cmb2_init() {

    // Including Taxonomy_MetaData_CMB2.php. Update to reflect your file structure
    if ( ! class_exists( 'Taxonomy_MetaData_CMB2' ) ) {
        require_once( 'Taxonomy_MetaData/Taxonomy_MetaData_CMB2.php' );
    }

    $metabox_id = 'cat_options';

    /**
     * Semi-standard CMB metabox/fields registration
     */
    $cmb = new_cmb2_box( array(
        'id'           => $metabox_id,
        'object_types' => array( 'key' => 'options-page', 'value' => array( 'unknown', ), ),
    ) );

    $cmb->add_field( array(
        'name' => __( 'Category Archive Featured Post', 'taxonomy-metadata' ),
        'desc' => __( 'Enter Post ID', 'taxonomy-metadata' ),
        'id'   => 'feat_post', // no prefix needed since the options are one option array.
        'type' => 'text',
    ) );

    $cmb->add_field( array(
        'name' => __( 'Test Checkbox', 'taxonomy-metadata' ),
        'desc' => __( 'field description (optional)', 'taxonomy-metadata' ),
        'id'   => 'test_checkbox',
        'type' => 'checkbox',
    ) );

    $cmb->add_field( array(
        'name' => __( 'Test Text Small', 'taxonomy-metadata' ),
        'desc' => __( 'field description (optional)', 'taxonomy-metadata' ),
        'id'   => 'test_textsmall',
        'type' => 'text_small',
        // 'repeatable' => true,
    ) );

    $cmb->add_field( array(
        'name'    => __( 'Test wysiwyg', 'taxonomy-metadata' ),
        'desc'    => __( 'field description (optional)', 'taxonomy-metadata' ),
        'id'      => 'test_wysiwyg',
        'type'    => 'wysiwyg',
        'options' => array( 'textarea_rows' => 5, ),
    ) );

    // (Recommended) Use wp-large-options
    if ( ! defined( 'wlo_update_option' ) ) {
        require_once( 'wp-large-options/wp-large-options.php' );
    }

    // wp-large-options overrides
    $wlo_overrides = array(
        'get_option'    => 'wlo_get_option',
        'update_option' => 'wlo_update_option',
        'delete_option' => 'wlo_delete_option',
    );

    /**
     * Instantiate our taxonomy meta class
     */
    $cats = new Taxonomy_MetaData_CMB2( 'category', $metabox_id, __( 'Category Settings', 'taxonomy-metadata' ), $wlo_overrides );
}
add_action( 'cmb2_init', 'taxonomy_metadata_cmb2_init' );

Changelog