Spud Banners

Spud Banners is an engine for creating and managing rotating banner sets, designed for use with 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, options)

Accepts the banner set name as a String or Symbol and returns an html template. Options hash accepts a :limit parameter for limiting the number of banners returned. This helper also accepts 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 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, 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>