• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

関数リファレンス/add meta box

提供: WordPress Codex 日本語版
移動先: 案内検索

説明

add_meta_box() は、WordPress 2.5 以降で利用できる関数です。プラグイン開発者は、管理画面にmeta boxを追加することができます。

この関数は add_meta_boxes_{post_type} または 'add_meta_boxes' アクションからコールされるべきです。 前者は他のポストタイプの不必要なコールバックを引き起こさないので、望ましいものです。 これらのアクションは Version 3.0 から導入されました。以前のバージョンでは代わりに 'admin_init' を使用してください。

使い方

 <?php
   add_meta_box( $id, $title, $callback, $screen, $context,
         $priority, $callback_args );
 ?>

パラメータ

$id
文字列) (必須) 編集画面セクションの HTML ID
初期値: なし
$title
文字列) (必須) 編集画面セクションのタイトル、画面上に表示される
初期値: なし
$callback
callback) (必須) 編集画面セクションに HTML 出力する関数. The function name as a string, or, within a class, an array to call one of the class's methods. The callback can accept up to two arguments: the first argument is the $post object for the post or page that is currently being edited. The second argument is the full $metabox item (an array), see Callback args. See the second example under Examples below.
初期値: なし
$screen
文字列) (オプション) The type of writing screen on which to show the edit screen section (examples include 'post','page','dashboard','link','attachment','custom_post_type','comment' where custom_post_type is the custom post type slug)
初期値: null
$context
文字列) (オプション) 編集画面セクションが表示される部分 ('normal', 'advanced' または (2.7 以降) 'side')
初期値: 'advanced'
$priority
文字列) (オプション) ボックスが表示される優先度 ('high', 'core', 'default' または 'low')
初期値: 'default'
$callback_args
array) (オプション) Arguments to pass into your callback function. The callback will receive the $post object and whatever parameters are passed through this variable.
初期値: null


用例

記事投稿画面とページ投稿画面にカスタムセクションを追加する例です。WordPress 2.5 やそれ以前のバージョン (add_meta_box が存在しない) でも動作します。

<?php
/* admin_menu アクションフックでカスタムボックスを定義 */
add_action('admin_menu', 'myplugin_add_custom_box');

/* データが入力された際 save_post アクションフックを使って何か行う */
add_action('save_post', 'myplugin_save_postdata');

/* 投稿・固定ページの "advanced" 画面にカスタムセクションを追加 */
function myplugin_add_custom_box() {

  if( function_exists( 'add_meta_box' )) {
    add_meta_box( 'myplugin_sectionid', __( 'My Post Section Title', 'myplugin_textdomain' ), 
                'myplugin_inner_custom_box', 'post', 'advanced' );
    add_meta_box( 'myplugin_sectionid', __( 'My Post Section Title', 'myplugin_textdomain' ), 
                'myplugin_inner_custom_box', 'page', 'advanced' );
   } else {
    add_action('dbx_post_advanced', 'myplugin_old_custom_box' );
    add_action('dbx_page_advanced', 'myplugin_old_custom_box' );
  }
}
   
/* カスタム投稿・固定ページセクションに内側のフィールドをプリント */
function myplugin_inner_custom_box() {

  // 認証に nonce を使う

  echo '<input type="hidden" name="myplugin_noncename" id="myplugin_noncename" value="' . 
    wp_create_nonce( plugin_basename(__FILE__) ) . '" />';

  // データ入力用の実際のフォーム

  echo '<label for="myplugin_new_field">' . __("Description for this field", 'myplugin_textdomain' ) . '</label> ';
  echo '<input type="text" name="myplugin_new_field" value="whatever" size="25" />';
}

/* 2.5 以前の WordPress で編集フォームをプリント */
function myplugin_old_custom_box() {

  echo '<div class="dbx-b-ox-wrapper">' . "\n";
  echo '<fieldset id="myplugin_fieldsetid" class="dbx-box">' . "\n";
  echo '<div class="dbx-h-andle-wrapper"><h3 class="dbx-handle">' . 
        __( '投稿セクションタイトル', 'myplugin_textdomain' ) . "</h3></div>";   
   
  echo '<div class="dbx-c-ontent-wrapper"><div class="dbx-content">';

  // 編集フォームを出力

  myplugin_inner_custom_box();

  // ラッパー終わり

  echo "</div></div></fieldset></div>\n";
}

/* 投稿を保存した際、カスタムデータも保存する */
function myplugin_save_postdata( $post_id ) {

  // データが先ほど作った編集フォームのから適切な認証とともに送られてきたかどうかを確認。
  // save_post は他の時にも起動する場合がある。

  if ( !wp_verify_nonce( $_POST['myplugin_noncename'], plugin_basename(__FILE__) )) {
    return $post_id;
  }

  // 自動保存ルーチンかどうかチェック。そうだった場合はフォームを送信しない(何もしない)
  if ( defined('DOING_AUTOSAVE') && DOING_AUTOSAVE ) 
    return $post_id;

  
  // パーミッションチェック
  if ( 'page' == $_POST['post_type'] ) {
    if ( !current_user_can( 'edit_page', $post_id ) )
      return $post_id;
  } else {
    if ( !current_user_can( 'edit_post', $post_id ) )
      return $post_id;
  }

  // 承認ができたのでデータを探して保存

  $mydata = $_POST['myplugin_new_field'];

  // $mydata を使って何かを行う
  // (add_post_meta()、update_post_meta()、またはカスタムテーブルを使うなど)

   return $mydata;
}
?>

※上記は以前の用例。最新の用例を以下に記します。

<?php

/**
 * 投稿と固定ページの編集画面メインカラムにボックスを追加
 */
function myplugin_add_meta_box() {

	$screens = array( 'post', 'page' );

	foreach ( $screens as $screen ) {

		add_meta_box(
			'myplugin_sectionid',
			__( 'My Post Section Title', 'myplugin_textdomain' ),
			'myplugin_meta_box_callback',
			$screen
		);
	}
}
add_action( 'add_meta_boxes', 'myplugin_add_meta_box' );

/**
 * ボックスのコンテンツをプリント
 * 
 * @param WP_Post $post The object for the current post/page.
 */
function myplugin_meta_box_callback( $post ) {

	// nonceフィールドを追加して後でチェックする
	wp_nonce_field( 'myplugin_save_meta_box_data', 'myplugin_meta_box_nonce' );

	/*
	 * DBから既存のvalueを検索してフォームのvalueに使うためにget_post_meta()を使用する
	 */
	$value = get_post_meta( $post->ID, '_my_meta_value_key', true );

	echo '<label for="myplugin_new_field">';
	_e( 'Description for this field', 'myplugin_textdomain' );
	echo '</label> ';
	echo '<input type="text" id="myplugin_new_field" name="myplugin_new_field" value="' . esc_attr( $value ) . '" size="25" />';
}

/**
 * 投稿が保存されたとき、カスタムデータも保存する
 *
 * @param int $post_id The ID of the post being saved.
 */
function myplugin_save_meta_box_data( $post_id ) {

	/*
	 * save_postアクションは他の時にも起動する場合があるので、
	 * 先ほど作った編集フォームのから適切な認証とともに送られてきたデータかどうかを検証する必要がある。
	 */

	// nonceがセットされているかどうか確認
	if ( ! isset( $_POST['myplugin_meta_box_nonce'] ) ) {
		return;
	}

	// nonceが正しいかどうか検証
	if ( ! wp_verify_nonce( $_POST['myplugin_meta_box_nonce'], 'myplugin_save_meta_box_data' ) ) {
		return;
	}

	// 自動保存の場合はなにもしない
	if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
		return;
	}

	// ユーザー権限の確認
	if ( isset( $_POST['post_type'] ) && 'page' == $_POST['post_type'] ) {

		if ( ! current_user_can( 'edit_page', $post_id ) ) {
			return;
		}

	} else {

		if ( ! current_user_can( 'edit_post', $post_id ) ) {
			return;
		}
	}

	/* 安全が確認できたのでデータを保存する */
	
	// データがセットされているか確認する
	if ( ! isset( $_POST['myplugin_new_field'] ) ) {
		return;
	}

	// ユーザーの入力を無害化する
	$my_data = sanitize_text_field( $_POST['myplugin_new_field'] );

	// フィールドを更新
	update_post_meta( $post_id, '_my_meta_value_key', $my_data );
}
add_action( 'save_post', 'myplugin_save_meta_box_data' );

クラス

This is an example of how to add a meta box from inside a class

<?php

/**
 * Calls the class on the post edit screen.
 */
function call_someClass() {
    new someClass();
}

if ( is_admin() ) {
    add_action( 'load-post.php', 'call_someClass' );
    add_action( 'load-post-new.php', 'call_someClass' );
}

/** 
 * The Class.
 */
class someClass {

	/**
	 * Hook into the appropriate actions when the class is constructed.
	 */
	public function __construct() {
		add_action( 'add_meta_boxes', array( $this, 'add_meta_box' ) );
		add_action( 'save_post', array( $this, 'save' ) );
	}

	/**
	 * Adds the meta box container.
	 */
	public function add_meta_box( $post_type ) {
            $post_types = array('post', 'page');     //limit meta box to certain post types
            if ( in_array( $post_type, $post_types )) {
		add_meta_box(
			'some_meta_box_name'
			,__( 'Some Meta Box Headline', 'myplugin_textdomain' )
			,array( $this, 'render_meta_box_content' )
			,$post_type
			,'advanced'
			,'high'
		);
            }
	}

	/**
	 * Save the meta when the post is saved.
	 *
	 * @param int $post_id The ID of the post being saved.
	 */
	public function save( $post_id ) {
	
		/*
		 * We need to verify this came from the our screen and with proper authorization,
		 * because save_post can be triggered at other times.
		 */

		// Check if our nonce is set.
		if ( ! isset( $_POST['myplugin_inner_custom_box_nonce'] ) )
			return $post_id;

		$nonce = $_POST['myplugin_inner_custom_box_nonce'];

		// Verify that the nonce is valid.
		if ( ! wp_verify_nonce( $nonce, 'myplugin_inner_custom_box' ) )
			return $post_id;

		// If this is an autosave, our form has not been submitted,
                //     so we don't want to do anything.
		if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) 
			return $post_id;

		// Check the user's permissions.
		if ( 'page' == $_POST['post_type'] ) {

			if ( ! current_user_can( 'edit_page', $post_id ) )
				return $post_id;
	
		} else {

			if ( ! current_user_can( 'edit_post', $post_id ) )
				return $post_id;
		}

		/* OK, its safe for us to save the data now. */

		// Sanitize the user input.
		$mydata = sanitize_text_field( $_POST['myplugin_new_field'] );

		// Update the meta field.
		update_post_meta( $post_id, '_my_meta_value_key', $mydata );
	}


	/**
	 * Render Meta Box content.
	 *
	 * @param WP_Post $post The post object.
	 */
	public function render_meta_box_content( $post ) {
	
		// Add an nonce field so we can check for it later.
		wp_nonce_field( 'myplugin_inner_custom_box', 'myplugin_inner_custom_box_nonce' );

		// Use get_post_meta to retrieve an existing value from the database.
		$value = get_post_meta( $post->ID, '_my_meta_value_key', true );

		// Display the form, using the current value.
		echo '<label for="myplugin_new_field">';
		_e( 'Description for this field', 'myplugin_textdomain' );
		echo '</label> ';
		echo '<input type="text" id="myplugin_new_field" name="myplugin_new_field"';
                echo ' value="' . esc_attr( $value ) . '" size="25" />';
	}
}

コールバック引数

The $callback_args array will be passed to the callback function as the second argument. The first argument is the post's $post object.

// This function adds a meta box with a callback function of my_metabox_callback()
function add_my_meta_box() {
     $var1 = 'this';
     $var2 = 'that';
     add_meta_box( 
           'metabox_id',
           'Metabox Title',
           'my_metabox_callback',
           'page',
           'normal',
           'low', 
           array( 'foo' => $var1, 'bar' => $var2)
      );
}

// $post is an object containing the current post (as a $post object)
// $metabox is an array with metabox id, title, callback, and args elements. 
// The args element is an array containing your passed $callback_args variables.

function my_metabox_callback ( $post, $metabox ) {
     echo 'Last Modified: ' . $post->post_modified;        // outputs last time the post was modified
     echo $metabox['args']['foo'];                         // outputs 'this'
     echo $metabox['args']['bar'];                         // outputs 'that'
     echo get_post_meta( $post->ID, 'my_custom_field', true ); // outputs value of custom field
}

ソースファイル

add_meta_box()wp-admin/includes/template.phpにあります。

関連記事


外部リソース


このページ「関数リファレンス/add meta box」は一部未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています


最新英語版: WordPress Codex » Function_Reference/add_meta_box最新版との差分

関数リファレンステンプレートタグ目次もご覧ください。