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

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

WordPress ウィジェット API

提供: WordPress Codex 日本語版
2009年5月30日 (土) 15:15時点におけるBono (トーク | 投稿記録)による版 (言語間リンク・原文リンク挿入、リンク調整等、未翻訳)

移動先: 案内検索

このページ「WordPress ウィジェット API」は未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

Widgets API

This page contains the technical documentation of the WordPress Widgets API (Application Programming Interface). The intended audience for this information includes WordPress theme authors, plug-in authors and anyone who would like to write a stand-alone widget. This document assumes a basic understanding of PHP scripting.

A widget is a PHP function that echoes string data to STDOUT when called. To turn such a PHP function into a Wordpress Widget it must be registered as such. This is done using a PHP callback (a Pseudo-Type in PHP documentation) that is registered by a wordpress widget API function.

register_sidebar_widget($callback);

The Wordpress widget API is located in wp-includes/widgets.php. It is advised to not use the functions starting with wp_ as these could change in subsequent releases. This is why we use register_sidebar_widget() instead of wp_register_sidebar_widget().

Function Reference

Sidebar Functions
Widget Functions

Developing New Widgets (2.8 and up)

Widget development has become easier since version 2.8. To create a widget, you only need to extend the standard widget class and some of it's functions.

That base class also contains information about the function that must be extended to get a working widget.

This sample code creates a Widget named FooWidget that has a settings form to change the display title.

/**
 * FooWidget Class
 */
class FooWidget extends WP_Widget {
    /** constructor */
    function FooWidget() {
        parent::WP_Widget(false, $name = 'FooWidget');	
    }

    /** @see WP_Widget::widget */
    function widget($args, $instance) {		
        extract( $args );
        ?>
              <?php echo $before_widget; ?>
                  <?php echo $before_title
                      . $instance['title']
                      . $after_title; ?>
                  Hello, World!
              <?php echo $after_widget; ?>
        <?php
    }

    /** @see WP_Widget::update */
    function update($new_instance, $old_instance) {				
        return $new_instance;
    }

    /** @see WP_Widget::form */
    function form($instance) {				
        $title = esc_attr($instance['title']);
        ?>
            <p><label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?> <input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" /></label></p>
        <?php 
    }

} // class FooWidget

This sample widget can then be registered in the widgets_init hook:

// register FooWidget widget
add_action('widgets_init', create_function('', 'return register_widget("FooWidget");'));

That's all. You will automatically get a multi-widget. No special tweaks needed any longer for that.

More information is available in the version information.

Developing New Widgets

The Google Search widget which was included in the deprecated (i.e. not needed since WordPress 2.2) original widget plugin is commented within inches of its life, so consider that your tutorial. Additionally, there are a few guidelines to follow:

  • Don’t execute any code while the plugin is being loaded. Use the plugins_loaded hook or you risk fatal errors due to undefined functions, or missing the boat completely because your plugin loaded before the one it depends on.
  • Use register_sidebar_widget($name, $callback) to add your widget to the admin interface.
  • Follow this template:
      function widget_myuniquewidget($args) {
          extract($args);
      ?>
              <?php echo $before_widget; ?>
                  <?php echo $before_title
                      . 'My Unique Widget'
                      . $after_title; ?>
                  Hello, World!
              <?php echo $after_widget; ?>
      <?php
      }
      register_sidebar_widget('My Unique Widget',
          'widget_myuniquewidget');

Important: To use the above in a plugin, wrap it with:

function widget_myuniquewidget_register() {
  --the above goes here--
  register_sidebar_widget('My Unique Widget','widget_myuniquewidget');}
add_action('init', widget_myuniquewidget_register);
  • Don’t leave out $before_widget, $after_widget, $before_title, or $after_title by accident. They are required for compatibility with various themes.
  • Name your widget and its functions carefully. Those strings will be used as HTML attributes and you don’t want to cause identical id’s in a single HTML document.
  • Localization is done internally to preserve the HTML id attribute. If you want your widget name localized with a textdomain, pass array($name, $textdomain) instead of $name.
  • To accommodate multi-widgets (e.g. Text and RSS) you can also pass a replacement value with the name: array($name_as_sprintf_pattern, $textdomain, $replacement). See the source.
  • You may use the variables mentioned above in different ways, or neglect them in some circumstances. Some widgets may not need a title, for example. Some widgets will use the $before_widget and $after_widget several times, or as arguments to tell another template tag how to format its output.
  • Optionally, use the following syntax to add a configuration page to the admin. Your callback will be used within the main form, so you must not include any <form> tags or a form submit button.
      register_widget_control($name, $callback [, $width [, $height ]] );
  • Namespace your form elements so they don’t conflict with other widgets.
  • Each widget must have a unique name. You can replace an already-registered widget by registering another one with the same name, supplying your own callback.
  • Any extra arguments to register_sidebar_widget() or register_widget_control() will be passed to your callback. See the Text and RSS widgets for examples.
  • Any widget or control can be “unregistered” by passing an empty string to the registration function.
  • There are probably some undocumented functions. You are encouraged to read the source code and see how we’ve created the standard widgets using these functions.
  • Please test your widgets with several themes other than Classic and Default (they both use the ul/li/h2 markup).
  • Please audit the security of your widgets before distributing them.
  • If you would like your widget to be considered for use on WordPress.com, send a link (no attachments please) to widgets@wordpress.com and we’ll have a look.

What else can I do with Widgets?

You have no idea how glad we are that you asked that. Here are a few ideas:

  • Write a theme that includes a special widget to set it apart from the others.
  • How about this for a special widget: a WordPress loop to show asides.
  • Register a replacement widget that buffers the original widget and transforms it somehow.
  • Remember that a “sidebar” is really just a name for a list. It can be displayed vertically or horizontally.
  • Remember that a “widget” is really just a name for a configurable code snippet. It can be invisible or it can be absolutely positioned.
  • Use the id and class attributes of any or all widgets in scripts to animate your sidebar.
  • Heck, use script.aculo.us or dbx (included with WordPress) to make your widgets draggable or even collapsible. Ain’t scripting sweet?
  • Remember that the widget control API is just for convenience. You can always set up your own admin page instead.
  • Support your users and get feedback so you can improve your widget. Put a link to your email or your site at the bottom of your widget control.
  • Send a link to your widgets to widgets@wordpress.com for review. We might put them up for everyone to use on WordPress.com. You could be internet famous!

Widgets - One or many

Widgets can be coded so that they can exist one time or they can exist multiple times. Wordpress is doing the work for you to instantiate your Widget multiple times if you follow some rules.

You can find a tutorial here.

最新英語版: WordPress Codex » Plugins/WordPress Widgets Api最新版との差分