Rooftop::Rails::Events

A library to make it super-easy to integrate events from Rooftop CMS into your Rails site.

What's included

A bit of a mix of stuff, and all work in progress. Here's a flavour:

Controller Mixins

You need to include these yourself.

Rooftop::Rails::Events::EventHandler

A mixin for a controller which handles events. It has methods for show(), instances() and book_instance() which get the event from Rooftop for you.

In the simplest form, you can just include this in your controller

class EventsController < ApplicationController
    include Rooftop::Rails::Events::EventHandler
end

But each method yields to a block so you can do other stuff if you want. Here's a more representative EventsController from a real project:

class EventsController < ApplicationController
  include Rooftop::Rails::Events::EventHandler
  decorates_assigned :events, :event, with: EventDecorator
  layout :determine_layout

  def instances
    # Pass a block into the EventHandler mixin's method, which is yielded to at the end of the method
    super do
      # If the event has an external ticketing url, redirect to it instead of rendering a list of instances
      # n.b. pretty obviously you'll need to define has_external_ticketing_url?() and external_ticketing_url() on your model
      if @event.has_external_ticketing_url?
        redirect_to @event.external_ticketing_url and return
      end

      # If the event only has 1 instance, it seems a bit mean to list that instance and make the user click again; go straight to the book_instance method
      if @event.instances.count == 1
        redirect_to action: :book_instance, instance_id: @event.instances.first.meta_attributes[:spektrix_id] and return
      end

    end
  end

  private
  def determine_layout
    case action_name.to_sym
      when :show
        "templates/event_detail"
      when :instances
        "templates/instance_list"
      when :book_instance
        "templates/iframe_wide"
    end
  end
end

Model Mixins

These are included automatically when you use this gem.

Rooftop::Rails::Events::Cache

A mixin added to the Rooftop::Events::Event to cache / expire it.

### Rooftop::Rails::Events::InstanceCache The same as Rooftop::Rails::Events::Cache but for instances. Allows you to receive a webhook for just an instance and be able to clear the cache for its associated Event.

### Rooftop::Rails::Events::Scopes Handy scopes for dealing with events - finding after a date, between dates, in the future etc.

Object Decorators

We use a lot of Draper as our decorator pattern at Error Agency. So there are some mixins you add to your EventDecorator to provide utility methods for use in views.

#in your project
class EventDecorator < Draper::Decorator
    include Rooftop::Rails::Events::Decorators
end

## Controller mixin for Event collections The standard pattern we've found works well for Rooftop is to have a PagesController with mixins which check the template of the page you're rendering, and makes requests to get collections of objects you'll need.

class PagesController < ApplicationController
    include Rooftop::Rails::Events::EventCollections 
end

You get a bunch of stuff for free with this:

• Rooftop events in the future will be returned as a collection called @events by default
• if you pass in query params, you can filter these:
  • q will do a free-text search
  • from will take an dd-mm-yyyy date string and return things happening on or after that date
  • to will work likewise, in reverse

Customising querystring filters

You might want to filter by something else. That's relatively easy.

class PagesController < ApplicationController
    include Rooftop::Rails::Events::EventCollections
    self.add_event_filter :genre, ->(events,params) {
        # add something here which returns a collection when genre is passed in, for example
        # very important - you must return something here
        if params[:genre].present?
            events.with_genre(params[:genre])
        else
            events
        end
    }
end

Installation

Add this line to your application's Gemfile:

gem 'rooftop-rails-events'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rooftop-rails-events

Usage

TODO: Write usage instructions here

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rooftop-rails-events. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.