# Spud Banners

Spud Banners is an engine for creating and managing rotating banner sets, designed for use with [Spud][spud].

## Installation/Usage

1. In your Gemfile add the following

		gem 'spud_banners'

2. Run bundle install
3. Copy in database migrations to your new rails project

		bundle exec rake railties:install:migrations
		rake db:migrate

4. Run a rails server instance and point your browser to /spud/admin

## Configuration

Spud Banners accepts the following configuration options:

	Spud::Banners.configure do |config|
		config.paperclip_storage = :filesystem #use :s3 to use s3 storage (aws gem required)
		config.s3_credentials = "#{Rails.root}/config/s3.yml"
		config.storage_path = ":rails_root/public/system/spud_banners/:id/:style/:basename.:extension"
		config.storage_url = "/system/spud_banners/:id/:style/:basename.:extension"
	end

## Creating a Banner Set

Banner Sets are created in the Spud admin. When creating a Set, you have the following options:

- **Name:** The unique identifier used to render this set
- **Width:** Maximum width of uploaded banners
- **Height:** Maximum height of uploaded banners
- **Cropped:** Whether or not banners should be cropped to fit into the above Width/Height constraints

## Managing Banners

Once a Set has been created, you can begin adding banners to it. Banners contain optional `link_to`, `link_target`, `title`, and `alt` options. Banners are also sortable via drag-and-drop.

## View Helpers

A number of view helpers are provided for displaying banners in your templates. 

`spud_banners_for_set(set_or_identifier)`

Accepts the banner set name as a String or Symbol and returns an html template. Optionally takes a block argument for rendering custom html. 

`spud_banner_tag(banner)`

Accepts a banner model object and returns a banner image wrapped in a link tag. Link tag is omitted if the `link_to` property of the banner is blank.

`spud_banner_image_tag(banner)`

Accepts a banner model and returns only the image tag, no link. 

## Examples

Displaying banners using the standard helper.

	<div id="banners">
		<%= spud_banners_for_set(:promotions) %>
	</div>

Displaying banners using the helper, with a block for custom html.

	<ul id="slides">
		<% spud_banners_for_set(:promotions) do |banner| %>
			<li class="custom_slide">
				<%= spud_banner_tag(banner) %>
			</li>
		<% end %>
	</ul>

Displaying banners using the helper, with a block for even more custom html.

	<ul id="slides">
		<% spud_banners_for_set(:promotions) do |banner| %>
			<li class="custom_slide">
				<h3><%= link_to banner.link_to, banner.title, :target => banner.link_target %></h3>
				<%= image_tag(banner.banner.url(:banner), :alt => banner.alt, :title => banner.title) %>
			</li>
		<% end %>
	</ul>

## Liquid

Spud Banners comes with its own custom [Liquid][liquid] tag. For now the liquid tag only supports rendering the standard html as generated by the `spud_banners_for_set`. Will provide support more advanced options in the future. 

Usage:

	<%= raw Liquid::Template.parse("{% spud_banner_set Promotions %}").render %>

## Slideshows

Spud Banners does not provide a built-in slideshow animation library. Instead, we make it easy for you to integrate into any number of popular JavaScript slideshow plugins available on the web, or even to write your own from scratch. 

Below is an example of integration with [SlidesJs][slidesjs], a jQuery plugin.

	<style type="text/css" media="screen">
		.spud_banner_set {
			width: 600px;
			height: 200px;
		}
		.spud_banner_set_banner {
			width: 600px;
			height: 200px;
			display: block;
		}
	</style>
	<div id="banners">
		<%= spud_banners_for_set(:promotions) %>
	</div>
	<script src="/slides.jquery.js" type="text/javascript"></script>
	<script>
		$(document).ready(function(){
			$("#banners").slides({
				play: 5000,
				container: 'spud_banner_set'
			});
		});
	</script>

[spud]:https://github.com/davydotcom/spud_core_admin
[slidesjs]:http://www.slidesjs.com
[liquid]:https://github.com/Shopify/liquid