Bump to version 0.5.0

Author: Mattia Roccoberton

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 A compact and composable dashboard component for Ruby
 
+## 0.5.0
+
+- feat: customize index entries links
+- feat: support config Objects for sections
+- feat: internal improvements
+
 ## 0.4.0
 
 - feat: introduce a Support class for attributes' formatters

README.md

@@ -16,10 +16,10 @@ Please ⭐ if you like it.
 
 ## Install
 
-- Add to your Gemfile: `gem 'tiny_admin', '~> 0.4'`
+- Add to your Gemfile: `gem 'tiny_admin', '~> 0.5'`
 - 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` (see [configuration](#configuration) below):
+- 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|
@@ -35,32 +35,37 @@ end
 ### Authentication
 
 Plugins available:
-- _SimpleAuth_: 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`);
-- _NoAuth_: no authentication.
+
+- **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.
 
 ### Repository
 
 Plugin available:
-- _ActiveRecordRepository_: isolates the query layer to expose the resources in the admin interface.
+
+- **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;
-- _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.
+
+- **Root**: define how to present the content in the main page of the interface;
+- **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.
+
+- **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
 
@@ -70,9 +75,10 @@ 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;
+
+- `title` (String): root section's title;
+- `page` (String): a view object to render;
+- `redirect` (String): alternative to _page_ option - redirects to a specific slug;
 
 Example:
 
@@ -88,9 +94,21 @@ root:
 
 `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.
+
 `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")`).
+
+- `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")`).
 
 Example:
 
@@ -101,15 +119,17 @@ authentication:
 ```
 
 `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: `url`, `page` or `resource`;
-  - other properties depends on the section's type.
+
+- `slug` (String): section reference identifier;
+- `name` (String): section's title;
+- `type` (String): the type of section: `url`, `page` or `resource`;
+- other properties depends on the section's type.
 
 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`).
+
+- `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:
 
@@ -123,7 +143,8 @@ options:
 ```
 
 For _page_ sections:
-  - `page` (String): a view object to render.
+
+- `page` (String): a view object to render.
 
 Example:
 
@@ -135,14 +156,15 @@ 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;
-  - `index` (Hash): collection's action options;
-  - `show` (Hash): detail's action options;
-  - `collection_actions` (Array of hashes): custom collection's actions;
-  - `member_actions` (Array of hashes): custom details's actions;
-  - `only` (Array of strings): list of supported actions (ex. `index`);
-  - `options` (Array of strings): resource options (ex. `hidden`).
+
+- `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;
+- `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;
+- `only` (Array of strings): list of supported actions (ex. `index`);
+- `options` (Array of strings): resource options (ex. `hidden`).
 
 Example:
 
@@ -153,14 +175,72 @@ type: resource
 model: Post
 ```
 
-`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.
+#### Resource index options
 
-`scripts` (Array of hashes): list of scripts to include, properties:
-  - `src` (String): source URL for the script.
+The Index hash supports the following options:
 
-`extra_styles` (String): inline CSS styles.
+- `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
+
+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
+```
 
 ### Sample
 

lib/tiny_admin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TinyAdmin
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end