[wp-docs] The widget API

[Andrew Nacin]

I was flipping through the codex today and saw this on
http://codex.wordpress.org/Widgets_API#Function_Reference and I'm wondering
if the page can get some eyes on it at some point:

Note: It is advised not to 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().


When functions get added, we make sure they always work in a backwards
compatible way, or we deprecate it and come up with a new function, so I'm
not sure why we're advising plugin authors to avoid these, or why we suggest
they may arbitrarily change.

In this case, wp_register_sidebar_widget() and wp_register_widget_control()
are for the 2.8+ widget API. If you wanted to be compatible with pre-2.8,
you would use the older functions, register_sidebar_widget() and
register_widget_control(). (In 3.0, these functions, which have more or less
been deprecated since 2.8, now officially spit out a deprecated function
notice.)

The preferred situation would be to check if wp_register_sidebar_widget
exists, and if so, use that, and if not, register via the old API. That way
you're never using deprecated functions, yet the plugin can still support
legacy versions.

It would be great if this page can be updated at some point. Let me know how
I can help.

Thanks for all you do,
Nacin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.automattic.com/pipermail/wp-docs/attachments/20100323/46183c37/attachment.htm>