webring-rails 1.0.0

data/app/assets/javascripts/webring/widget.js

@@ -0,0 +1,224 @@
+/**
+ * Webring Navigation Widget
+ *
+ * Usage:
+ * <script src="https://yourhub.com/webring/widget.js" data-member-uid="YOUR_MEMBER_UID" data-widget-type="full"></script>
+ * <div id="webring-widget"></div>
+ *
+ * For multiple widgets on same page:
+ * <script src="https://yourhub.com/webring/widget.js" data-member-uid="YOUR_MEMBER_UID" data-widget-type="full" data-target-id="custom-widget-id"></script>
+ * <div id="custom-widget-id"></div>
+ *
+ * Widget Types:
+ * - full: text, back btn, random btn, forward btn (default)
+ * - no-text: back btn, random btn, forward btn (no text)
+ * - two-way: back btn, forward btn (no random)
+ * - one-way: forward btn only
+ *
+ * Additional Options:
+ * - data-button-text="true|false": If true, buttons will show text labels. If false, only symbols are shown. Default: true
+ * - data-styles="full|layout|none": Controls styling applied to the widget. Default: full
+ *   - full: Apply all styles (default)
+ *   - layout: Only layout styles, no visual design
+ *   - none: No styles applied
+ */
+
+(function() {
+  // Configuration constants
+  const WIDGET_CONFIG = {
+    VALID_TYPES: ['full', 'no-text', 'two-way', 'one-way'],
+    DEFAULT_TYPE: 'full',
+    DEFAULT_TARGET_ID: 'webring-widget',
+    STYLE_ID: 'webring-widget-styles',
+    VALID_STYLE_TYPES: ['full', 'layout', 'none'],
+    DEFAULT_STYLE_TYPE: 'full'
+  };
+
+  const NAVIGATION_ACTIONS = {
+    prev: {
+      symbol: '«',
+      text: '« Prev',
+      title: 'Previous site',
+      path: 'previous'
+    },
+    random: {
+      symbol: '⚡',
+      text: 'Random',
+      title: 'Random site',
+      path: 'random'
+    },
+    next: {
+      symbol: '»',
+      text: 'Next »',
+      title: 'Next site',
+      path: 'next'
+    }
+  };
+
+  const WIDGET_TYPE_CONFIG = {
+    'full': { showTitle: true, actions: ['prev', 'random', 'next'] },
+    'no-text': { showTitle: false, actions: ['prev', 'random', 'next'] },
+    'two-way': { showTitle: false, actions: ['prev', 'next'] },
+    'one-way': { showTitle: false, actions: ['next'] }
+  };
+
+  // Define styles outside the function to avoid duplication
+  const STYLES = {
+    layout: `
+      .webring-nav {
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+        font-size: 16px;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        max-width: 350px;
+        margin: 0 auto;
+        padding: 10px;
+      }
+      .webring-title {
+        margin-bottom: 8px;
+      }
+      .webring-nav nav {
+        display: flex;
+        gap: 10px;
+        width: 100%;
+        justify-content: center;
+      }
+      .webring-nav a.webring-btn {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 6px 12px;
+        text-decoration: none;
+      }
+      .webring-nav[data-widget-type="no-text"] {
+        padding: 8px 10px;
+      }
+      .webring-nav[data-widget-type="one-way"] {
+        max-width: 200px;
+      }
+      .webring-nav[data-widget-type="one-way"] nav {
+        justify-content: center;
+      }
+    `,
+    design: `
+      .webring-nav[data-widget-type="full"] {
+        border: 2.5px solid #000000;
+      }
+      .webring-title {
+        font-weight: 600;
+      }
+      .webring-nav a.webring-btn {
+        color: #000000;
+        font-weight: 600;
+        background-color: #ffffff;
+        border: 2.5px solid #000000;
+        transition: background-color 0.2s ease, color 0.2s ease;
+      }
+      .webring-nav a.webring-btn:hover {
+        background-color: #000000;
+        color: #ffffff;
+      }
+      .webring-nav a.webring-btn:focus {
+        outline: none;
+        background-color: transparent;
+        color: #000000;
+      }
+      .webring-nav a.webring-btn:active {
+        border-color: #000000;
+        background-color: #000000;
+        color: #ffffff;
+      }
+    `
+  };
+
+  // Run immediately for widget initialization
+  createWidget();
+
+  function createWidget(scriptElement) {
+    const script = scriptElement || document.currentScript || (function() {
+      const scripts = document.getElementsByTagName('script');
+      return scripts[scripts.length - 1];
+    })();
+
+    if (!script) return;
+
+    // Config from data attributes
+    const memberUid = script.getAttribute('data-member-uid');
+    const widgetType = script.getAttribute('data-widget-type') || WIDGET_CONFIG.DEFAULT_TYPE;
+    const targetId = script.getAttribute('data-target-id') || WIDGET_CONFIG.DEFAULT_TARGET_ID;
+    const buttonText = script.getAttribute('data-button-text') !== 'false';
+    const stylesType = script.getAttribute('data-styles') || WIDGET_CONFIG.DEFAULT_STYLE_TYPE;
+    const stylesOption = WIDGET_CONFIG.VALID_STYLE_TYPES.includes(stylesType) ? stylesType : WIDGET_CONFIG.DEFAULT_STYLE_TYPE;
+
+    if (!memberUid) {
+      console.error('Webring Widget: Missing data-member-uid attribute on script tag.');
+      return;
+    }
+
+    if (!WIDGET_CONFIG.VALID_TYPES.includes(widgetType)) {
+      console.error(`Webring Widget: Invalid widget type "${widgetType}". Valid types: ${WIDGET_CONFIG.VALID_TYPES.join(', ')}`);
+      return;
+    }
+
+    const scriptSrc = script.getAttribute('src');
+    const baseUrl = new URL(scriptSrc, window.location.href).origin;
+
+    const renderWidget = function() {
+      const container = document.getElementById(targetId);
+      if (!container) {
+        console.error(`Webring Widget: No element with id "${targetId}" found.`);
+        return;
+      }
+
+      // Navigation links
+      const config = WIDGET_TYPE_CONFIG[widgetType];
+      const linkElements = config.actions.map(action => {
+        const actionConfig = NAVIGATION_ACTIONS[action];
+        const url = `${baseUrl}/webring/${actionConfig.path}?source_member_uid=${memberUid}`;
+        const label = buttonText ? actionConfig.text : actionConfig.symbol;
+        return `<a href="${url}" title="${actionConfig.title}" class="webring-btn">${label}</a>`;
+      }).join('\n          ');
+
+      // Create widget HTML
+      const title = config.showTitle ? '<span class="webring-title">Webring</span>' : '';
+      container.innerHTML = `
+        <div class="webring-nav" data-widget-type="${widgetType}">
+          ${title}
+          <nav class="webring-buttons">
+            ${linkElements}
+          </nav>
+        </div>
+      `;
+
+      applyStyles(stylesOption);
+    };
+
+    function applyStyles(styleOption) {
+      let styleElement = document.getElementById(WIDGET_CONFIG.STYLE_ID);
+      if (!styleElement) {
+        styleElement = document.createElement('style');
+        styleElement.id = WIDGET_CONFIG.STYLE_ID;
+        document.head.appendChild(styleElement);
+      }
+
+      switch (styleOption) {
+        case 'none':
+          styleElement.textContent = '';
+          break;
+        case 'layout':
+          styleElement.textContent = STYLES.layout;
+          break;
+        default: // 'full'
+          styleElement.textContent = STYLES.layout + STYLES.design;
+      }
+    }
+
+    // Run immediately or wait for DOM
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', renderWidget);
+    } else {
+      renderWidget();
+    }
+  }
+})();

data/app/controllers/webring/application_controller.rb

@@ -0,0 +1,5 @@
+module Webring
+  class ApplicationController < ActionController::Base
+    layout 'application'
+  end
+end

data/app/controllers/webring/members_controller.rb

@@ -0,0 +1,60 @@
+module Webring
+  class MembersController < ::ApplicationController
+    before_action :set_member, only: %i[show edit update destroy]
+
+    # GET /webring/members
+    def index
+      @members = Member.all.order(created_at: :desc)
+    end
+
+    # GET /webring/members/1
+    def show; end
+
+    # GET /webring/members/new
+    def new
+      @member = Member.new
+    end
+
+    # GET /webring/members/1/edit
+    def edit; end
+
+    # POST /webring/members
+    def create
+      @member = Member.new(member_params)
+
+      if @member.save
+        redirect_to admin_panel_member_path(@member), notice: 'Member was successfully created.'
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    # PATCH/PUT /webring/members/1
+    def update
+      if @member.update(member_params)
+        redirect_to admin_panel_member_path(@member), notice: 'Member was successfully updated.'
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    # DELETE /webring/members/1
+    def destroy
+      @member.destroy
+
+      redirect_to admin_panel_members_url, notice: 'Member was successfully destroyed.'
+    end
+
+    private
+
+    # Use callbacks to share common setup or constraints between actions.
+    def set_member
+      @member = Member.find_by!(uid: params[:id])
+    end
+
+    # Only allow a list of trusted parameters through.
+    def member_params
+      params.require(:member).permit(:name, :url)
+    end
+  end
+end

data/app/controllers/webring/navigation_controller.rb

@@ -0,0 +1,68 @@
+module Webring
+  class NavigationController < ApplicationController
+    before_action :find_member, only: %i[next previous]
+    before_action :ensure_members_exist, :check_member_exists, only: [:random]
+
+    # GET /webring/next
+    def next
+      member = Webring::Member.find_next(@member.uid)
+
+      redirect_to_member(member)
+    end
+
+    # GET /webring/previous
+    def previous
+      member = Webring::Member.find_previous(@member.uid)
+
+      redirect_to_member(member)
+    end
+
+    # GET /webring/random
+    def random
+      member = Webring::Member.find_random(source_member_uid: permitted_params[:source_member_uid])
+
+      redirect_to_member(member)
+    end
+
+    private
+
+    def permitted_params
+      params.permit(:source_member_uid)
+    end
+
+    def redirect_to_member(member)
+      redirect_to member.url, allow_other_host: true
+    end
+
+    def find_member
+      @member = Webring::Member.find_by(uid: permitted_params[:source_member_uid])
+      return if @member
+
+      render_member_not_found
+    end
+
+    def check_member_exists
+      member_uid = permitted_params[:source_member_uid]
+      return unless member_uid.present? && !Webring::Member.exists?(uid: member_uid)
+
+      render_member_not_found
+    end
+
+    def ensure_members_exist
+      return if Webring::Member.exists?
+
+      render plain: 'No members in the webring', status: :not_found
+    end
+
+    def render_member_not_found
+      render plain: 'Member not found', status: :not_found
+    end
+
+    def set_cors_headers
+      headers['Access-Control-Allow-Origin'] = '*'
+      headers['Access-Control-Allow-Methods'] = 'GET, OPTIONS'
+      headers['Access-Control-Allow-Headers'] = 'Origin, X-Requested-With, Content-Type, Accept'
+      headers['Access-Control-Max-Age'] = '86400'
+    end
+  end
+end

data/app/controllers/webring/widget_controller.rb

@@ -0,0 +1,31 @@
+module Webring
+  class WidgetController < ::ApplicationController
+    # Disable CSRF protection for widget.js as it needs to be loaded from other domains
+    skip_forgery_protection only: :show
+
+    # Set CORS headers for the widget
+    before_action :set_cors_headers, only: :show
+
+    # Serve the webring navigation widget JavaScript
+    # GET /webring/widget.js
+    def show
+      respond_to do |format|
+        format.js do
+          response.headers['Content-Type'] = 'application/javascript'
+
+          # Serve the JavaScript file from the engine's assets
+          render file: Webring::Engine.root.join('app/assets/javascripts/webring/widget.js')
+        end
+      end
+    end
+
+    private
+
+    def set_cors_headers
+      response.headers['Access-Control-Allow-Origin'] = '*'
+      response.headers['Access-Control-Allow-Methods'] = 'GET, OPTIONS'
+      response.headers['Access-Control-Allow-Headers'] = 'Origin, X-Requested-With, Content-Type, Accept'
+      response.headers['Access-Control-Max-Age'] = '86400'
+    end
+  end
+end

data/app/helpers/webring/application_helper.rb

@@ -0,0 +1,4 @@
+module Webring
+  module ApplicationHelper
+  end
+end

data/app/jobs/webring/application_job.rb

@@ -0,0 +1,4 @@
+module Webring
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/webring/application_mailer.rb

@@ -0,0 +1,6 @@
+module Webring
+  class ApplicationMailer < ActionMailer::Base
+    default from: 'from@example.com'
+    layout 'mailer'
+  end
+end

data/app/models/concerns/webring/navigation.rb

@@ -0,0 +1,60 @@
+module Webring
+  # Requires model to have `uid` and `created_at` columns
+  module Navigation
+    # Find the next member in the webring after the current one
+    # If current member is the last, return the first member (ring concept)
+    def find_next(source_member_uid)
+      source_member = find_by(uid: source_member_uid)
+      return first_member_by_creation unless source_member
+
+      find_next_member(source_member) || first_member_by_creation
+    end
+
+    # Find the previous member in the webring before the current one
+    # If current member is the first, return the last member (ring concept)
+    def find_previous(source_member_uid)
+      source_member = find_by(uid: source_member_uid)
+      return last_member_by_creation unless source_member
+
+      find_previous_member(source_member) || last_member_by_creation
+    end
+
+    # Find a random member, excluding the current one if provided
+    # If current member is the only one, return it
+    def find_random(source_member_uid: nil)
+      return order('RANDOM()').first if source_member_uid.blank?
+
+      # Use exists? check to avoid loading records when not needed
+      excluded_scope = where.not(uid: source_member_uid)
+
+      if excluded_scope.exists?
+        excluded_scope.order('RANDOM()').first
+      else
+        # if only one member exists (the current one), return it
+        find_by(uid: source_member_uid)
+      end
+    end
+
+    private
+
+    def first_member_by_creation
+      order(created_at: :asc).first
+    end
+
+    def last_member_by_creation
+      order(created_at: :desc).first
+    end
+
+    def find_next_member(source_member)
+      where('created_at > ?', source_member.created_at)
+        .order(created_at: :asc)
+        .first
+    end
+
+    def find_previous_member(source_member)
+      where('created_at < ?', source_member.created_at)
+        .order(created_at: :desc)
+        .first
+    end
+  end
+end

data/app/models/webring/application_record.rb

@@ -0,0 +1,5 @@
+module Webring
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/webring/member.rb

@@ -0,0 +1,31 @@
+module Webring
+  class Member < ApplicationRecord
+    extend Webring::Navigation
+
+    UID_LENGTH = 16 # 32-character hex string
+
+    validates :url, presence: true, uniqueness: true
+    validates :name, uniqueness: true, if: -> { name.present? }
+    validates :uid, presence: true, uniqueness: true, length: { is: UID_LENGTH * 2 }
+
+    before_validation :generate_uid, if: -> { uid.blank? }
+    before_validation :set_name_from_url, if: -> { name.blank? && url.present? }
+
+    def to_param
+      uid
+    end
+
+    private
+
+    def generate_uid
+      loop do
+        self.uid = SecureRandom.hex(UID_LENGTH)
+        break unless self.class.exists?(uid: uid)
+      end
+    end
+
+    def set_name_from_url
+      self.name = url
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,8 @@
+Webring::Engine.routes.draw do
+  get 'next', to: 'navigation#next'
+  get 'previous', to: 'navigation#previous'
+  get 'random', to: 'navigation#random'
+  get 'widget.js', to: 'widget#show', format: 'js', as: :widget
+
+  root to: 'navigation#random'
+end

data/lib/generators/USAGE

@@ -0,0 +1,25 @@
+Description:
+    The webring generator creates the necessary structure for integrating webring
+    functionality into your Rails application.
+
+Example:
+    rails generate webring:install
+
+    This will create:
+        config/initializers/webring.rb
+        # And mount the Webring engine in your routes.rb file
+
+Example:
+    rails generate webring:member
+
+    This will create:
+        app/models/webring/member.rb
+        db/migrate/TIMESTAMP_create_webring_members.rb
+        # And add member routes to your routes.rb file
+
+Example:
+    rails generate webring:controller
+
+    This will create:
+        app/controllers/webring/navigation_controller.rb
+        # And add navigation routes to your routes.rb file

data/lib/generators/webring/controller/controller_generator.rb

@@ -0,0 +1,49 @@
+require_relative '../shared/route_injector'
+
+module Webring
+  module Generators
+    # @description The ControllerGenerator creates a NavigationController to handle webring navigation
+    # This generator creates both the controller file and adds the required routes
+    #
+    # @usage Run: rails generate webring:controller
+    #
+    # @example The generated controller provides three main navigation endpoints:
+    #   # GET /webring/next     - Navigate to the next site in the webring
+    #   # GET /webring/previous - Navigate to the previous site in the webring
+    #   # GET /webring/random   - Navigate to a random site in the webring
+    #
+    # @note This generator should be run after installing the Webring engine and
+    #       generating the Member model with webring:member
+    class ControllerGenerator < Rails::Generators::Base
+      include Shared::RouteInjector
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a Webring::NavigationController and necessary routes for webring navigation'
+
+      # Creates the NavigationController file based on the template
+      # @return [void]
+      def create_controller_file
+        template 'navigation_controller.rb', 'app/controllers/webring/navigation_controller.rb'
+      end
+
+      # Adds navigation routes to the application's routes.rb file
+      # These routes are used to navigate between webring members
+      # @return [void]
+      def create_navigation_routes
+        route_content = <<~ROUTE
+          # Webring navigation routes
+          namespace :webring do
+            root to: 'navigation#random'
+
+            get 'next', to: 'navigation#next'
+            get 'previous', to: 'navigation#previous'
+            get 'random', to: 'navigation#random'
+          end
+        ROUTE
+
+        inject_webring_routes(route_content)
+      end
+    end
+  end
+end

data/lib/generators/webring/controller/templates/navigation_controller.rb

@@ -0,0 +1,61 @@
+module Webring
+  class NavigationController < ApplicationController
+    before_action :find_member, only: %i[next previous]
+    before_action :ensure_members_exist, :check_member_exists, only: [:random]
+
+    # GET /webring/next
+    def next
+      member = Webring::Member.find_next(@member.uid)
+
+      redirect_to_member(member)
+    end
+
+    # GET /webring/previous
+    def previous
+      member = Webring::Member.find_previous(@member.uid)
+
+      redirect_to_member(member)
+    end
+
+    # GET /webring/random
+    def random
+      member = Webring::Member.find_random(source_member_uid: permitted_params[:source_member_uid])
+
+      redirect_to_member(member)
+    end
+
+    private
+
+    def permitted_params
+      params.permit(:source_member_uid)
+    end
+
+    def redirect_to_member(member)
+      redirect_to member.url, allow_other_host: true
+    end
+
+    def find_member
+      @member = Webring::Member.find_by(uid: permitted_params[:source_member_uid])
+      return if @member
+
+      render_member_not_found
+    end
+
+    def check_member_exists
+      member_uid = permitted_params[:source_member_uid]
+      return unless member_uid.present? && !Webring::Member.exists?(uid: member_uid)
+
+      render_member_not_found
+    end
+
+    def ensure_members_exist
+      return if Webring::Member.exists?
+
+      render plain: 'No members in the webring', status: :not_found
+    end
+
+    def render_member_not_found
+      render plain: 'Member not found', status: :not_found
+    end
+  end
+end

data/lib/generators/webring/install/install_generator.rb

@@ -0,0 +1,31 @@
+module Webring
+  module Generators
+    # @description The InstallGenerator is the first step to set up the Webring engine
+    # It mounts the Webring engine to your Rails application's routes
+    #
+    # @usage Run: rails generate webring:install
+    #
+    # @example After installation, the engine will be mounted at /webring
+    #   # In your routes.rb
+    #   mount Webring::Engine => '/webring', as: 'webring'
+    #
+    # @note You can change the mount path in your routes.rb file after installation
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates Webring routes and mounts the engine in your application.'
+
+      # Adds the engine mount point to the application's routes.rb file
+      # @return [void]
+      def add_webring_routes
+        route "mount Webring::Engine => '/webring', as: 'webring'\n\n"
+      end
+
+      # Displays the README with next steps after installation
+      # @return [void]
+      def show_readme
+        readme 'AFTER_INSTALL' if behavior == :invoke
+      end
+    end
+  end
+end