{"id":14955942,"url":"https://github.com/khcr/snaptable","last_synced_at":"2025-10-24T09:30:24.158Z","repository":{"id":29938705,"uuid":"33485007","full_name":"khcr/snaptable","owner":"khcr","description":"A gem that generate HTML tables from your models in order to display them in your admin views.","archived":false,"fork":false,"pushed_at":"2022-05-01T21:24:56.000Z","size":96,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-29T09:11:32.732Z","etag":null,"topics":["html","html-tables","rails","ruby","search","sort","tables"],"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/khcr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-06T14:04:44.000Z","updated_at":"2021-11-14T16:47:52.000Z","dependencies_parsed_at":"2022-09-07T06:12:10.900Z","dependency_job_id":null,"html_url":"https://github.com/khcr/snaptable","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khcr%2Fsnaptable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khcr%2Fsnaptable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khcr%2Fsnaptable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khcr%2Fsnaptable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khcr","download_url":"https://codeload.github.com/khcr/snaptable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237944037,"owners_count":19391588,"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":["html","html-tables","rails","ruby","search","sort","tables"],"created_at":"2024-09-24T13:12:03.465Z","updated_at":"2025-10-24T09:30:23.814Z","avatar_url":"https://github.com/khcr.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Snaptable\n\nA gem that generate HTML tables from your models in order to display them in your admin views. It supports pagination, sorting and searching. It is also possible to customize the tables.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'snaptable'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install snaptable\n\nInclude the assets:\n\n```css\n# application.css\n/*\n *= require_self\n *= require_tree .\n *= require snaptable\n */\n\n```\n\n```js\n# application.js\n//= require_tree .\n//= require snaptable\n```\n\n## Usage\n\n### Basic table\n\nIn your controller, instantiate a new `Table` with minimum two arguments: the controller itself and the model to use.\n\n```ruby\ndef index\n  @table = Table.new(self, Article)\nend\n```\n\nThen, in order to enable sorting, call the method `respond` on the table.\n\n```ruby\ndef index\n  @table = Table.new(self, Article)\n  @table.respond\nend\n```\n\nFinally, in your view, generate the table where you wish.\n\n```html\n\u003cdiv\u003e\n  \u003c%= @table.present %\u003e\n\u003c/div\u003e\n```\n\nThe elements in the table are clickable. Click on an element and use the links above the table to edit or destroy it. If you double-click, you are directly redirect to the edit page. Furthermore, the columns are sortable. Click on a label to sort the data by a column.\n\n### Options\n\nYou can customize the table when you instantiate it. Pass you own collection in the third argument.\n\n```ruby\n@articles = Article.last(3)\nTable.new(self, Article, @articles)\n```\n\nPass the options in the fourth argument. Here is a list:\n\n* buttons [true]: enable the buttons above the table to add, edit or destroy an element.\n* search [false]: enable searching. Add a search field above the table.\n\n```ruby\nTable.new(self, Article, nil, { search: true, buttons: false })\n```\n\nYou can also configure the table in the view. The `present` method takes a single named argument to let you add a custom buttons bar. Pass the name of a partial to the parameter `buttons` and the content will be added above the table.\n\n```erb\n\u003cdiv\u003e\n  \u003c%= @table.present(buttons: \"my_custom_partial\") %\u003e\n\u003c/div\u003e\n```\nTo help you build your custom buttons header, you are provided two helper methods for each of the possible actions (add, show, edit, delete):\n\n* `#{action}_button` returns the HTML code to display the button for the desired action, e.g `add_button`.\n* `#{action}_button?` returns if the user is allowed to see the desired button, e.g. `delete_button?`.\n\n```erb\n\u003cdiv id=\"custom-buttons\"\u003e\n  \u003cp\u003eThis is my custom table header !\u003c/p\u003e\n  \u003c%= add_button if add_button? %\u003e\n\u003cdiv\u003e\n```\n\nNotice that you can customize the buttons header application-wide. With the following options, you decide which buttons are displayed by default.\n\n```ruby\nSnaptable.add_button = true\nSnaptable.edit_button = true\nSnaptable.delete_button = true\nSnaptable.show_button = false\n```\n\n### Custom class\n\nIf you need more control on the displayed fields or on the search, you can easily create your own table.\nCreate a directory `app/tables`. Then create a file `my_model_table.rb`. Inside declare a class `MyModelTable` that inherits from `BaseTable`.\nYou must necessarily write a method called `model` that returns the model to use for your table.\n\n```ruby\n# article_table.rb\nclass ArticleTable \u003c BaseTable\n\n  def model\n    Article\n  end\n\nend\n```\n\nFrom that point, you have a working table, but it acts exactly the same than the basic table. You have few possibilities to change the behavior.\nIf you want to change the table's columns, write a method `attributes` that returns an array of the model's attributes you want to display. It supports associations by allowing you to put a hash.\n\n```ruby\ndef attributes\n  [:title, :content, { user: :name }]\nend\n```\n\nYou can also change how the URL to edit and delete an element is generated. By default, it uses the element's id, but you can specify an other attribute. Write a method `url` that returns an attribute.\n\n```ruby\ndef url\n  :slug\nend\n```\n\nBy default, the search is done on the string fields of the model. If you want to search on the associations, create a module `Search` inside the class. Then declare a method `self.fields` that returns a hash and `self.associations` that returns an array. Be careful, the search is only possible on string fields.\n\n```ruby\nclass ArticleTable \u003c BaseTable\n\n  def model\n    Article\n  end\n\n  def attributes\n    [:title, :content, { user: :name }]\n  end\n\n  def url\n    :slug\n  end\n\n  module Search\n\n    def self.associations\n      [:user, :category]\n    end\n\n    def self.fields\n      { articles: [:title, :content], users: [:name, :email], categories: [:name] }\n    end\n\n  end\nend\n```\n\n### Multiple tables\n\nSnaptable supports multiple tables on the same page. However, if you want sorting for your tables to work, then type the following in the controller:\n\n```ruby\ndef index\n  @user_table = UserTable.new(self)\n  @group_table = GroupTable.new(self)\n  Snaptable.respond_with(self, @user_table, @group_table)\nend\n```\n\n### Enums\n\nThe gem supports enum's type in your model. If it detects a column that is an enum, it will automatically looks for the localized path `#{model.model_name.singular}.#{enum.pluralize}.#{enum_value}`. For example: `member.statuses.active`.\n\n### i18n\n\nTo display date \u0026 time columns, the gem uses a format named `snaptable`. You can easily override it in your localization file:\n\n```yml\n# en.yml\n\ntime:\n  format:\n    snaptable: \"%m.d.%y %H:%M\"\n\n```\n\nSee the [localization files](config/locales) to see all the keys you can override.\n\n### Gotchas\n\nIf you're using Postgresql, array types and want to enable searching, then you must create a custom table and specify the fields to search (see above). You must exclude the array columns from the search or it will raise an error.\n\n### Permission\n\nif you want to use the `adeia` gem which provides a permission system:\n\n```ruby\n# initializers/snaptable.rb\nSnaptable.use_permission = true\n```\n\n## Contributing\n\n1. Fork it ( https://github.com/khcr/snaptable/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhcr%2Fsnaptable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhcr%2Fsnaptable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhcr%2Fsnaptable/lists"}