{"id":16945138,"url":"https://github.com/rafbm/submodel","last_synced_at":"2025-08-13T23:02:40.784Z","repository":{"id":17487289,"uuid":"20270376","full_name":"rafbm/submodel","owner":"rafbm","description":"Submodel maps ActiveRecord columns to ActiveModel models","archived":false,"fork":false,"pushed_at":"2014-08-05T19:09:52.000Z","size":180,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-23T22:38:32.766Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rafbm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-05-28T19:54:42.000Z","updated_at":"2021-01-19T14:29:07.000Z","dependencies_parsed_at":"2022-07-26T18:15:09.459Z","dependency_job_id":null,"html_url":"https://github.com/rafbm/submodel","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafbm%2Fsubmodel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafbm%2Fsubmodel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafbm%2Fsubmodel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafbm%2Fsubmodel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rafbm","download_url":"https://codeload.github.com/rafbm/submodel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248431728,"owners_count":21102257,"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-10-13T21:21:14.502Z","updated_at":"2025-04-11T15:32:28.667Z","avatar_url":"https://github.com/rafbm.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Submodel\n\nSubmodel maps ActiveRecord columns to ActiveModel models, so that [hstore](http://www.postgresql.org/docs/9.3/static/hstore.html) or [serialized](http://api.rubyonrails.org/classes/ActiveRecord/AttributeMethods/Serialization/ClassMethods.html) hash columns can share validations and be augmented with some methods. This can greatly help cleanup your business logic.\n\n## Usage\n\n```ruby\n# Gemfile\ngem 'submodel'\n```\n\nCreate a submodel with `ActiveModel::Model`. Here’s an example `Address` model using [Carmen](http://github.com/jim/carmen) to provide country and state validations.\n\n```ruby\n# app/submodels/address.rb\n\nclass Address\n  include ActiveModel::Model\n\n  COUNTRY_CODES  = Carmen::Country.all.map(\u0026:code)\n  CA_STATE_CODES = Carmen::Country.coded('CA').subregions.map(\u0026:code)\n  US_STATE_CODES = Carmen::Country.coded('US').subregions.map(\u0026:code)\n\n  attr_accessor :street_1, :street_2, :city, :state, :country, :postal_code\n\n  validates_inclusion_of :country, in: COUNTRY_CODES\n  validates_inclusion_of :state, in: CA_STATE_CODES, if: :canada?\n  validates_inclusion_of :state, in: US_STATE_CODES, if: :united_states?\n\n  def canada?\n    country == 'CA'\n  end\n\n  def united_states?\n    country == 'US'\n  end\nend\n```\n\nUse the `submodel` method to map your ActiveRecord columns to the submodel.\n\n```ruby\n# app/models/order.rb\n\nclass Order \u003c ActiveRecord::Base\n  submodel :billing_address, Address\nend\n```\n\nThen, accessing `#billing_address` will return an instance created with `Address.new`. Similarly, passing a hash to `#billing_address=` will create a new instance with the hash as argument.\n\n```ruby\norder = Order.new\norder.attributes # =\u003e { \"id\" =\u003e nil, \"billing_address\" =\u003e nil }\n\norder.billing_address # =\u003e #\u003cAddress\u003e\norder.billing_address.blank? # =\u003e true\n\norder.billing_address.street_1 = '123 Fake Street'\norder.billing_address # =\u003e #\u003cAddress street_1=\"123 Fake Street\"\u003e\norder.billing_address.blank? # =\u003e false\n\norder.billing_address = { country: 'CA', state: 'QC' }\norder.billing_address # =\u003e #\u003cAddress state=\"QC\" country=\"CA\"\u003e\n```\n\nNote: While the getter creates an instance on demand, blank submodels are persisted as `NULL`.\n\n## Comparison\n\nWhen using `==`, your submodel columns will be compared based on the stringified hash of their instance variables. Blank variables are ignored.\n\n```ruby\norder = Order.new\norder.billing_address # =\u003e #\u003cAddress\u003e\n\norder.billing_address == Address.new # =\u003e true\norder.billing_address == {} # =\u003e true\norder.billing_address == { street_1: '', street_2: '  ' } # =\u003e true\norder.billing_address == { street_1: 'foo', street_2: 'bar' } # =\u003e false\n\norder.billing_address.country = 'CA'\norder.billing_address.state = 'QC'\norder.billing_address == { 'country' =\u003e 'CA', :state =\u003e 'QC' } # =\u003e true\norder.billing_address == Address.new(country: 'CA') # =\u003e false\n```\n\n## Extending submodels per-column\n\nYou can pass the `submodel` method a block to be executed at the class level. For instance, this adds an (unfortunate) validation to `shipping_address`, leaving `billing_address` as is.\n\n```ruby\nclass Order \u003c ActiveRecord::Base\n  submodel :billing_address, Address\n  submodel :shipping_address, Address do\n    validates :country, inclusion: { in: %w[US CA] }\n  end\nend\n```\n\n## This gem seems overkill.\n\nYou might think “Why not just override the getter and setter?” In my experience, getting this *right* is always more complex. If you want proper behavior (validation, comparison, FormBuilder support, persistence) you basically have to repeat [this code](lib/submodel/active_record.rb) for every column.\n\n---\n\n© 2014 [Rafaël Blais Masson](http://rafbm.com). Submodel is released under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafbm%2Fsubmodel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frafbm%2Fsubmodel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafbm%2Fsubmodel/lists"}