tiny_admin 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d203e48b821f195f95847a646e32787c9ffd953212326f64e65ca09d563ed55e
-  data.tar.gz: a133ad428942d240ec8852e4885e12a51bc6a96f9a4bcf426470180671dddf6f
+  metadata.gz: c3ac2be067ca35c35f40c677c5f9461c5f83e366488a48e6ab50a888f0f22317
+  data.tar.gz: 2289dd33940174e8e614260f96273967ade51f75dc67a04d5e639415c984e65b
 SHA512:
-  metadata.gz: 8955bf003179333debcf4c43dd7091b4d81fc9c1e90a6116119dc33f51b4ab7dca394d90f6f8aa6bb0385339dc5eb07b64bd546f0a92e02497d5c000cc835769
-  data.tar.gz: 5cabb3dc010e73b416068cca3afda56dc07ac7b024c70d734b9409298d2082798a8e5e276d892be81e82dcbfa68bad20360f0d99e4c8e7199a7bdb5067f72124
+  metadata.gz: f4f80d86ac6b30bc29cf8e2f1efe480edefe84907bf5e9b7a3a8c3b3c3750ff59a1f9e609c87090105c0cd31fa22df7aa913858911a455d918633269c27317e7
+  data.tar.gz: 4fe8a75d9e3c0cc3bd756ab247fecb7575049dcec58559bdb7cdb1c58ecb4b6e7de3f8be96c396b0b304134cc75c6058b3cbeafce92cd027413971a99a812c02

data/README.md

@@ -16,10 +16,10 @@ Please ⭐ if you like it.
 
 ## Install
 
-- Add to your Gemfile: `gem 'tiny_admin', '~> 0.3'`
+- 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:
 
@@ -82,9 +88,27 @@ root:
   redirect: posts
 ```
 
+`helper_class` (String): class or module with helper methods, used for attributes' formatters.
+
+`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.
+
 `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:
 
@@ -95,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:
 
@@ -117,7 +143,8 @@ options:
 ```
 
 For _page_ sections:
-  - `page` (String): a view object to render.
+
+- `page` (String): a view object to render.
 
 Example:
 
@@ -129,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:
 
@@ -147,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
 
@@ -175,65 +261,64 @@ end
 ---
 authentication:
   plugin: TinyAdmin::Plugins::SimpleAuth
-  # password: 'f1891cea80fc05e433c943254c6bdabc159577a02a7395df...' <= SHA512
-page_not_found: Admin::PageNotFound
-record_not_found: Admin::RecordNotFound
+  # password: 'f1891cea80fc05e433c943254c6bdabc159577a02a7395dfebbfbc4f7661d4af56f2d372131a45936de40160007368a56ef216a30cb202c66d3145fd24380906'
 root:
-  title: 'Tiny Admin'
-  page: Admin::PageRoot
-  # redirect: posts
+  title: Test Admin
+  # 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: stats
-    name: Stats
+      target: _blank
+  - slug: sample
+    name: Sample page
     type: page
-    page: Admin::Stats
+    page: SamplePage
   - slug: authors
     name: Authors
     type: resource
     model: Author
-    repository: Admin::AuthorsRepo
     collection_actions:
-      - latests: Admin::LatestAuthorsAction
+      - sample_col: SampleCollectionAction
     member_actions:
-      - csv_export: Admin::CsvExportAuthorAction
-    # only:
-    #   - index
-    # options:
-    #   - hidden
+      - sample_mem: SampleMemberAction
   - slug: posts
     name: Posts
     type: resource
     model: Post
     index:
-      sort:
-        - author_id DESC
-      pagination: 15
+      pagination: 5
       attributes:
         - id
         - title
         - field: author_id
           link_to: authors
-        - state
+        - category: upcase
+        - state: downcase
         - published
-        - dt
+        - position: round, 1
+        - dt: to_date
         - field: created_at
-          converter: Admin::Utils
+          converter: AdminUtils
           method: datetime_formatter
+        - updated_at: strftime, %Y%m%d %H:%M
       filters:
         - title
-        - field: state
+        - author_id
+        - field: category
           type: select
           values:
-            - available
-            - unavailable
-            - arriving
+            - news
+            - sport
+            - tech
         - published
+        - dt
+        - created_at
     show:
       attributes:
         - id
@@ -243,7 +328,8 @@ sections:
           link_to: authors
         - category
         - published
-        - state
+        - position: format, %f
+        - dt
         - created_at
 style_links:
   - href: /bootstrap.min.css

data/lib/tiny_admin/actions/basic_action.rb

@@ -5,12 +5,21 @@ module TinyAdmin
     class BasicAction
       include Utils
 
-      attr_reader :params, :path, :repository
-
-      def initialize(repository, path:, params:)
-        @repository = repository
-        @path = path
-        @params = params
+      def attribute_options(options)
+        options&.each_with_object({}) do |field, result|
+          field_data =
+            if field.is_a?(Hash)
+              if field.one?
+                field, method = field.first
+                { field.to_s => { field: field.to_s, method: method } }
+              else
+                { field[:field] => field }
+              end
+            else
+              { field => { field: field } }
+            end
+          result.merge!(field_data)
+        end
       end
     end
   end

data/lib/tiny_admin/actions/index.rb

@@ -3,9 +3,18 @@
 module TinyAdmin
   module Actions
     class Index < BasicAction
-      attr_reader :current_page, :fields_options, :filters_list, :pagination, :pages, :query_string, :sort
+      attr_reader :current_page,
+                  :fields_options,
+                  :filters_list,
+                  :links,
+                  :pagination,
+                  :pages,
+                  :params,
+                  :query_string,
+                  :repository,
+                  :sort
 
-      def call(app:, context:, options:, actions:)
+      def call(app:, context:, options:)
         evaluate_options(options)
         fields = repository.fields(options: fields_options)
         filters = prepare_filters(fields, filters_list)
@@ -14,9 +23,10 @@ module TinyAdmin
         prepare_page(Views::Actions::Index) do |page|
           setup_pagination(page, settings.components[:pagination], total_count: total_count)
           page.update_attributes(
-            actions: actions,
+            actions: context.actions,
             fields: fields,
             filters: filters,
+            links: links,
             prepare_record: ->(record) { repository.index_record_attrs(record, fields: fields_options) },
             records: records,
             title: repository.index_title
@@ -27,12 +37,13 @@ module TinyAdmin
       private
 
       def evaluate_options(options)
-        @fields_options = options[:attributes]&.each_with_object({}) do |field, result|
-          result.merge!(field.is_a?(Hash) ? { field[:field] => field } : { field => { field: field } })
-        end
+        @fields_options = attribute_options(options[:attributes])
+        @params = context.request.params
+        @repository = context.repository
         @filters_list = options[:filters]
         @pagination = options[:pagination] || 10
-        @sort = options[:sort] || ['id']
+        @sort = options[:sort]
+        @links = options[:links]
 
         @current_page = (params['p'] || 1).to_i
         @query_string = params_to_s(params.except('p'))
@@ -42,8 +53,8 @@ module TinyAdmin
         filters = (filters_list || []).map { _1.is_a?(Hash) ? _1 : { field: _1 } }
         filters = filters.each_with_object({}) { |filter, result| result[filter[:field]] = filter }
         values = (params['q'] || {})
-        fields.each_with_object({}) do |field, result|
-          result[field] = { value: values[field.name], filter: filters[field.name] } if filters.key?(field.name)
+        fields.each_with_object({}) do |(name, field), result|
+          result[field] = { value: values[name], filter: filters[name] } if filters.key?(name)
         end
       end
 
@@ -52,7 +63,7 @@ module TinyAdmin
         return if pages <= 1 || !pagination_component_class
 
         page.pagination_component = pagination_component_class.new
-        page.pagination_component.update(current: current_page, pages: pages, query_string: query_string)
+        page.pagination_component.update_attributes(current: current_page, pages: pages, query_string: query_string)
       end
     end
   end

data/lib/tiny_admin/actions/show.rb

@@ -3,17 +3,20 @@
 module TinyAdmin
   module Actions
     class Show < BasicAction
-      def call(app:, context:, options:, actions:)
-        fields_options = (options[:attributes] || []).each_with_object({}) do |field, result|
-          result.merge!(field.is_a?(Hash) ? { field[:field] => field } : { field => { field: field } })
-        end
+      def call(app:, context:, options:)
+        fields_options = attribute_options(options[:attributes])
+        repository = context.repository
         record = repository.find(context.reference)
         prepare_record = ->(record_data) { repository.show_record_attrs(record_data, fields: fields_options) }
-        fields = repository.fields(options: fields_options)
 
         prepare_page(Views::Actions::Show) do |page|
-          page.setup_record(record: record, fields: fields, prepare_record: prepare_record)
-          page.update_attributes(actions: actions, title: repository.show_title(record))
+          page.update_attributes(
+            actions: context.actions,
+            fields: repository.fields(options: fields_options),
+            prepare_record: prepare_record,
+            record: record,
+            title: repository.show_title(record)
+          )
         end
       rescue Plugins::BaseRepository::RecordNotFound => _e
         prepare_page(options[:record_not_found_page] || Views::Pages::RecordNotFound)

data/lib/tiny_admin/context.rb

@@ -4,6 +4,15 @@ module TinyAdmin
   class Context
     include Singleton
 
-    attr_accessor :reference, :slug
+    attr_accessor :actions,
+                  :navbar,
+                  :pages,
+                  :reference,
+                  :repository,
+                  :request,
+                  :resources,
+                  :router,
+                  :settings,
+                  :slug
   end
 end

data/lib/tiny_admin/field.rb

@@ -4,16 +4,23 @@ module TinyAdmin
   class Field
     attr_reader :name, :options, :title, :type
 
-    def initialize(type:, name:, title:, options: {})
+    def initialize(name:, title:, type:, options: {})
       @type = type
       @name = name
-      @title = title || name
+      @title = title
       @options = options
     end
 
+    def apply_call_option(target)
+      messages = (options[:call] || '').split(',').map(&:strip)
+      messages.inject(target) { |result, msg| result&.send(msg) } if messages.any?
+    end
+
     class << self
-      def create_field(name:, title:, type: nil, options: {})
-        new(type: type, name: name, title: title, options: options)
+      def create_field(name:, title: nil, type: nil, options: {})
+        field_name = name.to_s
+        field_title = field_name.respond_to?(:humanize) ? field_name.humanize : field_name.tr('_', ' ').capitalize
+        new(name: field_name, title: title || field_title, type: type || :string, options: options || {})
       end
     end
   end

data/lib/tiny_admin/plugins/active_record_repository.rb

@@ -4,17 +4,11 @@ module TinyAdmin
   module Plugins
     class ActiveRecordRepository < BaseRepository
       def index_record_attrs(record, fields: nil)
-        return record.attributes.transform_values(&:to_s) if !fields || fields.empty?
+        return record.attributes.transform_values(&:to_s) unless fields
 
-        record.attributes.slice(*fields.keys).each_with_object({}) do |(key, value), result|
-          field_data = fields[key]
-          result[key] =
-            if field_data[:converter] && field_data[:method]
-              converter = Object.const_get(field_data[:converter])
-              converter.send(field_data[:method], value)
-            else
-              value&.to_s
-            end
+        fields.to_h do |name, field|
+          value = record.send(name)
+          [name, translate_value(value, field)]
         end
       end
 
@@ -24,25 +18,19 @@ module TinyAdmin
       end
 
       def fields(options: nil)
-        opts = options || {}
-        columns = model.columns
-        if !opts.empty?
-          extra_fields = opts.keys - model.column_names
-          raise "Some requested fields are not available: #{extra_fields.join(', ')}" if extra_fields.any?
-
-          columns = opts.keys.map { |field| columns.find { _1.name == field } }
-        end
-        columns.map do |column|
-          name = column.name
-          type = opts.dig(column.name, :type) || column.type
-          TinyAdmin::Field.create_field(name: name, title: name.humanize, type: type, options: opts[name])
+        if options
+          types = model.columns.to_h { [_1.name, _1.type] }
+          options.each_with_object({}) do |(name, field_options), result|
+            result[name] = TinyAdmin::Field.create_field(name: name, type: types[name], options: field_options)
+          end
+        else
+          model.columns.each_with_object({}) do |column, result|
+            result[column.name] = TinyAdmin::Field.create_field(name: column.name, type: column.type)
+          end
         end
       end
 
-      def show_record_attrs(record, fields: nil)
-        attrs = !fields || fields.empty? ? record.attributes : record.attributes.slice(*fields.keys)
-        attrs.transform_values(&:to_s)
-      end
+      alias show_record_attrs index_record_attrs
 
       def show_title(record)
         "#{model} ##{record.id}"
@@ -54,10 +42,10 @@ module TinyAdmin
         raise BaseRepository::RecordNotFound, e.message
       end
 
-      def list(page: 1, limit: 10, filters: nil, sort: ['id'])
-        page_offset = page.positive? ? (page - 1) * limit : 0
-        query = model.all.order(sort)
+      def list(page: 1, limit: 10, sort: nil, filters: nil)
+        query = sort ? model.all.order(sort) : model.all
         query = apply_filters(query, filters) if filters
+        page_offset = page.positive? ? (page - 1) * limit : 0
         records = query.offset(page_offset).limit(limit).to_a
         [records, query.count]
       end

data/lib/tiny_admin/plugins/base_repository.rb

@@ -10,6 +10,20 @@ module TinyAdmin
       def initialize(model)
         @model = model
       end
+
+      def translate_value(value, field)
+        if field[:method]
+          method, *options = field[:method].split(',').map(&:strip)
+          if field[:converter]
+            converter = Object.const_get(field[:converter])
+            converter.send(method, value, options: options || [])
+          else
+            Settings.instance.helper_class.send(method, value, options: options || [])
+          end
+        else
+          value&.to_s
+        end
+      end
     end
   end
 end