Tiny Admin

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.

Install

• 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.configuredo |settings|
settings.root={title: 'Home',page: Admin::PageRoot}end

Plugins and components

Authentication

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.

Authorization

Plugins available:

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

Repository

Plugin available:

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

View pages

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.

View components

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.

Configuration

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: MyAdminredirect: postswidgets:
- 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::SimpleAuthpassword: '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-contentname: Test contenttype: contentcontent: > <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: googlename: Google.ittype: urlurl: https://www.google.itoptions:
target: '_blank'

For page sections:

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

Example:

slug: statsname: Statstype: pagepage: 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: postsname: Poststype: resourcemodel: Post

Resource index options

📚 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 DESCpagination: 10attributes:
- id
- author: call, name
- position: round, 1
- field: author_idheader: The authorlink_to: authorscall: author, namefilters:
- title
- field: statetype: selectvalues:
- published
- draft
- archivedlinks:
- show
- author_posts
- csv_export

Resource show options

📚 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_idheader: The authorlink_to: authorscall: author, namewidgets:
- LatestAuthorsWidget
- LatestPostsWidget

Sample

# config/initializers/tiny_admin.rbconfig=Rails.root.join('config/tiny_admin.yml').to_sTinyAdmin.configure_from_file(config)# Change some settings programmaticallyTinyAdmin.configuredo |settings|
settings.authentication[:password]=Digest::SHA512.hexdigest('changeme')end

# config/tiny_admin.yml
---
authentication:
plugin: TinyAdmin::Plugins::SimpleAuth# password: 'f1891cea80fc05e433c943254c6bdabc159577a02a7395dfebbfbc4f7661d4af56f2d372131a45936de40160007368a56ef216a30cb202c66d3145fd24380906'root:
title: Test Adminwidgets:
- LatestAuthorsWidget
- LatestPostsWidget# page: RootPagehelper_class: AdminHelperpage_not_found: PageNotFoundrecord_not_found: RecordNotFoundsections:
- slug: googlename: Google.ittype: urlurl: https://www.google.itoptions:
target: _blank
- slug: samplename: Sample pagetype: pagepage: SamplePage
- slug: authorsname: Authorstype: resourcemodel: Authorcollection_actions:
- sample_col: SampleCollectionActionmember_actions:
- sample_mem: SampleMemberAction
- slug: postsname: Poststype: resourcemodel: Postindex:
pagination: 5attributes:
- id
- title
- field: author_idlink_to: authors
- category: upcase
- state: downcase
- published
- position: round, 1
- dt: to_date
- field: created_atconverter: AdminUtilsmethod: datetime_formatter
- updated_at: strftime, %Y%m%d %H:%Mfilters:
- title
- author_id
- field: categorytype: selectvalues:
- news
- sport
- tech
- published
- dt
- created_atshow:
attributes:
- id
- title
- description
- field: author_idlink_to: authors
- category
- published
- position: format, %f
- dt
- created_atstyle_links:
- href: /bootstrap.min.cssrel: stylesheetscripts:
- src: /bootstrap.bundle.min.jsextra_styles: > .navbar { background-color: var(--bs-cyan); } .main-content { background-color: var(--bs-gray-100); } .main-content a { text-decoration: none; }

Do you like it? Star it!

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.

Contributors

• Mattia Roccoberton: author

License

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