Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/blocknotes/tiny_admin
A compact and composable dashboard component for Ruby
https://github.com/blocknotes/tiny_admin
rails roda ruby ruby-on-rails
Last synced: 9 days ago
JSON representation
A compact and composable dashboard component for Ruby
- Host: GitHub
- URL: https://github.com/blocknotes/tiny_admin
- Owner: blocknotes
- License: mit
- Created: 2023-04-07T07:29:01.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-20T08:28:59.000Z (9 months ago)
- Last Synced: 2024-12-21T12:50:26.718Z (22 days ago)
- Topics: rails, roda, ruby, ruby-on-rails
- Language: Ruby
- Homepage:
- Size: 1.95 MB
- Stars: 13
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
Awesome Lists containing this project
README
# Tiny Admin
[](https://badge.fury.io/rb/tiny_admin)
[](https://rubygems.org/gems/tiny_admin)
[](https://github.com/blocknotes/tiny_admin/actions/workflows/linters.yml)
[](https://github.com/blocknotes/tiny_admin/actions/workflows/tests.yml)
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](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](#configuration) below):
```rb
TinyAdmin.configure do |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](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](https://github.com/blocknotes/tiny_admin/wiki/Root) available
Example:
```yml
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](https://github.com/blocknotes/tiny_admin/wiki/Helper-methods) 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](https://github.com/blocknotes/tiny_admin/wiki/Styles-and-scripts) 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](https://github.com/blocknotes/tiny_admin/wiki/Authentication) available
Example:
```yml
authentication:
plugin: TinyAdmin::Plugins::SimpleAuth
password: 'f1891cea80fc05e433c943254c6bdabc159577a02a7395dfebbfbc4f7661d4af56f2d372131a45936de40160007368a56ef216a30cb202c66d3145fd24380906'
```
`authorization_class` (String): a plugin class to use;
> 📚 [Wiki Authentication page](https://github.com/blocknotes/tiny_admin/wiki/Authorization) 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](https://github.com/blocknotes/tiny_admin/wiki/Pages) available
For _content_ sections:
- `content` (String): the HTML content to present.
Example:
```yml
slug: test-content
name: Test content
type: content
content: >
Test content!
Some test content
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:
```yml
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:
```yml
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](https://github.com/blocknotes/tiny_admin/wiki/Repository) 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:
```yml
slug: posts
name: Posts
type: resource
model: Post
```
#### Resource index options
> 📚 [Wiki Resource index page](https://github.com/blocknotes/tiny_admin/wiki/Resource-index) 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:
```yml
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
```
#### Resource show options
> 📚 [Wiki Resource show page](https://github.com/blocknotes/tiny_admin/wiki/Resource-show) available
The Show hash supports the following options:
- `attributes` (Array): fields to expose in the resource details page.
Example:
```yml
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
```
### Sample
```rb
# 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
```
```yml
# 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;
}
```
## 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](https://www.blocknot.es/about-me).
## Contributors
- [Mattia Roccoberton](https://blocknot.es/): author
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).