{"id":13879167,"url":"https://github.com/eki-177/abyme","last_synced_at":"2026-04-01T17:20:20.950Z","repository":{"id":38346691,"uuid":"284742786","full_name":"eki-177/abyme","owner":"eki-177","description":"abyme is a modern take on handling dynamic nested forms in Rails 6+ using StimulusJS.","archived":false,"fork":false,"pushed_at":"2026-03-23T08:23:20.000Z","size":6986,"stargazers_count":87,"open_issues_count":13,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-03-28T00:37:12.710Z","etag":null,"topics":["nested-attributes","nested-forms","rails","stimulus"],"latest_commit_sha":null,"homepage":"","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/eki-177.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-08-03T15:55:14.000Z","updated_at":"2026-03-23T08:21:41.000Z","dependencies_parsed_at":"2024-06-02T19:41:14.201Z","dependency_job_id":null,"html_url":"https://github.com/eki-177/abyme","commit_stats":null,"previous_names":["bear-in-mind/abyme"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/eki-177/abyme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eki-177%2Fabyme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eki-177%2Fabyme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eki-177%2Fabyme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eki-177%2Fabyme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eki-177","download_url":"https://codeload.github.com/eki-177/abyme/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eki-177%2Fabyme/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["nested-attributes","nested-forms","rails","stimulus"],"created_at":"2024-08-06T08:02:11.969Z","updated_at":"2026-04-01T17:20:20.879Z","avatar_url":"https://github.com/eki-177.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# abyme 🕳\n\n[![Gem Version](https://badge.fury.io/rb/abyme.svg)](https://badge.fury.io/rb/abyme)\n![build](https://github.com/bear-in-mind/abyme/workflows/build/badge.svg)\n[![Maintainability](https://api.codeclimate.com/v1/badges/f591a9e00f7cf5188ad5/maintainability)](https://codeclimate.com/github/bear-in-mind/abyme/maintainability)\n[![Coverage Status](https://coveralls.io/repos/github/bear-in-mind/abyme/badge.svg?branch=master)](https://coveralls.io/github/bear-in-mind/abyme?branch=master)\n\nabyme is an easy and form-agnostic way to handle nested attributes in Rails, using [stimulus](https://stimulusjs.org/handbook/introduction) under the hood. Here's an example :\n```ruby\n# views/projects/_form.html.erb\n\u003c%= form_for @project do |f| %\u003e\n  \u003c%= f.text_field :title %\u003e\n  \u003c%= f.text_area :description %\u003e\n  \n  \u003c%= f.abyme_for(:tasks) %\u003e\n  \n  \u003c%= f.submit 'Save' %\u003e\n\u003c% end %\u003e\n```\nSupposing you have a `Project` that `has_many :tasks` and a partial located in `views/abyme/_task_fields` containing your form fields for `tasks`, the `abyme_for` command will generate and display 3 elements in this order :\n- A `div` containing all task fields for `@project.tasks` (either persisted or already built instances of `tasks`)\n- A `div` which will contain all additional tasks about to be created (added through the `Add task` button below)\n- A `button` to generate fields for new instances of tasks\n\nHave a look below to learn more about configuration and all its different options.\n\n## Demo app\n\n![Demo preview](https://res.cloudinary.com/aux-belles-autos/image/upload/v1603040053/abyme-preview.gif)\n\nCheck out our demo app here : https://abyme-demo.herokuapp.com/\n\nSource code is right here : https://github.com/bear-in-mind/abyme_demo\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'abyme'\n```\n\nAnd then execute:\n\n    $ bundle\n    $ yarn add abyme\n\n***IMPORTANT : If you use stimulus \u003c 3.0, please use yarn package v0.6.4 ***\nIf you have any issue importing or compiling the controller, you can simply [copy-paste it](https://github.com/eki-177/abyme/blob/master/src/abyme_controller.js) in your own `app/javascript/controllers` directory.\n\nIf you don't have Stimulus installed yet, please run :\n```bash\nyarn add @hotwired/stimulus\n```\n\nWith [Stimulus](https://stimulusjs.org/handbook/introduction) installed, you need to register the `stimulus` controller that takes care of the JavaScript behaviour. You can launch this generator :\n```bash\nrails generate abyme:stimulus\n```\nOr you can register it yourself :\n\n```javascript\n// app/javascript/controllers/index.js\nimport { Application } from \" @hotwired/stimulus\"\nimport { definitionsFromContext } from \"stimulus/webpack-helpers\"\n// Add this line below\nimport { AbymeController } from 'abyme'\n\nconst application = Application.start()\nconst context = require.context(\"controllers\", true, /_controller\\.js$/)\napplication.load(definitionsFromContext(context))\n// And this one\napplication.register('abyme', AbymeController)\n```\n\n## Getting started\n\nTo learn more about the *why* of this gem, check out our [wiki](https://github.com/bear-in-mind/abyme/wiki/What-are-nested-forms-and-why-a-new-gem-%3F)\n\nYou may also check out our [step by step tutorial](https://github.com/bear-in-mind/abyme/wiki/Step-by-step-Tutorial) and our [advanced configuration guide](https://github.com/bear-in-mind/abyme/wiki/Step-by-step-:-Advanced-configuration) (currently in construction).\n## Documentation\nAs in our [our tutorial](https://github.com/bear-in-mind/abyme/wiki/Step-by-step-Tutorial), we'll assume we have a `Project` model, that `has_many :tasks` for the rest of the documentation.\n### Generators\nTo be up and running in no time, we built a few generators. Feel free to skip these if you prefer a manual implementation.\n#### Resource\nTo generate everything you need with one command, use this generator :\n```bash\nrails generate abyme:resource project tasks\n# Includes configuration in Project model\n# Adds abyme_attributes in ProjectsController permitted params\n# Creates a partial and minimum boilerplate in app/views/abyme/_task_fields.html.erb\n```\nNow, head to your parent form and [keep reading](https://github.com/eki-177/abyme#abyme_forassociation-options---block) !\n\nYou can also specify [attributes to be permitted](https://github.com/eki-177/abyme#model), or permit all of them (see below). This will populate the partial with input fields for the specified attributes\n```bash\nrails generate abyme:resource project tasks description title\n# Includes configuration in Project model, including permitted attributes\n# Adds abyme_attributes in ProjectsController permitted params\n# Creates a partial with input fields for the specified attributes in app/views/abyme/_task_fields.html.erb\n```\n\n#### Individual generators\nAll the generators launched by the main `resource` generator are available individually :\n```bash\n# Controller\nrails generate abyme:controller Projects\n\n# Model\n# Permit only a few attributes\nrails generate abyme:model project tasks description title\n# Permit all attributes\nrails generate abyme:model project participants all_attributes\n\n# Views\n# Without attributes (use this if you're not using SimpleForm or don't care about generating input fields)\nrails generate abyme:view tasks\n# With a few attributes\nrails generate abyme:view tasks name description\n# With all attributes\nrails generate abyme:view tasks all_attributes\n```\n\n### Model\n\n💡 Don't forget to `include Abyme::Model` in your parent model\n\n#### #abymize(:association, permit: nil, reject: nil, options = {})\nIn models, the `abyme_for :association` acts as an alias for this command :\n```ruby\n  accepts_nested_attributes_for :association, reject_if: :all_blank, :allow_destroy: true\n```\n\n* `permit: []` : allows you to generate a hash of attributes that can be easily called on the controller side through the `::abyme_attributes` class method (see details below).\n```ruby\n  abymize :association, permit: [:name, :description]\n  \n  # You may also permit all attributes like so :\n  abymize :association, permit: :all_attributes \n```\n\n* `reject: []` : allows you to add all attributes to `::abyme_attributes`, excepted the ones specified.\n```ruby\n  abymize :association, reject: [:password]\n```\n\n* `options: {}` : [the same options] you may pass to the `accepts_nested_attributes` method (see [this link](https://api.rubyonrails.org/v6.1.0/classes/ActiveRecord/NestedAttributes/ClassMethods.html) for details)\n```ruby\n  abyme_for :association, limit: 3, allow_destroy: false\n```\n\n#### ::abyme_attributes\nReturns a hash to the right format to be included in the `strong params` on the controller side. For a `Project` model with nested `:tasks` :\n```ruby\n  Project.abyme_attributes\n  # =\u003e {tasks_attributes: [:title, :description, :id, :_destroy]}\n```\n\n### Controller\n#### #abyme_attributes\nInfers the name of the resource from the controller name, and calls the `::abyme_attributes` method on it. Hence, in your `ProjectsController` :\n```ruby\n  def project_params\n    params.require(:project).permit(:title, :description, abyme_attributes)\n  end\n```\n\n### Views\n\n#### #abyme_for(:association, options = {}, \u0026block)\nThis is the container for all your nested fields. It takes the symbolized association as a parameter, along with options, and an optional block to specify any layout you may wish for the different parts of the `abyme` builder. \n\n💡 Please note an id is automatically added to this element, which value is : `abyme--association_name`.\n\n💡  If you don't pass a block, `records`, `new_records` and `add_association` will be called and will appear in this order in your layout.\n* `partial: ` : allows you to indicate a custom partial path for both `records` and `new_records`\n```ruby\n  \u003c%= f.abyme_for(:tasks, partial: 'projects/task_fields') do |abyme| %\u003e\n    \u003c%= abyme.records %\u003e\n    \u003c%= abyme.new_records %\u003e\n    \u003c%= add_associated_record %\u003e\n  \u003c% end %\u003e\n```\n* `limit: ` : allows you to limit the number of new fields that can be created through JS. If you need to limit the number of associations in database, you will need to add validations. You can also pass an option [in your model as well](https://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html#method-i-accepts_nested_attributes_for).\n```ruby\n  \u003c%= f.abyme_for(:tasks, limit: 5) do |abyme| %\u003e\n    # Beyond 5 tasks, the add button won't add any more fields. See events section below to see how to handle the 'abyme:limit-reached' event\n    \u003c%= abyme.records %\u003e\n    \u003c%= abyme.new_records %\u003e\n    \u003c%= add_associated_record %\u003e\n  \u003c% end %\u003e\n```\n* `min_count: ` : by default, there won't be any blank fields added on page load. By passing a `min_count` option, you can set how many empty fields should appear in the form.\n```ruby\n  \u003c%= f.abyme_for(:tasks, min_count: 1) do |abyme| %\u003e\n    # 1 blank task will automatically be added to the form.\n    \u003c%= abyme.records %\u003e\n    \u003c%= abyme.new_records %\u003e\n    \u003c%= add_associated_record %\u003e\n  \u003c% end %\u003e\n```\n\n* `locals: {}` : allows you to pass some arbitrary variables to your partial.\n```ruby\n\u003c%= f.abyme_for(:comments, locals: {count: 0}) %\u003e\n```\nThe `count` variable will be available in `_comment_fields.html.erb` and equal 0 for both new and persisted records. If you need to differentiate between both, you can pass the same option to either #records and #new_records (see below)\n\n*If you're not passing a block*, the `abyme_for` method can take a few additional options:\n* `button_text: ` this will set the `add_association` button text to the string of your choice.\n\n💡 All options that should be passed to either `records` or `new_records` below can be passed here and will be passed down.\n\n#### #records\nA few options can be passed to `abyme.records`:\n* `collection:` : allows you to pass a collection of your choice to only display specific objects.\n```ruby\n  \u003c%= f.abyme_for(:tasks) do |abyme| %\u003e\n    \u003c%= abyme.records(collection: @project.tasks.where(done: false)) %\u003e\n    \u003c%= abyme.new_records %\u003e\n    \u003c%= add_associated_record %\u003e\n  \u003c% end %\u003e\n```\n* `order:` : allows you to pass an ActiveRecord `order` method to sort your instances the way you want.\n```ruby\n  \u003c%= f.abyme_for(:tasks) do |abyme| %\u003e\n    \u003c%= abyme.records(order: { created_at: :asc }) %\u003e\n    \u003c%= abyme.new_records %\u003e\n    \u003c%= add_associated_record %\u003e\n  \u003c% end %\u003e\n```\n* `partial:` : allows you to indicate a custom partial, if one has not already been passed to `abyme_for`.\n```ruby\n  \u003c%= f.abyme_for(:tasks) do |abyme| %\u003e\n    \u003c%= abyme.records %\u003e\n    \u003c%= abyme.new_records(partial: 'projects/task_fields') %\u003e\n    \u003c%= add_associated_record %\u003e\n  \u003c% end %\u003e\n```\n* `fields_html:` : gives you the possibility to add any HTML attribute you may want to each set of fields. By default, an `abyme--fields` and an `singular_association-fields` class are already present.\n```ruby\n  \u003c%= f.abyme_for(:tasks) do |abyme| %\u003e\n    \u003c%= abyme.records(fields_html: { class: \"some-class\" }) %\u003e\n    # Every set of persisted fields will have these 3 classes : 'abyme--fields', 'task-fields', and 'some-class'\n    \u003c%= abyme.new_records %\u003e\n    \u003c%= add_associated_record %\u003e\n  \u003c% end %\u003e\n```\n* `wrapper_html:` : gives you the possibility to add any HTML attribute you may want to the wrapper containing all persisted fields.\n```ruby\n  \u003c%= f.abyme_for(:tasks) do |abyme| %\u003e\n    \u003c%= abyme.records(wrapper_html: { class: \"persisted-records\" }) %\u003e\n    # The wrapper containing all persisted task fields will have an id \"abyme-tasks-wrapper\" and a class \"persisted-records\"\n    \u003c%= abyme.new_records %\u003e\n    \u003c%= add_associated_record %\u003e\n  \u003c% end %\u003e\n```\n* `locals: {}` : allows you to pass some arbitrary variables to your partial. When passed to either #records or #new_records, the value will be different depending on whether the record for which the partial is called is persisted or not\n```ruby\n\u003c%= f.abyme_for(:tasks) do |abyme| %\u003e\n  \u003c%= abyme.records(locals: {count: 1}) %\u003e\n  \u003c%= abyme.new_records(locals: {count: 2} %\u003e\n  \u003c%= add_associated_record(content: 'Add task' %\u003e\n\u003c% end %\u003e\n```\n\nIn `_task_fields.html.erb`, if the record has been dynamically added with the \"Add\" button, the `count`variable will be equal to 2. \nIf the record has been loaded from existing associations, it will equal 1.\n\n#### #new_records\nHere are the options that can be passed to `abyme.new_records`:\n* `position:` : allows you to specify whether new fields added dynamically should go at the top or at the bottom. `:end` is the default value.\n```ruby\n  \u003c%= f.abyme_for(:tasks) do |abyme| %\u003e\n    \u003c%= abyme.records %\u003e\n    \u003c%= abyme.new_records(position: :start) %\u003e\n    \u003c%= add_associated_record %\u003e\n  \u003c% end %\u003e\n```\n* `partial:` : same as `#records`\n* `fields_html:` : same as `#records`\n* `wrapper_html:` : same as `#records`\n* * `locals:` : same as `#records`\n\n#### #add_associated_record, #remove_associated_record\nThese 2 methods behave the same. Here are their options :\n* `tag:` : allows you to specify a tag of your choosing, like `:a`, or `:div`. Default is `:button`.\n* `content:` : the text to display inside the element. Default is `Add association_name`\n* `html:` : gives you the possibility to add any HTML attribute you may want to the element.\n```ruby\n  \u003c%= f.abyme_for(:tasks) do |abyme| %\u003e\n    # ...\n    \u003c%= add_associated_record(tag: :a, content: \"Add a super task\", html: {id: \"add-super-task\"}) %\u003e\n  \u003c% end %\u003e\n```\n\nAs you may have seen above, you can also pass a block to the method to give it whatever HTML content you want :\n```ruby\n  \u003c%= f.abyme_for(:tasks) do |abyme| %\u003e\n    # ...\n    \u003c%= add_associated_record(tag: :div, html: {id: \"add-super-task\", class: \"flex\"}) do %\u003e\n      \u003ci class=\"fas fa-plus\"\u003e\u003c/i\u003e\n      \u003ch2\u003eAdd a super task\u003c/h2\u003e\n    \u003c% end %\u003e\n  \u003c% end %\u003e\n```\n\n## Events\nThis part is still a work in progress and subject to change. We're providing some basic self-explanatory events to attach to. These are emitted by the main container (created by the `abyme_for` method).\n\nWe're currently thinking about a way to attach to these via Stimulus. Coming soon !\n\n### Lifecycle events\n* `abyme:before-add`\n* `abyme:after-add`\n* `abyme:before-remove`\n* `abyme:after-remove`\n```javascript\ndocument.getElementById('abyme--tasks').addEventListener('abyme:before-add', yourCallback)\n```\n\n### Other events\n* `abyme:limit-reached`\n```javascript\nconst tasksContainer = document.getElementById('abyme--tasks');\ntasksContainer.addEventListener('abyme:limit-reached', () =\u003e { \n  alert('You reached the max number of tasks !')\n});\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/eki-177/abyme.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feki-177%2Fabyme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feki-177%2Fabyme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feki-177%2Fabyme/lists"}