Routing System

Webring for Rails provides a streamlined routing system through the webring_routes helper method, similar to how Devise works with devise_for. This approach simplifies route configuration and ensures consistency across installations.

webring_routes Helper

The webring_routes helper method is the recommended way to configure webring routes in your Rails application.

Basic Usage

Add a single line to your config/routes.rb:

# config/routes.rb
Rails.application.routes.draw do
  webring_routes
  # ... other routes
end

This automatically generates:

• 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 widget usage
• Membership request routes (if MembershipRequest model exists)

Configuration Options

The webring_routes helper accepts several options for customization:

Option	Default	Description
navigation	:navigation	Controller name for navigation routes
widget	:widget	Controller name for widget routes
mount_path	'webring'	Module namespace for routes
mount_as	'webring'	Named route prefix
skip_metrics	false	Skip generating metrics endpoints
skip_membership_requests	false	Skip generating membership request routes

Custom Controllers

Use custom controllers for navigation and widget functionality:

# config/routes.rb
Rails.application.routes.draw do
  webring_routes navigation: :custom_navigation, widget: :custom_widget
end

This generates:

• Widget route: GET /widget.js → webring/custom_widget#show
• Navigation routes: GET /webring/next, GET /webring/previous, GET /webring/random → webring/custom_navigation#*

Advanced Configuration

# config/routes.rb
Rails.application.routes.draw do
  webring_routes(
    navigation: :my_navigation,
    widget: :my_widget,
    mount_path: 'network'
  )
end

Conditional Routes

Skip certain route groups based on your application's needs:

# Skip metrics tracking
webring_routes skip_metrics: true

# Skip membership request routes
webring_routes skip_membership_requests: true

# Skip both
webring_routes skip_metrics: true, skip_membership_requests: true

Generated Routes

The webring_routes helper creates the following routes:

Core Routes

# Widget serving
GET /widget.js → webring/widget#show (format: js)

# Navigation routes
GET /webring/next → webring/navigation#next
GET /webring/previous → webring/navigation#previous
GET /webring/random → webring/navigation#random

Metrics Routes (unless skipped)

# Widget usage tracking
POST /metrics/widget_fetched → metrics#widget_fetched
OPTIONS /metrics/widget_fetched → metrics#options_widget_fetched

Membership Request Routes (unless skipped)

# Membership requests
namespace :webring do
  resources :membership_requests, only: [:new, :create] do
    collection do
      get :thank_you
    end
  end
end

Route Names

The helper generates these route names:

Route Name	Path	Purpose
webring_widget_path	/widget.js	Widget JavaScript file
webring_next_path	/webring/next	Next site navigation
webring_previous_path	/webring/previous	Previous site navigation
webring_random_path	/webring/random	Random site navigation
widget_fetched_metrics_path	/metrics/widget_fetched	Metrics endpoint
new_webring_membership_request_path	/webring/membership_requests/new	New membership request
webring_membership_requests_path	/webring/membership_requests	Create membership request
thank_you_webring_membership_requests_path	/webring/membership_requests/thank_you	Thank you page

Migration from Manual Setup

Before (Manual Route Configuration)

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

  post 'metrics/widget_fetched', to: 'metrics#widget_fetched', as: :widget_fetched_metrics
  options 'metrics/widget_fetched', to: 'metrics#options_widget_fetched'

  namespace :webring do
    resources :membership_requests, only: [:new, :create] do
      collection do
        get :thank_you
      end
    end
  end
end

After (Using webring_routes Helper)

Rails.application.routes.draw do
  webring_routes navigation: :custom_navigation, widget: :custom_widget
end

Benefits

The webring_routes helper provides several advantages:

Cleaner Configuration

• Single line setup: Replace dozens of route declarations with one line
• Reduced boilerplate: No need to manually configure all routes
• Less error-prone: Eliminates typos and missing routes

Consistency

• Standardized routes: Ensures all installations use the same route structure
• Named routes: Consistent route names across all applications
• Future compatibility: Route changes are handled automatically in gem updates

Flexibility

• Easy customization: Simple options for common configuration needs
• Conditional loading: Skip unnecessary components with boolean flags
• Controller swapping: Easy switching between default and custom controllers

Maintenance

• Centralized logic: Route configuration logic is maintained in the gem
• Automatic updates: Route improvements are inherited on gem updates
• Backward compatibility: Existing route names are preserved

Troubleshooting

Routes Not Generated

If routes aren't being generated correctly:

1. Check route loading: Ensure the helper is called within Rails.application.routes.draw
2. Verify gem loading: Confirm webring-rails is in your Gemfile and installed
3. Check for conflicts: Look for existing route definitions that might conflict

Custom Controllers Not Working

If custom controllers aren't being used:

1. Verify controller names: Ensure controller names match the symbols passed to the helper
2. Check controller existence: Confirm custom controllers are generated and exist
3. Review namespacing: Controllers should be in the Webring namespace

Route Names Changed

The helper maintains the same route names as manual setup. If you experience issues:

1. Check route names: Run rails routes | grep webring to verify route names
2. Update references: Ensure view helpers use the correct route names
3. Test navigation: Verify all webring links are working correctly

Integration with Generators

The webring_routes helper works seamlessly with Webring generators:

# Generate models and controllers
rails generate webring:member
rails generate webring:navigation_controller
rails generate webring:custom_widget_controller

# Add to routes.rb
webring_routes navigation: :custom_navigation, widget: :custom_widget

The generators create controllers that are immediately compatible with the routing helper, requiring no additional configuration.