Installation - lstpsche/webring-rails GitHub Wiki
Installation
[!TIP] We recommend using the webring_routes helper for the easiest setup experience. It automatically configures all necessary routes with sensible defaults.
Step-by-Step Guide with webring_routes Helper
Add this line to your application's Gemfile:
gem 'webring-rails'
Run:
# Install the gem
bundle install
# Create the member model and migrations
rails generate webring:member
# Create the navigation controller
rails generate webring:navigation_controller
Optional Features
# Enable the membership request system
rails generate webring:membership_request
# Add membership request controller and routes
rails generate webring:membership_requests_controller
Configure Routes
Use the webring_routes
helper in your config/routes.rb
:
# config/routes.rb
Rails.application.routes.draw do
webring_routes
# ... other routes
end
Finally, run the migrations:
rails db:migrate
Using webring_routes Helper
The webring_routes
helper method provides an easy way to configure webring routes, similar to how Devise works with devise_for
.
Default Routes
# config/routes.rb
Rails.application.routes.draw do
webring_routes
end
This generates:
- Webring routes with
webring
namespace - Widget route:
GET /widget.js
→webring/widget#show
- Navigation routes:
GET /webring/next
,GET /webring/previous
,GET /webring/random
→webring/navigation#*
- Metrics endpoints for tracking
- Membership request routes
Custom Controllers
# config/routes.rb
Rails.application.routes.draw do
webring_routes navigation: :custom_navigation, widget: :custom_widget
end
Configuration Options
Option | Default | Description |
---|---|---|
navigation |
:navigation |
Controller name for navigation routes |
widget |
:widget |
Controller name for widget routes |
mount_path |
'/webring' |
Path where the webring engine is mounted |
mount_as |
:webring |
Name for the mounted engine route |
skip_metrics |
false |
Skip generating metrics endpoints |
skip_membership_requests |
false |
Skip generating membership request routes |
Advanced Configuration
# config/routes.rb
Rails.application.routes.draw do
webring_routes(
navigation: :my_navigation,
widget: :my_widget,
mount_path: 'my-webring'
)
end
Legacy Installation (Manual Setup)
[!WARNING] This approach is no longer recommended. Use the
webring_routes
helper instead for easier maintenance and consistency.
If you prefer manual route configuration or are migrating from an older version:
# Install the gem
bundle install
# Run the installation generator (adds routes manually)
rails generate webring:install
# Create models and controllers
rails generate webring:member
rails generate webring:navigation_controller
Migration from Manual Setup
Before (Manual):
Rails.application.routes.draw do
scope module: 'webring', as: 'webring' do
get 'widget.js', to: 'custom_widget#show', format: 'js', as: :widget
get 'webring/next', to: 'custom_navigation#next', as: :next
get 'webring/previous', to: 'custom_navigation#previous', as: :previous
get 'webring/random', to: 'custom_navigation#random', as: :random
end
# ... more route configurations
end
After (Using Helper):
Rails.application.routes.draw do
webring_routes navigation: :custom_navigation, widget: :custom_widget
end