{"id":15064559,"url":"https://github.com/blocknotes/tiny_admin","last_synced_at":"2025-04-10T12:23:08.406Z","repository":{"id":151756396,"uuid":"624758566","full_name":"blocknotes/tiny_admin","owner":"blocknotes","description":"A compact and composable dashboard component for Ruby","archived":false,"fork":false,"pushed_at":"2024-04-20T08:28:59.000Z","size":2045,"stargazers_count":13,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T11:11:19.742Z","etag":null,"topics":["rails","roda","ruby","ruby-on-rails"],"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/blocknotes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["blocknotes"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2023-04-07T07:29:01.000Z","updated_at":"2024-12-09T21:48:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"c29ad476-c34a-4ff1-a6be-1d677ae211f0","html_url":"https://github.com/blocknotes/tiny_admin","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocknotes%2Ftiny_admin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocknotes%2Ftiny_admin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocknotes%2Ftiny_admin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocknotes%2Ftiny_admin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blocknotes","download_url":"https://codeload.github.com/blocknotes/tiny_admin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248217110,"owners_count":21066633,"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":["rails","roda","ruby","ruby-on-rails"],"created_at":"2024-09-25T00:20:32.574Z","updated_at":"2025-04-10T12:23:08.361Z","avatar_url":"https://github.com/blocknotes.png","language":"Ruby","readme":"# Tiny Admin\n\n[![Gem Version](https://badge.fury.io/rb/tiny_admin.svg)](https://badge.fury.io/rb/tiny_admin)\n[![Gem Downloads](https://badgen.net/rubygems/dt/tiny_admin)](https://rubygems.org/gems/tiny_admin)\n[![Linters](https://github.com/blocknotes/tiny_admin/actions/workflows/linters.yml/badge.svg)](https://github.com/blocknotes/tiny_admin/actions/workflows/linters.yml)\n[![Specs](https://github.com/blocknotes/tiny_admin/actions/workflows/tests.yml/badge.svg)](https://github.com/blocknotes/tiny_admin/actions/workflows/tests.yml)\n\nA compact and composable dashboard component for Ruby.\n\nMain features:\n- a Rack app that can be mounted in any Rack-enabled framework or used standalone;\n- structured with plugins also for main components that can be replaced with little effort;\n- routing is provided by Roda which is small and performant;\n- views are Phlex components, so plain Ruby objects for views, no assets are needed.\n\nPlease ⭐ if you like it.\n\n![screenshot](extra/screenshot.png)\n\n## Install\n\n- Add to your Gemfile: `gem 'tiny_admin', '~\u003e 0.10'`\n- Mount the app in a route (check some examples with: Hanami, Rails, Roda and standalone in [extra](extra))\n  + in Rails, update _config/routes.rb_: `mount TinyAdmin::Router =\u003e '/admin'`\n- Configure the dashboard using `TinyAdmin.configure` and/or `TinyAdmin.configure_from_file` with a YAML config file (see [configuration](#configuration) below):\n\n```rb\nTinyAdmin.configure do |settings|\n  settings.root = {\n    title: 'Home',\n    page: Admin::PageRoot\n  }\nend\n```\n\n## Plugins and components\n\n### Authentication\n\nPlugins available:\n\n- **SimpleAuth**: a session authentication based on Warden (`warden` gem must be included in the Gemfile) using a password hash provided via config or via environment variable (`ADMIN_PASSWORD_HASH`). _Disclaimer: this plugin is provided as example, if you need a secure authentication I suggest to create your own._\n\n- **NoAuth**: no authentication.\n\n### Authorization\n\nPlugins available:\n\n- **Authorization**: base class to provide an authorization per action, the host application should inherit from it and override the class method `allowed?`.\n\n### Repository\n\nPlugin available:\n\n- **ActiveRecordRepository**: isolates the query layer to expose the resources in the admin interface.\n\n### View pages\n\nPages available:\n\n- **Root**: define how to present the content in the main page of the interface;\n- **Content**: define how to present page with inline content;\n- **PageNotFound**: define how to present pages not found;\n- **RecordNotFound**: define how to present record not found page;\n- **SimpleAuthLogin**: define how to present the login form for SimpleAuth plugin;\n- **Index**: define how to present a collection of items;\n- **Show**: define how to present the details of an item.\n\n### View components\n\nComponents available:\n\n- **FiltersForm**: define how to present the filters form in the resource collection pages;\n- **Flash**: define how to present the flash messages;\n- **Head**: define how to present the Head tag;\n- **Navbar**: define how to present the navbar (the default one uses the Bootstrap structure);\n- **Pagination**: define how to present the pagination of a collection.\n\n## Configuration\n\nTinyAdmin can be configured using a YAML file and/or programmatically.\nSee [extra](extra) folder for some usage examples.\n\nThe following options are supported:\n\n`root` (Hash): define the root section of the admin, properties:\n\n- `title` (String): root section's title;\n- `page` (String): a view object to render;\n- `redirect` (String): alternative to _page_ option - redirects to a specific slug;\n- `widgets` (Array): list of widgets (as View components) to present.\n\n\u003e 📚 [Wiki Root page](https://github.com/blocknotes/tiny_admin/wiki/Root) available\n\nExample:\n\n```yml\nroot:\n  title: MyAdmin\n  redirect: posts\n  widgets:\n    - LatestAuthorsWidget\n    - LatestPostsWidget\n```\n\n`helper_class` (String): class or module with helper methods, used for attributes' formatters.\n\n\u003e 📚 [Wiki Helper methods page](https://github.com/blocknotes/tiny_admin/wiki/Helper-methods) available\n\n`page_not_found` (String): a view object to render when a missing page is requested.\n\n`record_not_found` (String): a view object to render when a missing record is requested.\n\n`style_links` (Array of hashes): list of styles files to include, properties:\n\n- `href` (String): URL for the style file;\n- `rel` (String): type of style file.\n\n`scripts` (Array of hashes): list of scripts to include, properties:\n\n- `src` (String): source URL for the script.\n\n`extra_styles` (String): inline CSS styles.\n\n\u003e 📚 [Wiki Styles and scripts page](https://github.com/blocknotes/tiny_admin/wiki/Styles-and-scripts) available\n\n`authentication` (Hash): define the authentication method, properties:\n\n- `plugin` (String): a plugin class to use (ex. `TinyAdmin::Plugins::SimpleAuth`);\n- `password` (String): a password hash used by _SimpleAuth_ plugin (generated with `Digest::SHA512.hexdigest(\"some password\")`).\n\n\u003e 📚 [Wiki Authentication page](https://github.com/blocknotes/tiny_admin/wiki/Authentication) available\n\nExample:\n\n```yml\nauthentication:\n  plugin: TinyAdmin::Plugins::SimpleAuth\n  password: 'f1891cea80fc05e433c943254c6bdabc159577a02a7395dfebbfbc4f7661d4af56f2d372131a45936de40160007368a56ef216a30cb202c66d3145fd24380906'\n```\n\n`authorization_class` (String): a plugin class to use;\n\n\u003e 📚 [Wiki Authentication page](https://github.com/blocknotes/tiny_admin/wiki/Authorization) available\n\n`sections` (Array of hashes): define the admin sections, properties:\n\n- `slug` (String): section reference identifier;\n- `name` (String): section's title;\n- `type` (String): the type of section: `content`, `page`, `resource` or `url`;\n- `widgets` (Array): list of widgets (as View components) to present;\n- other properties depends on the section's type.\n\n\u003e 📚 [Wiki Pages page](https://github.com/blocknotes/tiny_admin/wiki/Pages) available\n\nFor _content_ sections:\n\n- `content` (String): the HTML content to present.\n\nExample:\n\n```yml\nslug: test-content\nname: Test content\ntype: content\ncontent: \u003e\n  \u003ch1\u003eTest content!\u003c/h1\u003e\n  \u003cp\u003eSome test content\u003c/p\u003e\nwidgets:\n  - LatestAuthorsWidget\n  - LatestPostsWidget\n```\n\nFor _url_ sections:\n\n- `url` (String): the URL to load when clicking on the section's menu item;\n- `options` (Hash): properties:\n  + `target` (String): link _target_ attributes (ex. `_blank`).\n\nExample:\n\n```yml\nslug: google\nname: Google.it\ntype: url\nurl: https://www.google.it\noptions:\n  target: '_blank'\n```\n\nFor _page_ sections:\n\n- `page` (String): a view object to render.\n\nExample:\n\n```yml\nslug: stats\nname: Stats\ntype: page\npage: Admin::Stats\n```\n\nFor _resource_ sections:\n\n- `model` (String): the class to use to fetch the data on an item of a collection;\n- `repository` (String): the class to get the properties related to the model;\n\n\u003e 📚 [Wiki Repository page](https://github.com/blocknotes/tiny_admin/wiki/Repository) available\n\n- `index` (Hash): collection's action options (see below);\n- `show` (Hash): detail's action options (see below);\n- `collection_actions` (Array of hashes): custom collection's actions;\n- `member_actions` (Array of hashes): custom details's actions;\n- `widgets` (Array): list of widgets (as View components) to present;\n- `only` (Array of strings): list of supported actions (ex. `index`);\n- `options` (Array of strings): resource options (ex. `hidden`).\n\nExample:\n\n```yml\nslug: posts\nname: Posts\ntype: resource\nmodel: Post\n```\n\n#### Resource index options\n\n\u003e 📚 [Wiki Resource index page](https://github.com/blocknotes/tiny_admin/wiki/Resource-index) available\n\nThe Index hash supports the following options:\n\n- `attributes` (Array): fields to expose in the resource list page;\n- `filters` (Array): filter the current listing;\n- `links` (Array): custom member actions to expose for each list's entry (defined in _member_actions_);\n- `pagination` (Integer): max pages size;\n- `sort` (Array): sort options to pass to the listing query.\n\nExample:\n\n```yml\n    index:\n      sort:\n        - id DESC\n      pagination: 10\n      attributes:\n        - id\n        - author: call, name\n        - position: round, 1\n        - field: author_id\n          header: The author\n          link_to: authors\n          call: author, name\n      filters:\n        - title\n        - field: state\n          type: select\n          values:\n            - published\n            - draft\n            - archived\n      links:\n        - show\n        - author_posts\n        - csv_export\n```\n\n#### Resource show options\n\n\u003e 📚 [Wiki Resource show page](https://github.com/blocknotes/tiny_admin/wiki/Resource-show) available\n\nThe Show hash supports the following options:\n\n- `attributes` (Array): fields to expose in the resource details page.\n\nExample:\n\n```yml\n    show:\n      attributes:\n        # Expose the id column\n        - id\n        # Expose the title column, calling `downcase` support method\n        - title: downcase\n        # Expose the category column, calling `upcase` support method\n        - category: upcase\n        # Expose the position column, calling `format` support method with argument %f\n        - position: format, %f\n        # Expose the position created_at, calling `strftime` support method with argument %Y%m%d %H:%M\n        - created_at: strftime, %Y%m%d %H:%M\n        # Expose the author_id column, with a custom header label, linked to authors section and calling author.name to get the value\n        - field: author_id\n          header: The author\n          link_to: authors\n          call: author, name\n      widgets:\n        - LatestAuthorsWidget\n        - LatestPostsWidget\n```\n\n### Sample\n\n```rb\n# config/initializers/tiny_admin.rb\n\nconfig = Rails.root.join('config/tiny_admin.yml').to_s\nTinyAdmin.configure_from_file(config)\n\n# Change some settings programmatically\nTinyAdmin.configure do |settings|\n  settings.authentication[:password] = Digest::SHA512.hexdigest('changeme')\nend\n```\n\n```yml\n# config/tiny_admin.yml\n---\nauthentication:\n  plugin: TinyAdmin::Plugins::SimpleAuth\n  # password: 'f1891cea80fc05e433c943254c6bdabc159577a02a7395dfebbfbc4f7661d4af56f2d372131a45936de40160007368a56ef216a30cb202c66d3145fd24380906'\nroot:\n  title: Test Admin\n  widgets:\n    - LatestAuthorsWidget\n    - LatestPostsWidget\n  # page: RootPage\nhelper_class: AdminHelper\npage_not_found: PageNotFound\nrecord_not_found: RecordNotFound\nsections:\n  - slug: google\n    name: Google.it\n    type: url\n    url: https://www.google.it\n    options:\n      target: _blank\n  - slug: sample\n    name: Sample page\n    type: page\n    page: SamplePage\n  - slug: authors\n    name: Authors\n    type: resource\n    model: Author\n    collection_actions:\n      - sample_col: SampleCollectionAction\n    member_actions:\n      - sample_mem: SampleMemberAction\n  - slug: posts\n    name: Posts\n    type: resource\n    model: Post\n    index:\n      pagination: 5\n      attributes:\n        - id\n        - title\n        - field: author_id\n          link_to: authors\n        - category: upcase\n        - state: downcase\n        - published\n        - position: round, 1\n        - dt: to_date\n        - field: created_at\n          converter: AdminUtils\n          method: datetime_formatter\n        - updated_at: strftime, %Y%m%d %H:%M\n      filters:\n        - title\n        - author_id\n        - field: category\n          type: select\n          values:\n            - news\n            - sport\n            - tech\n        - published\n        - dt\n        - created_at\n    show:\n      attributes:\n        - id\n        - title\n        - description\n        - field: author_id\n          link_to: authors\n        - category\n        - published\n        - position: format, %f\n        - dt\n        - created_at\nstyle_links:\n  - href: /bootstrap.min.css\n    rel: stylesheet\nscripts:\n  - src: /bootstrap.bundle.min.js\nextra_styles: \u003e\n  .navbar {\n    background-color: var(--bs-cyan);\n  }\n  .main-content {\n    background-color: var(--bs-gray-100);\n  }\n  .main-content a {\n    text-decoration: none;\n  }\n```\n\n## Do you like it? Star it!\n\nIf you use this component just star it. A developer is more motivated to improve a project when there is some interest.\n\nOr consider offering me a coffee, it's a small thing but it is greatly appreciated: [about me](https://www.blocknot.es/about-me).\n\n## Contributors\n\n- [Mattia Roccoberton](https://blocknot.es/): author\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":["https://github.com/sponsors/blocknotes"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblocknotes%2Ftiny_admin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblocknotes%2Ftiny_admin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblocknotes%2Ftiny_admin/lists"}