connect-rails
A rails engine for interfacing with OpenStax's common services server.
Usage
Add the engine to your Gemfile and then run bundle install
.
Mount the engine your application's routes.rb
file:
MyApplication::Application.routes.draw do
...
mount OpenStax::Connect::Engine, at: "/connect"
...
end
You can use whatever path you want instead of /connect
, just make sure to make the appropriate changes below.
Create an openstax_connect.rb
initializer in config/initializers
, with the following contents:
OpenStax::Connect.configure do |config|
config.openstax_application_id = 'value_from_openstax_services_here'
config.openstax_application_secret = 'value_from_openstax_services_here'
end
If you're running OpenStax Services in a dev instance on your machine, you can specify that instance's local URL with:
config.openstax_services_url = 'http://localhost:2999/'
To have users login, direct them to /connect/sessions/new
. This is also available through the openstax_connect.login
route helper, e.g. <%= link_to 'Sign in!', openstax_connect.login_path %>
.
There is also a logout path helper for /connect/sessions/destroy
, given by logout_path
. By default this expects a GET
request. If you'd prefer a DELETE
request, add this configuration:
config.logout_via = :delete
Make sure to install the engine's migrations:
rake openstax_connect:install:migrations
You also need to create your own User and AnonymousUser models. Once you do this, include concerns from the connect gem to get their baseline functionality.
class User < ActiveRecord::Base
include OpenStax::Connect::Models::User
...
end
and
class AnonymousUser < ActiveRecord::Base
include OpenStax::Connect::Models::AnonymousUser
...
end
Check out the engine code in app/concerns to see what this gets you.
Example Application
There is an example application included in the gem in the example
folder. Here are steps
to follow:
- Download (clone) the OpenStax Services site from github.com/openstax/services.
- In the site's
config
folder put asecret_settings.yml
file that has values for the following keys:facebook_app_id
,facebook_app_secret
,twitter_consumer_key
,twitter_consumer_secret
. If you don't have access to these values, you can always make dummy apps on facebook and twitter. - Do the normal steps to get this site online:
- Run
bundle install --without production
- Run
bundle exec rake db:migrate
- Run
bundle exec rails server
- Run
- Open this services site in a web browser (defaults to http://localhost:2999)
- Navigate to http://localhost:2999/oauth/applications
- Click
New application
- Set the callback URL to
http://localhost:4000/connect/auth/openstax/callback
.
Port 4000 is where you'll be running the example application. - The name can be whatever.
- Click the
Trusted?
checkbox. - Click
Submit
. - Keep this window open so you can copy the application ID and secret into the example app
- Set the callback URL to
- Leave the services app running
- Download (clone) the OpenStax Connect gem from github.com/openstax/connect-rails. The
example application is in the
example
folder. In that folder's config folder, create asecret_settings.yml
file according to the instructions insecret_settings.yml.example
. Run the example server in the normal way (bundle install..., migrate db, rails server). - Navigate to the home page, http://localhost:4000. Click log in and play around. You can also refresh the services site and see yourself logged in, log out, etc.
- For fun, change example/config/openstax_connect.rb to set
enable_stubbing
totrue
. Now when you click login you'll be taken to a developer-only page where you can login as other users, generate new users, create new users, etc.