To reach more readers the following post is in english (Um mehr Leser zu erreichen, ist der folgende Beitrag in englisch).
What does this plugin do?
The Post Restrictions plugin shows private posts to other users if at least one of the user’s capabilities meets one of the post’s capabilities.
Make it quick. Where can I download it?
Download Post Restrictions 1.1 here!
How do I install the plugin?
As with the most WordPress plugins, installation is easy:
- Download the Post Restrictions plugin and extract it to your WordPress plugins directory.
- Activate the plugin in your WordPress admin panel.
- Ready. It couldn’t be easier. The rest is self-explanatory. 😉
Why is there so much text below?
Because I hate cool plugins that are badly documented. Even the smallest piece of code needs some documentation. The following text is (hopefully) pretty exhaustive and structured as FAQ. Feel free to skip the questions you are not interested in.
- I want to test it. What do I need?
- How do I update the plugin from a previous version?
- What is the difference to other similar plugins?
- How do I restrict my posts to be read only by specific users?
- What is the restriction status?
- What is protected on a protected post?
- How are feeds protected?
- How can I assign capabilities to my registered users?
- What happens to my protected posts when I deactivate the plugin?
- How do I migrate from one of the other restriction plugins?
- Which template tags are provided?
- What other functions can I use for advanced templates?
- Are there any known issues about this plugin?
- Which versions of the plugin exist and what are their features?
I want to test it. What do I need?
You need the following software to be installed on your webserver:
- PHP 4.2 or higher
- WordPress 2.0 or higher
- the Post Restrictions plugin 😉
How do I update the plugin from a previous version?
It’s so easy. Just replace your old post_restrictions.php file with the one from the current version archive. That’s it.
What is the difference to other similar plugins?
The Post Levels plugin by Filipe Fortes provides almost the same functionality. A big bunch of this work is taken from his plugin. The difference is that Post Restrictions is using the roles/capabilities model of WordPress 2.0 to permit access to posts where as Post Levels does its own permission management.
The ViewLevel plugin by Alex Tingle isn’t yet ported to WordPress 2.0 as far as I know and so has no restrictions based on roles/capabilities either. The restricted posts will become public when plugin is deactivated.
The Private Categories plugin by Greg Elin restricts complete categories from being read. The restricted posts will become public when plugin is deactivated.
How do I restrict my posts to be read only by specific users?
Your Write Post page in the WordPress admin panel now has a new box called Post Restrictions. Simply choose the capabilities a user must have to read the post and save your changes afterwards. Now a user can only read this post if he has at least one capability in common with one you have set for the post. Once you have chosen at least one capability from the Post Restrictions box, it doesn’t make a difference whether you press the ‘Save’ or ‘Publish’ button or mark your post as ‘Published’ or ‘Private’ in the Post Status box. The Post Restrictions plugin will adjust the post status in all cases to private and will protect you from accidently publishing a restricted post.
What is the restriction state?
The WordPress core system knows two restriction states for posts. They are public for posts to show up even for unregistered users on your blog and private for posts only to show up for the user who has written the post. The Post Restriction plugin introduces a third virtual state protected for posts that is defined by having a post status of private and at least one capability set in the Post Restrictions box of the Write Post page. This restriction is weaker than the private, but stronger than the public state. The restriction state will show up on the Manage Post page of the WordPress admin panel.
What is protected on a protected post?
Once a post is protected by the plugin, the post will only show up on the main page, archives, feeds, etc. while the viewer is logged in and has at least one capability in common with the capabilities set for this post. A direct access to the post, if the URL is known, will lead to an error message by the WordPress system.
How are feeds protected?
Since most RSS readers support HTTP authentication, you can add http_auth=yes to the query string of the feed, to use HTTP authentication to get protected posts data. The amount of data of the post shown in the feed is configurable on the plugin’s configuration page. You can show just the title, excerpt, or give the full content of your posts.
How can I assign capabilities to my registered users?
Assigning capabilities to roles or users is out of the scope of this plugin. Because WordPress has no built-in configuration page in the admin panel to assign roles/capabilities, you need to install one of the available role/capability manager plugins. There may be more such plugins available as shown in the following list:
- Role Manager by Owen Winkler
What happens to my protected posts when I deactivate the plugin?
If you deactivate the plugin, all your protected posts become private again and are only visible to the user who has written the post.
How do I migrate from one of the other restriction plugins?
The Post Restrictions plugin provides a configuration page in your WordPress admin panel accessible from the Plugins tab. If it recognizes that another restriction plugin was once used, it provides an additional migration dialog at the end of the configuration page. Remember that migration can not be undone by this plugin. Currently migration was tested with the following plugins:
- Post Levels version 1.0 but should work with all previous versions.
- ViewLevel2 version 2.0.0 but should work with all previous versions including ViewLevel.
- Private Categories 2 version 0.2.
Which template tags are provided?
<?php get_post_restrictions_list($display=true); ?>
- Must be called inside the loop and returns a comma separated list of capabilities set for this post.
- display: (boolean) If true, the resulting output will be printed at the position in the template where the tag is used and no value will be returned. If display is false, no output will be printed but the resulting string will be given back to the caller.
What other functions can I use for advanced templates?
get_post_restrictions()
- Must be called inside the loop and returns an array of capabilities set for this post.
is_private()
- Must be called inside the loop and returns true if the post is private.
is_protected()
- Must be called inside the loop and returns true if the post is protected.
Are there any known issues about this plugin?
Sorrowly the answer is ‘Yes’. The following issues are known:
- Private and protected posts don’t show up in the next/previous post links
- Until WordPress ticket #2183 isn’t fixed, get_post_restrictions and get_post_restrictions_list won’t work as expected
Which versions of the plugin exist and what are their features?
- 2006-01-01 Version 1.0: Plugin
- Feature: Protecting posts based on roles/capabilities.
- Feature: Support for HTTP authentication in feeds.
- 2006-01-14 Version 1.1: Plugin
- Feature: Improved migration from Post Levels.
- Feature: New migration from View Levels.
- Feature: New migration from Private Categories.
For the curious: A complete list of plugins running this blog can be found here.
For the daring: A complete list of plugins I have written for WordPress can be found here.