tiny_admin 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: afea7b433e47bdf47e2682a334e2ffe7761e6e341aec9b43746291faf4d16406
+  data.tar.gz: 6c53fbae6a6c6749ef423bbd190094c25149abae29c6c235bf49f13fb3d6906a
+SHA512:
+  metadata.gz: 4b9701bccac2aa19c6fb838c037e0522d6ee8d3560ec1d5aa743725a64d1c2e4bfc7369faaef9bdc6b98da280f8f1d82c302fadfae5620fe1e958857238005c4
+  data.tar.gz: 16763a9cdf6df77cc261f5a5493803a55cd41756888026fb93ccdf66bf7c6fe7412482b39a666fd026892787addeb55c80adef45b1af479b0f062eb7276aaa53

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2023 Mattia Roccoberton
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,171 @@
+# Tiny Admin
+
+A compact and composible dashboard component for Ruby.
+
+The main features are:
+- a Rack app that can be mounted in any Rack-enabled framework;
+- some features are handled as plugins, so they can be replaced with little effort;
+- routing is provided by Roda (which is small and performant);
+- views are Phlex components.
+
+See (extra)[extra] folder for usage examples.
+
+Please ⭐ if you like it.
+
+## Install
+
+- Add to your Gemfile: `gem 'tiny_admin'`
+- For a Rails project: add an initializer and the YAML config - see (configuration)[#configuration] below.
+
+## Plugins and components
+
+Every plugin or component can be replaced.
+
+### Authentication
+
+There are 2 plugins included:
+- _SimpleAuth_: provides a simple session authentication based on Warden (`warden` gem must be included in the host project);
+- _NoAuth_: no authentication.
+
+### Repository
+
+There is 1 plugin included:
+- _ActiveRecordRepository_: isolates the query layer to expose the resources in the admin interface.
+
+### View pages
+
+There are 5 view pages included:
+- _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
+
+There are 5 view components included:
+- _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 programmatically or using a YAML config.
+
+Example:
+
+```rb
+# config/initializers/tiny_admin.rb
+
+# hash generated using: Digest::SHA512.hexdigest("changeme")
+ENV['ADMIN_PASSWORD_HASH'] = 'f1891cea80fc05e433c943254c6bdabc159577a02a7395dfebbfbc4f7661d4af56f2d372131a45936de40160007368a56ef216a30cb202c66d3145fd24380906'
+config = Rails.root.join('config/tiny_admin.yml').to_s
+TinyAdmin.configure_from_file(config)
+```
+
+```yml
+---
+authentication:
+  plugin: TinyAdmin::Plugins::SimpleAuth
+page_not_found: Admin::PageNotFound
+record_not_found: Admin::RecordNotFound
+root:
+  title: 'Tiny Admin'
+  page: Admin::PageRoot
+  # redirect: posts
+sections:
+  - slug: google
+    name: Google.it
+    type: url
+    url: https://www.google.it
+    options:
+      target: '_blank'
+  - slug: stats
+    name: Stats
+    type: page
+    page: Admin::Stats
+  - slug: authors
+    name: Authors
+    type: resource
+    model: Author
+    repository: Admin::AuthorsRepo
+    collection_actions:
+      - latests: Admin::LatestAuthorsAction
+    member_actions:
+      - csv_export: Admin::CsvExportAuthorAction
+    # only:
+    #   - index
+    # options:
+    #   - hidden
+  - slug: posts
+    name: Posts
+    type: resource
+    model: Post
+    index:
+      sort:
+        - author_id DESC
+      pagination: 15
+      attributes:
+        - id
+        - title
+        - field: author_id
+          link_to: authors
+        - state
+        - published
+        - dt
+        - field: created_at
+          converter: Admin::Utils
+          method: datetime_formatter
+      filters:
+        - title
+        - field: state
+          type: select
+          values:
+            - available
+            - unavailable
+            - arriving
+        - published
+    show:
+      attributes:
+        - id
+        - title
+        - description
+        - field: author_id
+          link_to: authors
+        - category
+        - published
+        - state
+        - 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).

data/lib/tiny_admin/actions/basic_action.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module TinyAdmin
+  module Actions
+    class BasicAction
+      include Utils
+
+      attr_reader :params, :path, :repository
+
+      def initialize(repository, path:, params:)
+        @repository = repository
+        @path = path
+        @params = params
+      end
+    end
+  end
+end

data/lib/tiny_admin/actions/index.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TinyAdmin
+  module Actions
+    class Index < BasicAction
+      attr_reader :current_page, :fields_options, :filters_list, :pagination, :query_string, :sort
+
+      def call(app:, context:, options:, actions:)
+        evaluate_options(options)
+        fields = repository.fields(options: fields_options)
+        filters = prepare_filters(fields, filters_list)
+        records, total_count = repository.list(page: current_page, limit: pagination, filters: filters, sort: sort)
+        prepare_record = ->(record) { repository.index_record_attrs(record, fields: fields_options) }
+        title = repository.index_title
+        pages = (total_count / pagination) + 1
+
+        prepare_page(Views::Actions::Index, title: title, context: context, query_string: query_string) do |page|
+          page.setup_pagination(current_page: current_page, pages: pages > 1 ? pages : false)
+          page.setup_records(records: records, fields: fields, prepare_record: prepare_record)
+          page.actions = actions
+          page.filters = filters
+        end
+      end
+
+      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
+        @filters_list = options[:filters]
+        @pagination = options[:pagination] || 10
+        @sort = options[:sort] || ['id']
+
+        @current_page = (params['p'] || 1).to_i
+        @query_string = params_to_s(params.reject { |k, _v| k == 'p' })
+      end
+
+      def prepare_filters(fields, filters_list)
+        filters = (filters_list || []).map { _1.is_a?(Hash) ? _1 : { field: _1 } }.index_by { _1[:field] }
+        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)
+        end
+      end
+    end
+  end
+end

data/lib/tiny_admin/actions/show.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+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
+        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, title: repository.show_title(record), context: context) do |page|
+          page.setup_record(record: record, fields: fields, prepare_record: prepare_record)
+          page.actions = actions
+        end
+      rescue Plugins::BaseRepository::RecordNotFound => _e
+        prepare_page(options[:record_not_found_page] || Views::Pages::RecordNotFound)
+      end
+    end
+  end
+end

data/lib/tiny_admin/authentication.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TinyAdmin
+  class Authentication < BasicApp
+    route do |r|
+      r.get 'unauthenticated' do
+        if current_user
+          r.redirect settings.root_path
+        else
+          render_login
+        end
+      end
+
+      r.post 'unauthenticated' do
+        render_login(warnings: ['Failed to authenticate'])
+      end
+
+      r.get 'logout' do
+        logout_user
+        r.redirect settings.root_path
+      end
+    end
+
+    private
+
+    def render_login(notices: nil, warnings: nil, errors: nil)
+      page = prepare_page(settings.authentication[:login], options: %i[no_menu compact_layout])
+      page.setup_flash_messages(
+        notices: notices || flash['notices'],
+        warnings: warnings || flash['warnings'],
+        errors: errors || flash['errors']
+      )
+      render(inline: page.call)
+    end
+  end
+end

data/lib/tiny_admin/basic_app.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TinyAdmin
+  class BasicApp < Roda
+    include Utils
+
+    class << self
+      def authentication_plugin
+        plugin = TinyAdmin::Settings.instance.authentication&.dig(:plugin)
+        plugin_class = plugin.is_a?(String) ? Object.const_get(plugin) : plugin
+        plugin_class || TinyAdmin::Plugins::NoAuth
+      end
+    end
+
+    plugin :flash
+    plugin :not_found
+    plugin :render, engine: 'html'
+    plugin :sessions, secret: SecureRandom.hex(64)
+
+    plugin authentication_plugin
+
+    not_found { prepare_page(settings.page_not_found).call }
+
+    def attach_flash_messages(page)
+      return unless page.respond_to?(:setup_flash_messages)
+
+      page.setup_flash_messages(notices: flash['notices'], warnings: flash['warnings'], errors: flash['errors'])
+    end
+  end
+end

data/lib/tiny_admin/context.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TinyAdmin
+  class Context
+    include Singleton
+
+    attr_accessor :reference, :slug
+  end
+end

data/lib/tiny_admin/field.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module TinyAdmin
+  class Field
+    attr_reader :name, :options, :title, :type
+
+    def initialize(type:, name:, title:, options: {})
+      @type = type
+      @name = name
+      @title = title || name
+      @options = options
+    end
+
+    class << self
+      def create_field(name:, title:, type: nil, options: {})
+        new(type: type, name: name, title: title, options: options)
+      end
+    end
+  end
+end

data/lib/tiny_admin/plugins/active_record_repository.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+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?
+
+        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
+        end
+      end
+
+      def index_title
+        title = model.to_s
+        title.respond_to?(:pluralize) ? title.pluralize : title
+      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])
+        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
+
+      def show_title(record)
+        "#{model} ##{record.id}"
+      end
+
+      def find(reference)
+        model.find(reference)
+      rescue ActiveRecord::RecordNotFound => e
+        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)
+        query = apply_filters(query, filters) if filters
+        records = query.offset(page_offset).limit(limit).to_a
+        [records, query.count]
+      end
+
+      def apply_filters(query, filters)
+        filters.each do |field, filter|
+          value = filter&.dig(:value)
+          next if value.nil? || value == ''
+
+          query =
+            case field.type
+            when :string
+              value = ActiveRecord::Base.sanitize_sql_like(value.strip)
+              query.where("#{field.name} LIKE ?", "%#{value}%")
+            else
+              query.where(field.name => value)
+            end
+        end
+        query
+      end
+    end
+  end
+end

data/lib/tiny_admin/plugins/base_repository.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TinyAdmin
+  module Plugins
+    class BaseRepository
+      RecordNotFound = Class.new(StandardError)
+
+      attr_reader :model
+
+      def initialize(model)
+        @model = model
+      end
+    end
+  end
+end

data/lib/tiny_admin/plugins/no_auth.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TinyAdmin
+  module Plugins
+    module NoAuth
+      class << self
+        def configure(_app, _opts = {}); end
+      end
+
+      module InstanceMethods
+        def authenticate_user!
+          true
+        end
+
+        def current_user
+          'admin'
+        end
+
+        def logout_user
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/tiny_admin/plugins/simple_auth.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module TinyAdmin
+  module Plugins
+    module SimpleAuth
+      class << self
+        def configure(app, opts = {})
+          Warden::Strategies.add(:secret) do
+            def authenticate!
+              hash = ENV.fetch('ADMIN_PASSWORD_HASH')
+              secret = params['secret']
+              return fail(:invalid_credentials) if !secret || Digest::SHA512.hexdigest(secret) != hash
+
+              success!(app: 'TinyAdmin')
+            end
+          end
+
+          app.opts[:login_form] = opts[:login_form] || TinyAdmin::Views::Pages::SimpleAuthLogin
+
+          app.use Warden::Manager do |manager|
+            manager.default_strategies :secret
+            manager.failure_app = TinyAdmin::Authentication
+          end
+        end
+      end
+
+      module InstanceMethods
+        def authenticate_user!
+          env['warden'].authenticate!
+        end
+
+        def current_user
+          env['warden'].user
+        end
+
+        def logout_user
+          env['warden'].logout
+        end
+      end
+    end
+  end
+end

data/lib/tiny_admin/router.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module TinyAdmin
+  class Router < BasicApp
+    TinyAdmin::Settings.instance.load_settings
+
+    route do |r|
+      r.on 'auth' do
+        context.slug = nil
+        r.run Authentication
+      end
+
+      authenticate_user!
+
+      r.root do
+        root_route(r)
+      end
+
+      r.post '' do
+        context.slug = nil
+        r.redirect settings.root_path
+      end
+
+      TinyAdmin::Settings.instance.pages.each do |slug, data|
+        setup_page_route(r, slug, data)
+      end
+
+      TinyAdmin::Settings.instance.resources.each do |slug, options|
+        setup_resource_routes(r, slug, options: options || {})
+      end
+
+      nil # NOTE: needed to skip the last line (each) return value
+    end
+
+    private
+
+    def render_page(page)
+      attach_flash_messages(page)
+      render(inline: page.call)
+    end
+
+    def root_route(router)
+      context.slug = nil
+      if settings.root[:redirect]
+        router.redirect "#{settings.root_path}/#{settings.root[:redirect]}"
+      else
+        page = settings.root[:page]
+        page_class = page.is_a?(String) ? Object.const_get(page) : page
+        render_page prepare_page(page_class, context: context)
+      end
+    end
+
+    def setup_page_route(router, slug, page_class)
+      router.get slug do
+        context.slug = slug
+        render_page prepare_page(page_class, context: context)
+      end
+    end
+
+    def setup_resource_routes(router, slug, options:)
+      router.on slug do
+        context.slug = slug
+        setup_collection_routes(router, slug: slug, options: options)
+        setup_member_routes(router, slug: slug, options: options)
+      end
+    end
+
+    def setup_collection_routes(router, slug:, options:)
+      repository = options[:repository].new(options[:model])
+      index_options = options[:index] || {}
+      custom_actions = []
+
+      # Custom actions
+      (options[:collection_actions] || []).each do |custom_action|
+        action_slug, action = custom_action.first
+        action_class = action.is_a?(String) ? Object.const_get(action) : action
+        custom_actions << action_slug.to_s
+        router.get action_slug.to_s do
+          custom_action = action_class.new(repository, path: request.path, params: request.params)
+          render_page custom_action.call(app: self, context: context, options: index_options)
+        end
+      end
+
+      # Index
+      actions = options[:only]
+      if !actions || actions.include?(:index) || actions.include?('index')
+        router.is do
+          index_action = TinyAdmin::Actions::Index.new(repository, path: request.path, params: request.params)
+          render_page index_action.call(app: self, context: context, options: index_options, actions: custom_actions)
+        end
+      end
+    end
+
+    def setup_member_routes(router, slug:, options:)
+      repository = options[:repository].new(options[:model])
+      show_options = (options[:show] || {}).merge(record_not_found_page: settings.record_not_found)
+      custom_actions = []
+
+      router.on String do |reference|
+        context.reference = reference
+
+        # Custom actions
+        (options[:member_actions] || []).each do |custom_action|
+          action_slug, action = custom_action.first
+          action_class = action.is_a?(String) ? Object.const_get(action) : action
+          custom_actions << action_slug.to_s
+
+          router.get action_slug.to_s do
+            custom_action = action_class.new(repository, path: request.path, params: request.params)
+            render_page custom_action.call(app: self, context: context, options: show_options)
+          end
+        end
+
+        # Show
+        actions = options[:only]
+        if !actions || actions.include?(:show) || actions.include?('show')
+          router.is do
+            show_action = TinyAdmin::Actions::Show.new(repository, path: request.path, params: request.params)
+            render_page show_action.call(app: self, context: context, options: show_options, actions: custom_actions)
+          end
+        end
+      end
+    end
+  end
+end