<?php
// Create
add_role('privatereader', 'Private Reader', array(
            'read' => 1,
            'level_0' => 1,
            'read_private_pages' => 1,
            'read_private_posts' => 1,
        ));
?>

The add_role function requires three arguments: the role’s name (for internal use), the display name, and an array of the role’s capabilities. (See the Codex page on Roles and Capabilities for a complete list of the capabilities in WordPress.) Here, we’ve given our role the same two capabilities a subscriber starts out with, ‘read’ and ‘level_0.’ (The level_n capabilities exist for backward compatibility with very early versions of WordPress, which used a 1-10 scale instead of named roles.) Then we’ve added the two roles relating to private content.

If you create or edit a user now, you should see the new Private Reader role as an option.

If we wanted to modify our new role, we’d use the same code we used to change capabilities before, but but we’d change the get_role function’s argument to our new role’s internal name.

<?php
// remove ability to read private pages
$PrivateRole = get_role('privatereader');
$PrivateRole -> remove_cap('read_private_pages');
?>

Need to remove the role? That’s easy:

<?php
remove_role('privatereader');
?>

That’s nice, but now what?

In this example, it makes sense to create a new role only if you wanted to keep the subscriber role as-is; otherwise; it was simpler to just modify the subscriber role.

When would it make sense to create a new role?

Let’s imagine a new scenario. You’re building a large site, and you, the programmer, are sharing responsibilities with a graphic designer. You want to give your designer complete control over the content and theme design, but you don’t want him editing other users, adding plugins, or importing content from other sites.

We could create a whole new role and enumerate every capability we want the designer to have, as we did above for the private reader, but this role will be similar to the administrator’s, and that’s a lot of capabilities! Instead, we’ll duplicate the admin role and remove the eight or nine capabilities we don’t want the designer to have.

Creating a designer role

<?php
$admin = get_role('administrator');

// get_role returns an object.
// We want the capabilities piece, which is an array.
$caps = $admin->capabilities;

// Remove the stuff we don't want in the new role.
unset($caps['activate_plugins']);
unset($caps['edit_plugins']);
unset($caps['update_plugins']);
unset($caps['delete_plugins']);
unset($caps['install_plugins']);
unset($caps['edit_users']);
unset($caps['delete_users']);
unset($caps['create_users']);
unset($caps['import']);

// Add the new role.
add_role('designer', 'Designer', $caps);
?>

And that’s that!

Note that WordPress’s admin menus and screens don’t always behave exactly as you’d expect. In this case, even though we’ve removed all capabilities involving plugins, the designer will still be able to access the Plugins → Add New screen, search for plugins, and install them — but s/he won’t be able to activate the new plugin, or see the list of installed plugins.

The user/role structure is due for an overhaul in version 3.1; hopefully these menu glitches will be addressed then.

Managing Roles with Plugins

If you’d rather click tickyboxes than write all this code, Justin Tadlock’s Members plugin provides an elegant user interface for everything I’ve shown here. It also has some extra features related to private content.

How rare is snow here? I’d never seen this glyph on the weather widget, let’s put it that way.

User Descriptions

The biography field on the user profile page accepts a limited number of HTML tags — the same ones allowed in comments. If you need to create richer biographies for your users, you can preserve HTML by adding the following to your functions.php file:

remove_filter( 'pre_user_description', 'wp_filter_kses' );

Category, Tag, and Taxonomy Descriptions

The taxonomy description fields also prevent you from entering some HTML. To keep it, add this to functions.php:

remove_filter( 'pre_term_description', 'wp_filter_kses' );
remove_filter( 'term_description', 'wp_kses_data' );

Excerpts

As I’ve mentioned before, there is no easy way to filter the excerpt function to preserve HTML; the PHP strip_tags() function is part of the_excerpt(), and there’s no getting around it without recreating the function altogether¹. That’s exactly what the Advanced Excerpt plugin does. Download and activate it, and your HTML stays right where you put it.

¹ If you’d like to see the_excerpt changed to allow HTML, add a comment on this bug report.

So, I just imported a bunch of stuff, and I’m now cleaning it up (the code from those posts really doesn’t play nicely with Textile, which might force me to abandon it at last, as much as I love it), and in a little while I’ll shut down the other site and redirect everything here.

Sorry about the mess.

Text Widgets

It’s easy to make shortcodes work in text widgets. Just add the following to your functions.php file:

add_filter( 'widget_text', 'shortcode_unautop');
add_filter( 'widget_text', 'do_shortcode');

The second line is the one that makes the shortcodes work, but you’ll want to include both. If you check “add paragraphs automatically” on the widget, WordPress will apply the autop filter — the one that turns your line breaks into paragraph and break tags. If a shortcode is on its own line, it would normally get wrapped in a paragraph tag. The first line prevents that from happening.

Template Files

You can use shortcodes right in your theme! Use the do_shortcode() function, where the argument is a string that contains a shortcode.

For example, to print the output of the shortcode [foo] in a theme, add this to the file:

<?php do_shortcode('[foo]'); ?>

The do_shortcode() function accepts any text as its input. If the string contains a shortcode, that code will get processed. So, for example, you could manually process your post content for shortcodes like this:

<?php
$content = get_the_content();
echo do_shortcode($content);
?>

Comments

Do you trust your commenters enough to allow them to use shortcodes? This goes into functions.php:

add_filter( 'comment_text', 'shortcode_unautop');
add_filter( 'comment_text', 'do_shortcode' );

Excerpts

To enable shortcodes in excerpts, add these lines to your functions.php file:

add_filter( 'the_excerpt', 'shortcode_unautop');
add_filter( 'the_excerpt', 'do_shortcode');

User Descriptions

There is no filter (as far as I know) for the user description, so in order to display the description with shortcodes, you’ll need to fetch the description string, then pass it to the do_shortcode() function. This would go into your theme file:

<?php
// $user_id = 3;
$userdata = get_userdata($user_id);
echo do_shortcode($userdata->description);
?>

Category, Tag, and Taxonomy Descriptions

These descriptions can be filtered, so the code for your functions.php file is simple:

add_filter( 'term_description', 'shortcode_unautop');
add_filter( 'term_description', 'do_shortcode' );

nolove,
Women