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