NOTE: I never got round to using this in production but it should be ready but will require some testing on your part.
Giveaways
Overview
Giveaways gem allows you to create giveaway contests where entrants provide you thier email address to enter. The most common reason to run such contests is for marketing purposes such as building your email list.
To encourage entrants to spread the word of the contest - something they normally would rather avoid to increase their own chances - the gem provides them with their own referall link. For every new entrant they refer they are rewarded extra chances to win the prize.
With this gem you can
- run multiple contests at the same time
- set how many winners there are in a contest
- open and close contests at specifice dates and times
- require entrants to accept your rules and confirm their email addresses
- set how many extra chances an entrant is rewarded per referall
- download all entrants as CSV
- randonly draw winners
- use default stylings or roll your own
Getting setup
Add the gem to your gemfile
# Gemfile
gem 'giveaways'
bundle install
rails g giveaways:install
The last command will do a number of things such as create an initializer with configuration settings; copy essential migrations and migrate your database and mount the giveaways engine at /giveaways
in your routes file.
You can customize the defined path to your contests by modifying the placeholder generated by the install command.
Rails.application.routes.draw do
# ...
mount Giveaways::Engine, :at => "/giveaways" # you can change this
# ...
end
The installer also adds an empty giveaways_user
method in your application controller. It a way for the gem to get hold of your app's current user. Simply provide the code in the method to return that user. If you are using devise you can simply return current_user.
class AplicationController
def giveaways_user
current_user # or whatever method you use to return authenticated users
end
def giveaways_unauthorized_path
# return the path to redirect unauthorized users.
# e.g. root_path or sign_in_path etc
end
end
The second method giveaways_unauthorized_path
returns the path to return to whenever a user / visitor tries to access the admin without authorization. Probably sending them to your sign in page is the best bet.
Final steps
There are a three extra things you will need to do that the installer couldn't:
1. Define a method in your User model (or equivalant) to authorize access to the Giveaways admin dashboard
Add a method called can_manage_giveaways?
to your User model. Instances which return true will be able to access the admin dashboard.
class User
def can_manage_giveaways?
# returns true if authorized
# e.g.
# return true if admin? or moderator?
end
end
2. Add the giveaway stylesheet to your assets path
Because the gem's layouts are loading a file called 'giveaways.css' and not 'application.css' you will need to add 'giveaways.css' to your assets file path. This is to prevent any of giveaways styles bleeding into your own and vice versa.
In config/intializers/assets.rb add or ammend the following line
# note extension is the post compiled extension of css
Rails.application.config.assets.precompile += %w( giveaways.css )
3. Make sure you have a mailer setup
Everytime an entrant enters a content they will be emailed a confirmation link to confirm their email. This means you need to have a mailer setup.
You can do that by reading the Rails guide on mailers
In development you might want to add ryanb's excellent letter_opener gem. This allows you to preview all emails in your browser as they are sent - no more checking your logs to see everything is ok.
And that's it!
You are all set. Simply visit /giveaways/giveaways to get started
Optional configuration
Define a 'Back to app' link
In the admin section there is a convenience link back to your app. By default it is set to '/'. You can change it by adding the following to the initializer file mentioned above
Giveaways.main_app_path = '/welcome'
Styling with custom css and html
If you don't wan't to use the default styles or views you can roll your own.
First you should get copies of the views by running
rails g giveaways:views
These views will still use the default layouts inside the gem but you will want to use your own layouts.
To provide your own layouts which you have in your usual layouts directory, specify their location in the initializer. You can define two layouts. One for the admin side and the second for all the publicly facing views such as the contest entry form.
# config/initializers/giveaways.rb
Giveaways.admin_layout = 'layouts/application' # path to your application layout
Giveaways.public_layout = 'layouts/another_layout'
Because admin can preview contests whilst they construct them you will need to provide a link to exit the preview mode. You can simply include this partial in your public layout:
<%= render partial: 'giveaways/shared/exit_preview' %>
In your admin area you can also include the default nav in your custom admin layout with this partial:
<%= render partial: 'giveaways/shared/admin_nav' %>
Problems? Ideas for improvements?
Let me know via the issue tracker!
Have fun.
Adam.