(New page: ==I’m a theme author. What’s with all this email asking me to update my theme?== You should be happy they like your theme well enough to contact you rather than switch to somebody els...) |
(→How to display new Widget Areas) |
||
| (57 intermediate revisions by 23 users not shown) | |||
| Line 1: | Line 1: | ||
| + | {{Languages| |
||
| − | ==I’m a theme author. What’s with all this email asking me to update my theme?== |
||
| + | {{en|Widgetizing Themes}} |
||
| + | {{fr|Widgetiser les Themes}} |
||
| + | {{ja|Widgetizing Themes}} |
||
| + | {{pt-br|Widgets em Temas}} |
||
| + | {{zh-cn|令主题支持小工具}} |
||
| + | {{mk|Виџетизирање}} |
||
| + | }} |
||
| + | ===What is Widgetizing?=== |
||
| − | You should be happy they like your theme well enough to contact you rather than switch to somebody else’s themes. Well done on making users happy! We’re sorry if that seems threatening. It hurt us more than it hurt you. Please fix up your theme. Widgets are now a standard part of the WordPress install so to reach the broadest audience your theme should support them, as well as supporting old style sidebars. |
||
| + | Widgetizing is a pseudo word that describes the process of implementing [http://codex.wordpress.org/Glossary#Widget Widgets] and Widget Areas into your Theme. |
||
| − | == |
+ | ===How to Register a Widget Area=== |
| + | The following should be added to your Theme's functions.php file: |
||
| + | <pre id="how-to-register-a-widget-area"> |
||
| + | <?php |
||
| + | /** |
||
| + | * Register our sidebars and widgetized areas. |
||
| + | * |
||
| + | */ |
||
| + | function arphabet_widgets_init() { |
||
| + | register_sidebar( array( |
||
| − | First you have to ask yourself, “Do I know anything about my theme? Does it use an unordered list to create the sidebar?” (If you can’t answer that, you’ll need in-depth help on this task and that usually means paying somebody a lot of money or asking very nicely at the forums. Better yet, you can learn HTML. Sorry, we don’t teach that here.) |
||
| + | 'name' => 'Home right sidebar', |
||
| + | 'id' => 'home_right_1', |
||
| + | 'before_widget' => '<div>', |
||
| + | 'after_widget' => '</div>', |
||
| + | 'before_title' => '<h2 class="rounded">', |
||
| + | 'after_title' => '</h2>', |
||
| + | ) ); |
||
| + | } |
||
| − | Here is an example of good sidebar markup: |
||
| + | add_action( 'widgets_init', 'arphabet_widgets_init' ); |
||
| − | |||
| + | ?> |
||
| − | <pre> |
||
| − | <ul id="sidebar"> |
||
| − | <li id="about"> |
||
| − | <h2>About</h2> |
||
| − | <p>This is my blog.</p> |
||
| − | </li> |
||
| − | <li id="links"> |
||
| − | <h2>Links</h2> |
||
| − | <ul> |
||
| − | <li><a href="http://example.com">Example</a></li> |
||
| − | </ul> |
||
| − | </li> |
||
| − | </ul> |
||
</pre> |
</pre> |
||
| + | === How to display new Widget Areas === |
||
| − | Notice that the entire sidebar is an unordered list and the titles are in <h2> tags. Not every theme is built this way and it’s not necessary to do so, but it’s currently the most common sidebar markup in the themes we surveyed so we adopted it. The element with id=”links” is the equivalent of one basic widget. |
||
| + | You can display your new widget area by: |
||
| − | The [[Plugins/WordPress_Widgets_Api|Widget API]] offers a few functions to use in your template just like template tags. These functions let WordPress replace your theme’s sidebar with a dynamic one while still falling back on the old sidebar in case you remove all the widgets. |
||
| + | # Adding the code directly to a theme file like the sidebar.php file; or |
||
| + | # Using a custom function with hook in your functions.php file. |
||
| − | Here |
+ | Here's some example code that is a common way to add your new widget area to a parent or child theme: |
<pre> |
<pre> |
||
| + | <?php if ( is_active_sidebar( 'home_right_1' ) ) : ?> |
||
| − | <ul id="sidebar"> |
||
| + | <div id="primary-sidebar" class="primary-sidebar widget-area" role="complementary"> |
||
| − | <?php if ( !function_exists('dynamic_sidebar') |
||
| − | + | <?php dynamic_sidebar( 'home_right_1' ); ?> |
|
| + | </div><!-- #primary-sidebar --> |
||
| − | <li id="about"> |
||
| − | <h2>About</h2> |
||
| − | <p>This is my blog.</p> |
||
| − | </li> |
||
| − | <li id="links"> |
||
| − | <h2>Links</h2> |
||
| − | <ul> |
||
| − | <li><a href="http://example.com">Example</a></li> |
||
| − | </ul> |
||
| − | </li> |
||
<?php endif; ?> |
<?php endif; ?> |
||
| − | </ul> |
||
</pre> |
</pre> |
||
| + | The above code can be added to your sidebar.php file. It checks to see if the widget area is populated (i.e. is active) and then displays the contents of the widget if active. |
||
| − | See? We just added two lines to the template and now it’ll display a dynamic sidebar if possible, otherwise display the old sidebar. Removing all the widgets from the sidebar in the admin interface will cause the old sidebar to be displayed. |
||
| − | |||
| − | Now there is one more thing to be done to the theme. Assuming you are using WordPress 2.0 or higher, this change will be made within functions.php in your theme’s directory. |
||
| − | |||
| − | Here is an example of functions.php for a theme that does not yet have such a file (no blank lines at the beginning or end of the file, please): |
||
| + | This is the function which outputs the widget: |
||
<pre> |
<pre> |
||
| + | <?php dynamic_sidebar( 'home_right_1' ); ?> |
||
| − | <?php |
||
| − | if ( function_exists('register_sidebar') ) |
||
| − | register_sidebar(); |
||
| − | ?> |
||
</pre> |
</pre> |
||
| + | The code above will display the widget registered with an ID value of 'home_right_1'. When displaying a widget on your site, remember to replace 'home_right_1' with the ID value you specified when you registered your widget. |
||
| − | That’s it, just four lines. This code tells the plugin that your theme will need exactly one dynamic sidebar. At this point, your admin interface should have an extra item in the Presentation menu: Sidebar Widgets. Try dragging some widgets from the palette on the left into the box marked Sidebar 1 and saving your changes. Got it working? Fantastic. |
||
| + | For more information, please refer to the [http://codex.wordpress.org/Widgets_API Widgets API] to learn how to, programmatically, [http://codex.wordpress.org/Widgets_API#Displaying_Widgets display Widgets and Widget Areas]. |
||
| − | ===My sidebar isn’t a list. What do I do?=== |
||
| + | If you're not a programmer, you should refer to the [http://codex.wordpress.org/WordPress_Widgets WordPress Widgets] page. |
||
| − | We knew you’d ask that. You’ll have to discover your sidebar’s design pattern, then use some extra parameters to tell the plugin how to format them to work with your theme. We’ll work through one example. |
||
| + | === Create New Widget Area Using Custom Function === |
||
| − | Here’s the original markup: |
||
| + | You can use WordPress or theme specific hooks to display new widget areas in your theme directly from your parent or child themes functions file. |
||
<pre> |
<pre> |
||
| + | function wpsites_before_post_widget( $content ) { |
||
| − | <div id="sidebar"> |
||
| + | if ( is_singular( array( 'post', 'page' ) ) && is_active_sidebar( 'before-post' ) && is_main_query() ) { |
||
| − | <div class="title">About</div> |
||
| + | dynamic_sidebar('before-post'); |
||
| − | <p>This is my blog.</p> |
||
| + | } |
||
| − | <div class="title">Links</div> |
||
| + | return $content; |
||
| − | <ul> |
||
| + | } |
||
| − | <li><a href="http://example.com">Example</a></li> |
||
| + | add_filter( 'the_content', 'wpsites_before_post_widget' ); |
||
| − | </ul> |
||
| − | </div> |
||
</pre> |
</pre> |
||
| + | The above code displays a new widget area before all single posts and pages in any theme using the_content [http://codex.wordpress.org/Plugin_API/Filter_Reference/the_content] filter however it is suggested you use theme specific hooks if your theme includes them. |
||
| − | Yes, we’ve seen markup like this. It’s the second most common sidebar design pattern, which is why we chose it for the example. The first difference is that the sidebar is not built inside a <ul> tag. That means we should not be wrapping any of our widgets in <li> tags. The second difference is that our titles are wrapped in <div class=”title”> instead of <h2> tags. |
||
| + | Note: You will also need to register a new widget area using the same ID as what you use in the dynamic sidebar which in this example is before-post. |
||
| − | We prefer to change the markup to our ul/li/h2 standard, but the API is powerful enough that we don’t have to. Instead, we fix these issues by adding some parameters to the code in functions.php: |
||
<pre> |
<pre> |
||
| + | register_sidebar( array( |
||
| − | <?php |
||
| + | 'id' => 'before-post', |
||
| − | if ( function_exists('register_sidebar') ) |
||
| + | 'name' => 'Before Posts Widget', |
||
| − | register_sidebar(array( |
||
| + | 'description' => __( 'Your Widget Description.', 'text_domain' ), |
||
| − | 'before_widget' => '', |
||
| + | ) ); |
||
| − | 'after_widget' => '', |
||
| − | 'before_title' => '<div class="title">', |
||
| − | 'after_title' => '</div>', |
||
| − | )); |
||
| − | ?> |
||
</pre> |
</pre> |
||
| + | == Resources == |
||
| − | And here is the sidebar.php markup with our special template tags inserted: |
||
| + | * [http://generatewp.com/sidebar/ WordPress Sidebar Generator] |
||
| + | == Related == |
||
| − | <pre> |
||
| − | <div id="sidebar"> |
||
| − | <?php if ( !function_exists('dynamic_sidebar') |
||
| − | || !dynamic_sidebar() ) : ?> |
||
| − | <div class="title">About</div> |
||
| − | <p>This is my blog.</p> |
||
| − | <div class="title">Links</div> |
||
| − | <ul> |
||
| − | <li><a href="http://example.com">Example</a></li> |
||
| − | </ul> |
||
| − | <?php endif; ?> |
||
| − | </div> |
||
| − | </pre> |
||
| − | |||
| − | That’s it. Your HTML markup is taken care of. |
||
| − | |||
| − | Well, mostly taken care of. The default before_widget is a little bit more than just <li>. It includes an id and class. Well, sort of, but this is where it gets complicated. The default before_widget includes sprintf directives %1$s and %2$s, which are replaced by the id and class, respectively. The id is generated by sanitizing the widget name (which is why you should name your widget carefully: you don’t want duplicate id’s in one HTML document!) and the class is generated from the widget’s callback. This ensures all Text and RSS widgets, for instance, have unique id’s and similar classnames. Additionally, there is a “widget” class for each widget. |
||
| − | |||
| − | So, if you want your theme to be most flexible you should use this instead of |
||
| − | the empty strings shown above: |
||
| − | |||
| − | <pre> |
||
| − | 'before_widget' => '<div id="%1$s" class="widget %2$s">', |
||
| − | 'after_widget' => '</div>', |
||
| − | </pre> |
||
| − | |||
| − | Now your HTML markup is REALLY taken care of. |
||
| − | |||
| − | ===The HTML looks good but the page looks awful in the browser!=== |
||
| − | |||
| − | Yeah, we knew that would happen. Your theme was probably written before widgets were born so the author didn’t know she should make the stylesheet flexible enough to handle new markup in the sidebar. If you know some CSS, you should be able to handle the problems with a few new rules at the end of your stylesheet. Look in your blog’s markup for the selectors (id and/or class) belonging to each widget you want to style. |
||
| − | |||
| − | If CSS is a mystery to you, we regret that we can’t offer you any help. As much as we’d like to help you with this, it just isn’t possible due to the wild variations of themes. Contact your theme’s author and ask her to update the theme for better compatibility with widgets. |
||
| − | |||
| − | ===The search widget is still ugly. I want my theme’s original search box as a widget.=== |
||
| − | |||
| − | The widgets are CSS-selectable so that you can style them very specifically. However, the markup might not be to your liking. Many themes will look better if they supply their own widgets to replace some of the basic widgets, such as Search and Meta. It’s usually best to copy the existing markup from sidebar.php into a new widget in functions.php, then use the registration functions to replace the standard widget with the custom one. |
||
| − | |||
| − | You can do this with any part of the theme’s sidebar, or all of them. Here’s an example of how to do this: |
||
| − | |||
| − | <pre> |
||
| − | function widget_mytheme_search() { |
||
| − | ?> |
||
| − | << PASTE YOUR SEARCH FORM HERE >> |
||
| − | <?php |
||
| − | } |
||
| − | if ( function_exists('register_sidebar_widget') ) |
||
| − | register_sidebar_widget(__('Search'), 'widget_mytheme_search'); |
||
| − | </pre> |
||
| + | {{Sidebar Tags}} |
||
| − | ==I have a theme with more than one sidebar. How do I make them all dynamic?== |
||
| + | {{Widget Tags}} |
||
| − | Oh, that’s easy. Instead of register_sidebar() you should use register_sidebars(n) where n is the number of sidebars. Then place the appropriate number in the dynamic_sidebar() function, starting with 1. (There are several other ways to use these function. See the [[Plugins/WordPress_Widgets_Api|API]]). |
||
| + | [[Category:UI Link]] |
||
| − | You can even give your sidebars names rather than numbers, which lets you maintain a different set of saved sidebars for each theme. But if you need to know so much about the plugin, why aren’t you reading the API? |
||
Languages: English • Français • Themes 日本語 Português do Brasil • 中文(简体) • Македонски • (Add your language)
Widgetizing is a pseudo word that describes the process of implementing Widgets and Widget Areas into your Theme.
The following should be added to your Theme's functions.php file:
<?php
/**
* Register our sidebars and widgetized areas.
*
*/
function arphabet_widgets_init() {
register_sidebar( array(
'name' => 'Home right sidebar',
'id' => 'home_right_1',
'before_widget' => '<div>',
'after_widget' => '</div>',
'before_title' => '<h2 class="rounded">',
'after_title' => '</h2>',
) );
}
add_action( 'widgets_init', 'arphabet_widgets_init' );
?>
You can display your new widget area by:
Here's some example code that is a common way to add your new widget area to a parent or child theme:
<?php if ( is_active_sidebar( 'home_right_1' ) ) : ?> <div id="primary-sidebar" class="primary-sidebar widget-area" role="complementary"> <?php dynamic_sidebar( 'home_right_1' ); ?> </div><!-- #primary-sidebar --> <?php endif; ?>
The above code can be added to your sidebar.php file. It checks to see if the widget area is populated (i.e. is active) and then displays the contents of the widget if active.
This is the function which outputs the widget:
<?php dynamic_sidebar( 'home_right_1' ); ?>
The code above will display the widget registered with an ID value of 'home_right_1'. When displaying a widget on your site, remember to replace 'home_right_1' with the ID value you specified when you registered your widget.
For more information, please refer to the Widgets API to learn how to, programmatically, display Widgets and Widget Areas.
If you're not a programmer, you should refer to the WordPress Widgets page.
You can use WordPress or theme specific hooks to display new widget areas in your theme directly from your parent or child themes functions file.
function wpsites_before_post_widget( $content ) {
if ( is_singular( array( 'post', 'page' ) ) && is_active_sidebar( 'before-post' ) && is_main_query() ) {
dynamic_sidebar('before-post');
}
return $content;
}
add_filter( 'the_content', 'wpsites_before_post_widget' );
The above code displays a new widget area before all single posts and pages in any theme using the_content [1] filter however it is suggested you use theme specific hooks if your theme includes them.
Note: You will also need to register a new widget area using the same ID as what you use in the dynamic sidebar which in this example is before-post.
register_sidebar( array( 'id' => 'before-post', 'name' => 'Before Posts Widget', 'description' => __( 'Your Widget Description.', 'text_domain' ), ) );
Sidebars: is_active_sidebar(), is_dynamic_sidebar(), dynamic_sidebar(), register_sidebars(), register_sidebar(), unregister_sidebar(), wp_register_sidebar_widget(), wp_unregister_sidebar_widget(), wp_get_sidebars_widgets(), wp_set_sidebars_widgets()
Widgets: is_active_widget(), the_widget(), register_widget(), unregister_widget(), wp_register_widget_control(), wp_unregister_widget_control(), wp_convert_widget_settings(), wp_get_widget_defaults(), wp_widget_description()