{"id":20904675,"url":"https://github.com/sage/handler_registerable","last_synced_at":"2026-04-25T13:39:47.026Z","repository":{"id":56875801,"uuid":"61224623","full_name":"Sage/handler_registerable","owner":"Sage","description":"A ruby gem which provides a mechanism for common code to collaborate with a handler which is designed to meet a more concrete requirement","archived":false,"fork":false,"pushed_at":"2023-08-29T08:53:48.000Z","size":1384,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-01-19T14:16:39.699Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sage.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-15T16:50:45.000Z","updated_at":"2023-08-29T08:52:35.000Z","dependencies_parsed_at":"2024-11-18T13:20:28.832Z","dependency_job_id":"4e686bf7-0481-4a10-97df-7424b999461d","html_url":"https://github.com/Sage/handler_registerable","commit_stats":{"total_commits":14,"total_committers":4,"mean_commits":3.5,"dds":0.2857142857142857,"last_synced_commit":"d865d7aec3a75b21b15af2ee0492891498fcc9d3"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sage%2Fhandler_registerable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sage%2Fhandler_registerable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sage%2Fhandler_registerable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sage%2Fhandler_registerable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sage","download_url":"https://codeload.github.com/Sage/handler_registerable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243295511,"owners_count":20268385,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-18T13:18:27.879Z","updated_at":"2025-12-27T17:27:16.033Z","avatar_url":"https://github.com/Sage.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HandlerRegisterable\n\n[![Build Status](https://travis-ci.org/Sage/handler_registerable.svg?branch=master)](https://travis-ci.org/Sage/handler_registerable)\n[![Maintainability](https://api.codeclimate.com/v1/badges/aa4fce157655c3ee8497/maintainability)](https://codeclimate.com/github/Sage/handler_registerable/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/aa4fce157655c3ee8497/test_coverage)](https://codeclimate.com/github/Sage/handler_registerable/test_coverage)\n[![Gem Version](https://badge.fury.io/rb/handler_registerable.svg)](https://badge.fury.io/rb/handler_registerable)\n\n## Description\n\nRegistered handlers allow common code to collaborate with a handler which is designed to meet a more concrete requirement.\n\nThe basic premise is that a registry is created for a particular concern, and this registry allows each specific handler to be added. The registry handlers will conform to a documented API, and may often provide a base class or default implementations.\n\nYour application and context specific details can be written in a specific handler, and then added to the registry. At run time, code that needs to collaborate with the appropriate handler from the registry is correctly given the appropriate handler.\n\n![Demo Gif](assets/handler_registerable.gif)\n\n## Installation\n\nAdd to your project's Gemfile:\n\n```ruby\ngem 'handler_registerable'\n```\n\nRun in your project root:\n\n```\nbundle install\n```\n\n## Usage\n\nThis gem provides a Ruby module which can be extended into a class/module to provide the following class methods:\n\n`registered_handlers` - returns a hash which can be modified\n`obtain` - loops through all registered handlers and returns the first one that handles the given condition (tested by calling the `handles?` class method on each handler)\n\n### Creating your registry\n\nA registry is usually a module within a given namespace. For example let's create a welcome handler:\n\n```ruby\nmodule WelcomeHandlers\nend\n```\n\n```ruby\nmodule WelcomeHandlers\n  extend HandlerRegisterable::Registry\nend\n```\n\n### Base classes and registering\n\nTo make life easier you can provide a base class which allows users to subclass and register themselves within the registry:\n\n```ruby\nmodule WelcomeHandlers\n  class Base\n    def initialize(context)\n      @context = context\n    end\n\n    # Registers a handler with the given identifier.\n    #\n    # @param [Symbol] handler the identifier to represent this handler class.\n    def self.register(handler)\n      WelcomeHandlers.register self, handler\n    end\n  end\nend\n```\n\nIt's important to document the public API which handlers are required to implement. These methods will be dependant on the purpose of the registry, but all will require the appropriate `handles?` API for that registry.\n\n```ruby\nmodule WelcomeHandlers\n  class Example \u003c Base\n    register :first_time_user\n\n    def self.handles?(context)\n      context.some_attribute == 'example'\n    end\n  end\nend\n```\n\n\u003e Note: Handlers don't necessarily need to be within the registry's namespace (in fact in application code it will be in your own namespaces).\n\nThe exact arguments and conditions for the `handles?` class method in the handlers is specific to the purpose of the registry. This should always be a single arg, but if you need more than one, you can use a hash. However, you should look to keep the details to a minimum.\n\n### Defining and Registering\n\nLet's now define the public API for our Welcome handlers\n\n* `welcome_message` - returns the string for this type of business\n* `expiry_reminders` - array of time periods from trial expiration to email reminders\n\nHere's a couple of example handlers:\n\n```ruby\nclass ProductOneWelcome \u003c WelcomeHandler::Base\n  register :product_one\n\n  def self.handles?(user)\n    user.product == 'product_one'\n  end\n\n  def welcome_message\n    'Thanks for choosing product one'\n  end\n\n  def expiry_reminders\n    [2.weeks, 1.week, 2.days]\n  end\nend\n\nclass ProductTwoeWelcome \u003c WelcomeHandler::Base\n  register :product_two\n\n  def self.handles?(user)\n    user.product == 'product_two'\n  end\n\n  def welcome_message\n    'Thanks for choosing product two'\n  end\n\n  def expiry_reminders\n    [1.week, 2.days, 1.day]\n  end\nend\n```\n\n### Setting a Default\n\nWhen no handler is found, it is possible to specify a default handler to use instead:\n\n```ruby\nmodule WelcomeHandlers\n  class Default \u003c Base\n    WelcomeHandlers.default = self\n\n    def welcome_message\n      'A default welcome message'\n    end\n  end\nend\n```\n\n### Using the registry\n\nThe way the registry is used is through the `obtain` method:\n\n```ruby\n# code in a signup to a service object\n\ndef complete_signup(user)\n  welcome = WelcomeHandlers.obtain(user)\n  user.send_message(welcome.welcome_message)\n  ReminderJob.schedule_for_user(user, welcome.expiry_reminders)\nend\n```\n\n\n## License\n\nHandler Registerable is available as open source under the terms of the\n[Apache-2.0 licence](https://github.com/Sage/handler_registerable/blob/master/LICENSE).\n\nCopyright (c) 2018 Sage Group Plc. All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsage%2Fhandler_registerable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsage%2Fhandler_registerable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsage%2Fhandler_registerable/lists"}