WordPress:Plugins/WordPress Widgets Api
Widgets 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.
这个页面包括了WordPress Widgets API(应用程序接口)的技术文档。WordPress主题作者，插件作者，以及任何想要编写卓越的widget的人，都想要查看这个信息。阅读这个文档的前提是基本了解PHP脚本。
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.
Widget是个PHP 函数调用时，向STDOUT反映字符串数据。要将这样的PHP函数转变为Wordpress Widget，必须像这样注册。使用 PHP callback (PHP文档中的 准型)，由wordpress widget API函数注册，可以操作。
register_sidebar_widget($callback);
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().
Wordpress widget API位于wp-includes/widgets.php。建议不要使用，以wp_开头的函数，因为这些函数在随后的版本中会变化。这就是我们使用register_sidebar_widget()而不是使用wp_register_sidebar_widget()函数的原因。
Function Reference[ ]
函数参考[ ]
|
Developing New Widgets[ ]
开发新的Widgets[ ]
The Google Search widget is commented within inches of its life, so consider that your tutorial. Additionally, there are a few guidelines to follow:
Google 搜索widget注释尽在咫尺，因此考虑将这个作为你的指南。此外，需要遵循一些指导方针：
- Don’t execute any code while the plugin is 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.
- 载入插件的时候，不要运行任何代码。使用plugins_loaded hook或者因为未定义的函数，或者因为你的插件再没有依赖函数的情况下，载入，你坐失良机，冒着致命错误的危险。
- Use register_sidebar_widget($name, $callback) to add your widget to the admin interface.
- 使用register_sidebar_widget($name, $callback)将你的widget添加到管理界面。
- 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');
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');
- Don’t leave out $before_widget, $after_widget, $before_title, or $after_title by accident. They are required for compatibility with various themes.
- 不要碰巧遗漏了$before_widget, $after_widget, $before_title, 或者$after_title。需要这些函数与不同的主题兼容。
- 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.
- 仔细地命名你的widget和函数。这些字符串将会用作HTML属性而且你不希望在单一的HTML文档中产生同样的id’s。
- 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.
- 本地化是在内部完成的，保留HTML id 属性。如果你希望能使用文本域名本地化你的widget名称，请传递array($name, $textdomain)而不是$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.
- 要容纳多个widgets（例如文本和RSS），你可以使用下面的名称传递replacement参数值：array($name_as_sprintf_pattern, $textdomain, $replacement)。请看看原始资料。
- 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.
- 你可能以不同的方式使用上述提到的变数，或者在有些情况下，忽视这些变数。一些widgets可能不需要标题。有的widgets几次都用到$before_widget 和 $after_widget，或者作为参数通知其它模板标签怎样为输出内容设计格式。
- 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.
- 使用下面的语法将配置页面添加到管理。在主要的表格中会用到你的callback，因此你不应该包含任何<form>标签或者表格递交按钮。
register_widget_control($name, $callback
[, $width [, $height ]] );
register_widget_control($name, $callback
[, $width [, $height ]] );
- Namespace your form elements so they don’t conflict with other widgets.
- 给你的表格内容定义名字空间，这样与其它的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.
- 每个widget必须有个单独的名称，你可以通常同样名称的widget，替换已注册的widget，支持你自己的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.
- register_sidebar_widget()或者register_widget_control()的任何额外参数会传递到你的callback。请看看文本和RSS widget，作为例子参考。
- Any widget or control can be “unregistered” by passing an empty string to the registration function.
- 向注册函数传递空字符串，可以“取消注册”任何widget或者control。
- 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.
- 可能有一些违归档的函数。鼓励你阅读源代码，了解我们怎样使用这些函数，创建了标准的widgets。
- Please test your widgets with several themes other than Classic and Default (they both use the ul/li/h2 markup).
- 除了经典和默认主题（都使用ul/li/h2标记），请使用多个主题测试你的widgets。
- Please audit the security of your widgets before distributing them.
- 发行widgets之前，请审核widgets的安全性。
- 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.
- 如果你希望你的widget在WordPress.com上使用，请发送链接（不要加附件）到widgets@wordpress.com，我们会查看你的widget。
What else can I do with Widgets?[ ]
我还可以怎样处理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.
- 编写主题包含某个widget，将这个widget与其它的分开。
- How about this for a special widget: a WordPress loop to show asides.
- 为某个widget使用这个怎样：WordPress loop显示asides。
- Register a replacement widget that buffers the original widget and transforms it somehow.
- 注册replacement widget，buffer最初的widget并且将其转变。
- 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.
- 记住“widget”真的只是可配置的代码snippet的名称。可以是无形的，或者可以完全地放置。
- Use the id and class attributes of any or all widgets in scripts to animate your sidebar.
- 使用脚本中的任何或者所有widgets的id和class属性，装饰你的边栏。
- Heck, use script.aculo.us or dbx (included with WordPress) to make your widgets draggable or even collapsible. Ain’t scripting sweet?
- Heck，使用script.aculo.us 或者 dbx（包含在WordPress中），使得你的widgets可以拖拉或者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.
- 记住widget control API只是为了方便使用。你也可以经常设置你自己的管理页面。
- 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.
- 支持你的用户并且经常得到反馈，这样你能够改善你的widget。向你的电子邮件或者你的widget控制底部的你的站点添加链接。
- 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到widgets@wordpress.com以便查看。我们可以建议任何人都在WordPress.com 上使用这个widget。你就在网络上出名了！
Widgets - One or many[ ]
Widgets –一个或者许多[ ]
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.
Widgets可以再次编码，这样可以只存在一次或者多次。如果你遵循一些规则，WordPress会为你多次例示Widget。