Marquex on the game

I'm Ok, I'm not dead or anything, I've just moved to a new blog where I've been working in for some time.

There you will find all the info about custom sidebars and entry widgets you need, some WordPress hints, the ultimate CSS and HTML tricks and original Opencms tutorials.

Continue following me at javimarque web development articles blog.

This post makes reference to an outdated version of the Custom Sidebars plugin. If you are looking for the current version visit the custom sidebars new site.

It's been a while since the last time I upgraded the plugin, and in this time I've been listening to the users that needed some functionalities to have the sidebars they wanted, and they showed me that the plugin was useful but yet incomplete. So in this version i've tried to add all those features, so this is a big update.

Update or get it on the wordpress repository

Sidebars by category

One of the most wanted feature was the sidebars by categories. People needed all the posts that belong to a category to have the same sidebar. That's logical but it's much easier to say it than to implement it, because a post can have several categories, and some categories are children of others, so what category sidebar should a post use?

Imagine that a post belongs to the following hierarchy of categories:

Cat level 1
- Cat level 2
-- Cat level 3
Other Cat 1
- Other Cat 2

The post belongs to 5 categories. Custom Sidebars plugin will replace the post sidebar by the bar defined for the highest level category and if there are custom sidebars defined for two same-level categories, the sidebar shown  will be the one of the category whose name is the first ordered alphabetically.

So, in the example above, if all the categories have a defined custom sidebar, the post will show the Cat level 3 sidebar. In case that Cat level 3 didn't have a sidebar defined, the Cat level 2 would be shown, because "Cat level 2" has priority over "Other Cat 2", since it's name is the first when both are ordered alphabetically.

The priority queue for the categories sidebars in the example would be:

Cat level 3 > Cat level 2 > Other Cat 2 > Cat Level 1 > Other Cat 1

More default sidebars

The plugin also allows now to define a sidebar for the list of posts of a category and for the list of post of a post-type.

Other user necessity was assigning a sidebar for the main blog page. In this case I still recomend to configure the default theme sidebar for the blog, so no replacement is needed and everything load faster. But if you can't or you don't want to do so, there is the posibility to define custom sidebars for the main blog page in this version of the plugin.

There are more pages which will be able to have sidebars replacements so on, they are the list of post by a tag page, and a single author page.

Sidebars advanced edition

The edition of sidebars was a feature that i didn't want to include in the plugin, because there are some too much technical parameters for the sidebars that I think a normal WP user shouldn't know about. But it's true that for some developers it is useful modify the before_widget, after_widget, before_title and after_title sidebar properties. Don't you know what I'm writing about?? You are right, who cares about that crap? But if you still care, there is a great article about WP Sidebars in Justin Tadlock Blog.

So Custom Sidebars plugin now allows to edit sidebars properties, to do it, just create a custom sidebar as usual and in the sidebar list you will have a link to edit them. If you don't edit before/after properties, your sidebars will have the theme default design, the same way the plugin was working so far.

Custom sidebars translations

Nobody have tried to translate the plugin yet, c'mon people!!! It would be nice to have the plugin translated in your language, not just Spanish and my English (Even the english translation made by me sucks!).

I hope you enjoy the plugin!

(download)

Click here to download:

wp-custom-sidebars-v0-6-released-hjIxjyEDcIkquDDbqBAq.zip (237 KB)

When creating a WordPress widgets, it's very easy to start from the example which come with the Widget API documentation:

 class My_Widget extends WP_Widget {
 function My_Widget() {
 // widget actual processes
 }
 
 function form($instance) {
 // outputs the options form on admin
 }
 
 function update($new_instance, $old_instance) {
 // processes widget options to be saved
 }
 
 function widget($args, $instance) {
 // outputs the content of the widget
 }
 } 

The formatting info of the front-end will be placed in the widget function, this function has two parameters: 

* $instance, the options for the current instance of the plugin (all the info stored in the backend)

* $args, what the hell is this parameter?? No info anywhere. Let's disect it:

$args is an array that contains information about the sidebar where the widget will be displayed. Its array elements are:

• $args['name']: The 'human' sidebar's name.
• $args['id']: The id of the sidebar. Using this id you can access to all the widgets in the bar using the global variable $_wp_sidebars_widgets. Example: $_wp_sidebars_widgets[$args['id']].

You can use this element to display the widget in different ways depending on the bar it belongs to.

• $args['description']: The description of the sidebar.
• $args['before_widget'] & $args['before_widget']: When a sidebar is registered, some HTML code is defined for the elements in it. An example of 'before_widget' code may be '<li>' and 'after_widget' could be '</li>'. This way the sidebar would be a list of elements (widgets). To agree with the rest of the design of the sidebar, and don't break it, our widget method should be:

 function widget($args, $instance) {
 echo $args['before_widget'];
 
 // outputs the content of the widget
 
 echo $args['after_widget'];
 } 

• $args['before_title'] and $args['before_title']: This is a similar case than the before widget one. The sidebar has a default code which encapsulates the titles of its widgets, so if you want to follow the sidebar style completely, your widget function should look like:

 function widget($args, $instance) {
 echo $args['before_widget'];
 
 echo $args['before_title'], 'This is My Marvellous Widget Title', $args['after_title'];
 
 // outputs the content of the widget
 
 echo $args['after_widget'];
 } 

• $args['widget_id']: The widget id attribute. Every widget instance has its own id.
• $args['widget_name']: The 'human' name of the widget, this is common for all the instances of the widget.

• Security Improved by WP-Nonces
• Documentation now shows screenshots
• New error messages.

You can download the plugin from here:

http://wordpress.org/extend/plugins/custom-sidebars/

I'm creating my first WordPress Widget at the moment, and the first thing i've done it a little research about the widgets. Everywhrere i've found the same, for WP2.8+ there is a new Widget API, and it is necessary to extend the class WP_Widget, and implements the methods below:

class My_Widget extends WP_Widget {


 


function My_Widget() {


// widget actual processes


}


function form($instance) {


// outputs the options form on admin


}


function update($new_instance, $old_instance) {


// processes widget options to be saved


}


function widget($args, $instance) {


// outputs the content of the widget


}


}


 

Easy isn't it? But when I start implementing my widget I could not get the info from the form I had made to set the plugin's options. In the update function i can't retrieve the form info from $_POST or $_GET, and I only have the empty $new_instance and $old_instance variables.

That happened to me because i did not use the WP_Widget method get_field_name. There is a subtle reference to it in the Widget API documentation, but it doesn't describe how important it is.

If we want a input field named title in our widget, we must declare it this way:

<input name="<?php echo $this->get_field_name('title') ?>" type="text" />

If so, we will recieve the value in the update function using

$new_instance['title']

For saving the information recieved we will have the help of WordPress, it will save automatically the instance returned by the update function. For example:

function update($new_instance, $old_instance) {


// processes widget options to be saved


$myinstance = $old_instance;


$myinstance['title'] = esc_attr($new_instance['title']);


return $myinstance;


}

After the update, we can access to the $instance['title'] value in all the other methods of the widget.

I am impressed how fast is moving the WP world. I like the new version of WP (version 3) because of its new custom post types, so i decided i will publish gratefully some of my plugins to the public and the first one is available from yesterday, Custom Sidebars.

I asked the wordpress stuff for the space in the plugin repository on sunday and on monday the send me the information to access. At the moment, in less than 20 hours almost 200 people have already downloaded it.

It is a pleasure develop this way, and i'm sure i will get the feedback from the users to build great plugins. I offer this space to help anybody who had problems with the plugin.

Cheers

Hello Posterous!!

I needed you and here you are!