=== Promotion Slider ===

Contributors: woodent
Donate link: http://www.orderofbusiness.net/payments/
Tags: slideshow, promotions, slider, javascript slider, jquery slider, carousel, featured content, news, gallery, banners, image rotation, images, rotate, auto, autoplay, shortcode, slide, ad, ad gallery, advertisement, ads, media, pictures, custom post types
Requires at least: 3.0
Tested up to: 3.0.1
Stable Tag: 2.2.2

Promotion Slider is a jQuery slideshow populated by the promotions you enter into the WordPress admin area.


== Description ==

Promotion Slider allows you to easily create promotions in the WordPress admin area; complete with a title, content and image.  The image displays in the slider, and when a user clicks on the image, they are taken to the full promotion page.  Designed with SEO in mind, this slider can be integrated anywhere on your blog or website.

This plugin features: 

* Easy creation and management of promotions within the WordPress admin.
* Automatic inclusion of images attached to promotions.
* Creation of unique pages with a unique URL for each promotion.
* SEO friendly jQuery animation that can be viewed on most mobile devices.
* Slider navigation that makes it easy for users to find and click on the promotion of their choice.
* Supports the option to link to external URLs instead of promotion pages from the slider.
* Ability to display only a certain post type or limit to posts from a certain category.
* Customizable time delay and the ability to disable automatic slide advancement.
* Built-in support for displaying a title and/or excerpt for each post or promotion.
* The ability to display multiple sliders without conflicts.
* Works with any custom post type.
* Plenty of hooks available to advanced WordPress users.

This plugin is provided as-is, but [paid support for this plugin is available](http://www.orderofbusiness.net/services/web-design-development/).

If you have feature requests for this plugin, [please let us know](http://www.orderofbusiness.net/contact-us/)!


== Installation ==

1. Upload the `promotion-slider` folder to the `/wp-content/plugins/` directory.
2. Go to the 'Plugins' page of your WordPress administration area and activate the plugin.
3. Use the shortcode `[promoslider]` in the content area of a page or post where you want the image slider to appear.
4. Create your promotions by clicking on 'Promotions' in your administration menu and selecting 'Add New'.  *The slider uses ONLY the featured image attached to any given promotion.*
5. Visit the 'Permalinks' page under 'Settings' in your administration menu.  No need to do anything, just visit the page.  This will ensure that you can visit the promotion pages when you click on an image in the slider. *If you skip this step, your promotion pages will return a 'Page not found' error!*

== Frequently Asked Questions ==

= How do I insert the Promotion Slider? =

You can insert the Promotion Slider by pasting the shortcode `[promoslider]` into the content area of a page or post.  Be sure to use the HTML editor when inserting shortcodes.  Also, be aware that if you don't have any published promotions, the slider will not appear.  To customize your slider, there are optional attributes that can be used with the shortcode.

= What are the optional attributes that can be used with the shortcode? = 

There are several attributes that are supported by the `[promoslider]` shortcode:

1. **id** - You can assign a promotion slider its own HTML id attribute so you can easily customize the CSS for a particular instance of the slider.  Example: `[promoslider id="my_id"]`
2. **post_type** - You can display any post type in the slider, including custom post types.  Most users will probably just use the built-in 'promotion' post type and the default WordPress 'post' post type.  The 'promotion' post type is default, so you would only need to specify this if you want to display your standard WordPress blog posts.  Example: `[promoslider post_type="post"]`
3. **category** - You can choose to display only posts from a particular category, regardless of which post type you are pulling from.  Please note that if a category doesn't exist, all posts will show in the slider.  If there are no posts in an existing category, the slider will not show at all when using this attribute.  Example: `[promoslider category="my_category"]`

You can combine all of these attributes together as needed.  Example: `[promoslider id="my_id" post_type="post" category="my_catagory"]`

= How do I create promotions? =

Promotions can be created in the WordPress administration area by clicking on 'Promotions' in the navigation and then selecting 'Add New'.  

You will be able to provide a title, content, category, and optonal URL, as well as a featured image.  By default, the featured image will be used in the slider, and the title and content that you create will display ONLY on the promotion page when a user clicks through from the slider image.  You can enable the display of other content on the slider if desired. For detailed instructions, see 'How can I enable the display of additional content in the slider?'. 

Images can be placed within the content area of the promotion without affecting the slider, and featured images will not display on the promotion pages. If you set the optional URL, the slider will link to that URL rather than the promotion page. 

You can optionally create categories for your promotions by clicking on 'Promotions' in the navigation area and then selecting 'Categories'.  You can create sliders that will only display certain categories if you wish.

= What are the dimensions of the slider?  How can I change them? =

The height of the slider is 235px by default and the width varies to adapt to your theme.  

If you desire to set the dimensions to something more concrete, you can do so by copying the following line into your theme's style.css file and then editing the dimensions as needed:

>  `div.promo_slider { height:235px; width:635px; }`

If you want the width to automatically adapt to your theme's layout, just delete `width:635px;` from the line above.

If you have multiple sliders and wish to have them different sizes, you will need to use the id attribute available in the shortcode.  Then, you can use that unique id to define css for each instance of the slider.  Simply replace the 'div.promo_slider' in the line of code above with the # symbol followed by the unique id.

= How can I enable the display of additional content in the slider? =

To enable the display of the title in the promotion slider, copy the following line into your theme's functions.php file: 

>  `add_action('promoslider_content', 'promoslider_display_title');`

To enable the display of the excerpt in the promotion slider, copy the following line into your theme's functions.php file: 

>  `add_action('promoslider_content', 'promoslider_display_excerpt');`

Enabling the excerpt, without disabling or moving the slider navigation, will cause some overlap of the two elements.  If you would like to disable the slider navigation, copy the following line to your theme's functions.php file: 

>  `remove_action('promoslider_nav', 'promoslider_display_nav');`

Note: By using the 'id' attribute in the shortcode, you can assign all instances of the promotion slider a unique id.  This will allow you to customize the look and feel of individual sliders by editing the css in your theme's stylesheet.

More advanced users might want to display a title and extra content on one slider, but not on another.  This can be done by using the id attribute available in the shortcode and using the action hooks to add custom functions.  Here is an example:

>	`// Insert the [promoslider id="my_unique_id"] shortcode on your site.
>	// Create your own function for conditionally displaying the title
>	function my_slider_content($values){
>	  extract($values); // Values currently provided are $title, $excerpt, $image, $destination_url , $target, $id
>	  // Display title and content only for one slider instance
>	  if( $id == 'my_unique_id' ){
>		add_action('promoslider_content', 'promoslider_display_title', 9);
>		add_action('promoslider_content', 'promoslider_extra_content');
>	  }
>	}
>	// Add your function to the promoslider_content hook
>	add_action('promoslider_content', 'my_slider_content');
>	// Create your own function for inserting extra content
>	function promoslider_extra_content(){
>	  echo '<< INSERT CUSTOM CONTENT HERE >>';
>	}`

= What if I don't want to display an image on the slider? =

Ideally, you can just remove any featured image that you may have uploaded.  However, you can also place the following in your theme's functions.php file:

>  `remove_action('promoslider_content', 'promoslider_display_image');`

= How can I edit my theme's stylesheet or functions file? =

The stylesheet is located here: `/wp-content/themes/[your theme's folder]/style.css`.  

The functions.php file is located here: `/wp-content/themes/[your theme's folder]/functions.php`

You can edit either of these files using the built in file editor in WordPress or via FTP.

= How can I change the time delay between slides? =

Just click on 'Promotions' in the WordPress admin area and select the 'Slider Options' page.  You can change the time delay from here.

= What if I don't want the slides to automatically advance? =

If you would rather not have the slides advance automatically, users can still browse through the promotions in the slider with the slider navigation.  To disable the automatic advancement of slides, just click on 'Promotions' in the WordPress admin area and select the 'Slider Options' page.  You can disable automatic slide advancement from here.

= What if I want to show the slider in my sidebar? =

First, you will need to enable the use of shortcodes in text widgets by adding the following line to your functions.php file:

>`add_filter('widget_text', 'do_shortcode');`

Next, all you need to do is add a text widget to your sidebar and include the shortcode as described earlier.  Most likely, you will need to adust the width and/or height of the slider in your sidebar by changing the css in your theme's stylesheet.

= What if I don't want to use the shortcode?  Can I hardcode the slider into my theme? =

Hardcoding the slider into your theme is just as simple as using the shortcode.  All you do is insert the following line into your theme where you want the slider to appear:

>`<?php do_shortcode('[promoslider]') ?>`

If you want to use any of the shortcode attributes when hardcoding your theme, you may do so like this:

>`<?php do_shortcode('[promoslider id="my_id" post_type="post" category="my_category"]'); ?>`

= Can I control the order in which the slides appear? =

We provide a filter which allows you to customize the get_posts() query.  You can use any of the [documented parameters](http://codex.wordpress.org/Template_Tags/get_posts#Parameters:_WordPress_2.6.2B) in your query.  Here is an example of how you could control the order:

>	`// Create your custom function for changing the order of the promotions
>	function change_promotion_order($query, $id){ // The $query is what we will alter here, the $id is available if you want to apply the changes only to a slider with a unique id
>	  $query['orderby'] = 'title';
>	  $query['order'] = 'ASC';
>	  return $query
>	}
>	// Add the filter so it gets applied to the slider
>	add_filter('promoslider_query', 'change_promotion_order');`

== Screenshots ==

1. An example of the Promotion Slider with a default installation.
2. An example of the Promotion Slider with the title display enabled.  This slider is using the default styling for the title.
3. An example of the Promotion Slider with some minor customizations.  By following the instructions in the FAQ section, you can make your customizations upgrade-proof.

== Changelog ==

= 2.2.2 =
* Replaced bad function call apply_filter() with apply_filters()

= 2.2.1 = 
* Fixed issue where slider would not advance unless the disable auto advancement option was set.
* Fixed issue where slider would not progress because time delay option was not set.

= 2.2.0 =
* Added an options page where users can change the time delay and disable the automatic slide advancement.
* Reset the time delay when a user clicks on a navigation link in the slider.
* Fixed issue where the back button on the slider nav would perform the action for all sliders on the page.
* Fixed the issue where forward and back buttons on the slider nav would progress slides in the wrong direction.
* Added some basic CSS to highlight which image the user is viewing in the slider nav.
* Added support for all post types, including custom post types.
* Added a query filter to allow advanced users to customize the slider even more.
* Added the 'promoslider_add_meta_to_save' filter for easier saving of promotion meta; for users who may add their own meta boxes.
* Changed the functionality so that if a requested category does not exist, all promotions/posts are shown.
* Changed the way values are passed to the 'promoslider_content' action.  Values are now passed as an associative array for ease of use and flexibility in future updates.
* Added a 'Support this Plugin' box to the options page.

= 2.1.0 = 
* Added automatic flushing of rewrite rules via 'register_activation_hook' (still needs work)
* Replaced content of slider panels with an action hook.
* Created actions that allow users to easily add or remove the title, excerpt or image
* Replaced slider navigation with an action hook.
* Created an action so users can easily add or remove the slider navigation.
* Updated CSS to include default styling for the title and excerpt.
* Simplified instructions for hardcoding the slider in a theme.
* Updated processing of post meta so that empty meta box values are removed from the postmeta table.
* Updated the readme.txt file to reflect changes relating to the action hooks.

= 2.0.0 =
* Added ability to use external links with slider promotions.
* Added a custom taxonomy for the promotion post type.
* Added ability to use the promotion slider with the WordPress default post type.
* Added ability to show only promotions or posts from a particular category.
* Added attributes to shortcode.
* Added ability to display multiple instances of the promotion slider on a single page.
* Added ability to easily change the time delay and disable automatic slide advancement.
* Provided detailed instructions on how to display the title and/or excerpt in the slider.

= 1.0.0 =
* Promotion Slider is now available for download!

== Upgrade Notice ==

= 2.2.2 = 
Replaced a bad function call.

= 2.2.1 =
Fixed a couple of bugs that prevented slider from working properly.

= 2.2.0 = 
Users can now easily set the time delay and disable the automatic advancement of slides.  A lot of advanced functionality has been added allowing power users to infinitely customize their sliders.

= 2.1.0 = 
The latest version makes it very simple to customize the slider to display only the content you want to appear.  You can easily add or remove the image, title, excerpt or navigation for the Promotion Slider.

= 2.0.0 =
The latest version allows you to specify link targets instead of having the promotions always link to promotion pages.  You can display promotions or WordPress's default posts in the slider and can limit posts by category.  Support added for the display of title and/or excerpt in the slider.