Gem Version Gem Downloads Linters Specs

A compact and composable dashboard component for Ruby.

Main features:

• a Rack app that can be mounted in any Rack-enabled framework or used standalone;
• structured with plugins also for main components that can be replaced with little effort;
• routing is provided by Roda which is small and performant;
• views are Phlex components, so plain Ruby objects for views, no assets are needed.

Please ⭐ if you like it.

screenshot

• Add to your Gemfile: gem 'tiny_admin', '~> 0.10'
• Mount the app in a route (check some examples with: Hanami, Rails, Roda and standalone in extra)
  • in Rails, update config/routes.rb: mount TinyAdmin::Router => '/admin'
• Configure the dashboard using TinyAdmin.configure and/or TinyAdmin.configure_from_file with a YAML config file (see configuration below):

TinyAdmin.configure do |settings|
 settings.root = {
 title: 'Home',
 page: Admin::PageRoot
 }
end

Plugins available:

• 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.

• NoAuth: no authentication.

Plugins available:

• Authorization: base class to provide an authorization per action, the host application should inherit from it and override the class method allowed?.

Plugin available:

• ActiveRecordRepository: isolates the query layer to expose the resources in the admin interface.

Pages available:

• Root: define how to present the content in the main page of the interface;
• Content: define how to present page with inline content;
• PageNotFound: define how to present pages not found;
• RecordNotFound: define how to present record not found page;
• SimpleAuthLogin: define how to present the login form for SimpleAuth plugin;
• Index: define how to present a collection of items;
• Show: define how to present the details of an item.

Components available:

• FiltersForm: define how to present the filters form in the resource collection pages;
• Flash: define how to present the flash messages;
• Head: define how to present the Head tag;
• Navbar: define how to present the navbar (the default one uses the Bootstrap structure);
• Pagination: define how to present the pagination of a collection.

TinyAdmin can be configured using a YAML file and/or programmatically. See extra folder for some usage examples.

The following options are supported:

root (Hash): define the root section of the admin, properties:

• title (String): root section's title;
• page (String): a view object to render;
• redirect (String): alternative to page option - redirects to a specific slug;
• widgets (Array): list of widgets (as View components) to present.

📚 Wiki Root page available

Example:

root:
 title: MyAdmin
 redirect: posts
 widgets:
 - LatestAuthorsWidget
 - LatestPostsWidget

helper_class (String): class or module with helper methods, used for attributes' formatters.

📚 Wiki Helper methods page available

page_not_found (String): a view object to render when a missing page is requested.

record_not_found (String): a view object to render when a missing record is requested.

style_links (Array of hashes): list of styles files to include, properties:

• href (String): URL for the style file;
• rel (String): type of style file.

scripts (Array of hashes): list of scripts to include, properties:

• src (String): source URL for the script.

extra_styles (String): inline CSS styles.

📚 Wiki Styles and scripts page available

authentication (Hash): define the authentication method, properties:

• plugin (String): a plugin class to use (ex. TinyAdmin::Plugins::SimpleAuth);
• password (String): a password hash used by SimpleAuth plugin (generated with Digest::SHA512.hexdigest("some password")).

📚 Wiki Authentication page available

Example:

authentication:
 plugin: TinyAdmin::Plugins::SimpleAuth
 password: 'f1891cea80fc05e433c943254c6bdabc159577a02a7395dfebbfbc4f7661d4af56f2d372131a45936de40160007368a56ef216a30cb202c66d3145fd24380906'

authorization_class (String): a plugin class to use;

📚 Wiki Authentication page available

sections (Array of hashes): define the admin sections, properties:

• slug (String): section reference identifier;
• name (String): section's title;
• type (String): the type of section: content, page, resource or url;
• widgets (Array): list of widgets (as View components) to present;
• other properties depends on the section's type.

📚 Wiki Pages page available

For content sections:

• content (String): the HTML content to present.

Example:

slug: test-content
name: Test content
type: content
content: >
 <h1>Test content!</h1>
 <p>Some test content</p>
widgets:
 - LatestAuthorsWidget
 - LatestPostsWidget

For url sections:

• url (String): the URL to load when clicking on the section's menu item;
• options (Hash): properties:
  • target (String): link target attributes (ex. _blank).

Example:

slug: google
name: Google.it
type: url
url: https://www.google.it
options:
 target: '_blank'

For page sections:

• page (String): a view object to render.

Example:

slug: stats
name: Stats
type: page
page: Admin::Stats

For resource sections:

• model (String): the class to use to fetch the data on an item of a collection;
• repository (String): the class to get the properties related to the model;

📚 Wiki Repository page available

• index (Hash): collection's action options (see below);
• show (Hash): detail's action options (see below);
• collection_actions (Array of hashes): custom collection's actions;
• member_actions (Array of hashes): custom details's actions;
• widgets (Array): list of widgets (as View components) to present;
• only (Array of strings): list of supported actions (ex. index);
• options (Array of strings): resource options (ex. hidden).

Example:

slug: posts
name: Posts
type: resource
model: Post

📚 Wiki Resource index page available

The Index hash supports the following options:

• attributes (Array): fields to expose in the resource list page;
• filters (Array): filter the current listing;
• links (Array): custom member actions to expose for each list's entry (defined in member_actions);
• pagination (Integer): max pages size;
• sort (Array): sort options to pass to the listing query.

Example:

 index:
 sort:
 - id DESC
 pagination: 10
 attributes:
 - id
 - author: call, name
 - position: round, 1
 - field: author_id
 header: The author
 link_to: authors
 call: author, name
 filters:
 - title
 - field: state
 type: select
 values:
 - published
 - draft
 - archived
 links:
 - show
 - author_posts
 - csv_export

📚 Wiki Resource show page available

The Show hash supports the following options:

• attributes (Array): fields to expose in the resource details page.

Example:

 show:
 attributes:
 # Expose the id column
 - id
 # Expose the title column, calling `downcase` support method
 - title: downcase
 # Expose the category column, calling `upcase` support method
 - category: upcase
 # Expose the position column, calling `format` support method with argument %f
 - position: format, %f
 # Expose the position created_at, calling `strftime` support method with argument %Y%m%d %H:%M
 - created_at: strftime, %Y%m%d %H:%M
 # Expose the author_id column, with a custom header label, linked to authors section and calling author.name to get the value
 - field: author_id
 header: The author
 link_to: authors
 call: author, name
 widgets:
 - LatestAuthorsWidget
 - LatestPostsWidget

# config/initializers/tiny_admin.rb
config = Rails.root.join('config/tiny_admin.yml').to_s
TinyAdmin.configure_from_file(config)
# Change some settings programmatically
TinyAdmin.configure do |settings|
 settings.authentication[:password] = Digest::SHA512.hexdigest('changeme')
end

# config/tiny_admin.yml
---
authentication:
 plugin: TinyAdmin::Plugins::SimpleAuth
 # password: 'f1891cea80fc05e433c943254c6bdabc159577a02a7395dfebbfbc4f7661d4af56f2d372131a45936de40160007368a56ef216a30cb202c66d3145fd24380906'
root:
 title: Test Admin
 widgets:
 - LatestAuthorsWidget
 - LatestPostsWidget
 # page: RootPage
helper_class: AdminHelper
page_not_found: PageNotFound
record_not_found: RecordNotFound
sections:
 - slug: google
 name: Google.it
 type: url
 url: https://www.google.it
 options:
 target: _blank
 - slug: sample
 name: Sample page
 type: page
 page: SamplePage
 - slug: authors
 name: Authors
 type: resource
 model: Author
 collection_actions:
 - sample_col: SampleCollectionAction
 member_actions:
 - sample_mem: SampleMemberAction
 - slug: posts
 name: Posts
 type: resource
 model: Post
 index:
 pagination: 5
 attributes:
 - id
 - title
 - field: author_id
 link_to: authors
 - category: upcase
 - state: downcase
 - published
 - position: round, 1
 - dt: to_date
 - field: created_at
 converter: AdminUtils
 method: datetime_formatter
 - updated_at: strftime, %Y%m%d %H:%M
 filters:
 - title
 - author_id
 - field: category
 type: select
 values:
 - news
 - sport
 - tech
 - published
 - dt
 - created_at
 show:
 attributes:
 - id
 - title
 - description
 - field: author_id
 link_to: authors
 - category
 - published
 - position: format, %f
 - dt
 - created_at
style_links:
 - href: /bootstrap.min.css
 rel: stylesheet
scripts:
 - src: /bootstrap.bundle.min.js
extra_styles: >
 .navbar {
 background-color: var(--bs-cyan);
 }
 .main-content {
 background-color: var(--bs-gray-100);
 }
 .main-content a {
 text-decoration: none;
 }

If you use this component just star it. A developer is more motivated to improve a project when there is some interest.

Or consider offering me a coffee, it's a small thing but it is greatly appreciated: about me.

• Mattia Roccoberton: author

The gem is available as open source under the terms of the MIT License.