=== Plugin Name ===
Contributors: trick77
Tags: posts, widgets, plugin, sidebar, links, page
Requires at least: 2.7
Tested up to: 2.7
Stable tag: 1.0.2

Retrieves posts (or pages) with a certain custom field (e.g. to permanently show your most recommended posts in a widget) and displays them in a list.

== Description ==

Retrieves posts (or pages) with a certain custom field (e.g. to permanently show your **most recommended posts** in a widget) and displays them in a list. The plugin uses a custom field named *must-read* if it exists in a post or a page. If the field exists in a page or post **and** has the value *true*, the post automatically will be shown in the widget.

Once installed, you can use it with the
<code>
get_must_read('Custom Title', number of posts);
</code>
instruction in your templates **or** just add it as a **widget** to your sidebar. Of course you can specify the maximum number of posts to be shown in the widget. You can also change the widget's title to something like "Most recommended posts", "FAQ", "Read first" or whatever you like.

If you use the plugin for the first time, click "Add new custom field" to add the field name "must-read" and insert "true" in the value field of the page or post you want to be shown in the new widget. Once you want to display an additional post in the widget, just select it from the custom field drop-down box and insert "true" in the value field.

If you don't want the custom field to be named *must-read* you can also change it to something else. The custom field value always has to be named *true*.

== Installation ==

1. Upload must-read-posts.php to the /wp-content/plugins/ directory.
2. Activate "Must Read Posts" through the 'Plugins' menu in WordPress.
3. What to do now depends on how up to date your theme is:

**Modern theme with widget support**

The plugin is a widget. If your theme supports widgets, and you have installed the widget plugin, adding the plugin to the sidebar is easy: Go to the appearance menu and drag and drop the widget into the sidebar. Don't forget to save your new widget structure using the save button below.

**Old school theme without widget support**

This will require some programming in the sidebar.php file. There are many resources on the web about how to do this.
4. Mark all the posts/pages you want to show in the widget with the custom field *must-read* and the value *true* (see screenshots).

== Frequently Asked Questions ==

= I want to change the look of the list. How can I do that? =

The look of the list of posts and pages in the widget can be customized using the style.css cascading style sheet. Just add your own or the following style to your current theme's style.css file:

<code>
#must-read-posts li {
   list-style-type:square;
   margin-bottom:0.4em;
}
</code>

== Screenshots ==
1. Must Read Posts in action in widget in the right sidebar
2. Widget configuration
3. How to add the *must-read* custom field to a post or page, don't forget to add the value *true*