Calagator is distributed as a Rails engine, which is a type of Ruby gem that can be "mounted" inside of a Rails application to add functionality. In this document, we'll refer to the app that Calagator is mounted in as the host application.
Calagator requires Ruby 1.9.3 - 2.1.x, and a host application built on Rails 4 or newer.
If you're looking to build your own community calendar using Calagator, follow these instructions. If you're aiming to contribute code to Calagator itself, see the instructions in DEVELOPMENT.md.
First, install the calagator gem:
gem install calagator --pre
You can then use the calagator command to generate a new Rails application with Calagator installed:
calagator new my_great_calendar
cd my_great_calendar
You should now be able to start your calendar in development mode with:
bin/rails server
If all went according to plan, you should be able to see your calendar at: http://localhost:3000.
To stop the server, press CTRL-C.
Calagator's settings can be configured by editing these files in your host application:
config/initializers/01_calagator.rbconfig/initializers/02_geokit.rb
Please see these file for more details.
It's important to make sure your time zone is properly configured in config/application.rb. Calagator relies heavily on this setting when displaying event times.
Calagator uses a number of API keys to communicate with external services.
-
Google Maps: To use Google's geocoder, and to use Google to display maps, you must get an API key. See
config/initializers/01_calagator.rbandconfig/initializers/02_geokit.rbfor details. -
Meetup.com: To import events from Meetup.com, you need an API key. See
config/initializers/01_calagator.rbfor details.
You can specify the search engine to use in config/initializers/01_calagator.rb:
This is the default search engine which uses SQL queries. This option requires no additional setup, dependencies, or service. It does not provide relevance-based sorting. It does provide substring matches.
This optional search engine uses the Sunspot gem. This option requires additional setup, dependencies, and service. It provides relevance-based sorting. It does not provide substring matches.
To use Sunspot, you will need to install Java 1.6.x, a programming language used to run the search service.
You can start the Solr search service for local development with:
bundle exec rake sunspot:solr:start
You will then need to initially populate your records by running:
bundle exec rake sunspot:reindex:calagator
You can stop the Solr search service with:
bundle exec rake sunspot:solr:stop
Calagator has tests that verify functionality against Solr automatically, if the tests find the service running; you'll see pending tests if Solr isn't found. To start a test instance of Solr, do:
bundle exec rake RAILS_ENV=test sunspot:solr:start
You should set up a firewall to protect the ports utilized by the Solr search service. These ports are described in the config/sunspot.yml file.
There are two places you'll want to customize right away. Both are *.html.erb files you'll need to create.
views/calagator/site/_description.html.erb is the description in the sidebar on the home page of your calendar.
views/calagator/site/about.html.erb is the about page linked to from the home page. The existing sidebar has links to anchors called find_local_events, share_local_events, and get_involved as suggested sections of the About page.
Is there something wrong, unclear, or outdated in this documentation? Please get in touch so we can make it better. If you can contribute improved text, we'd really appreciate it.