cm-admin 1.5.49 → 1.5.50

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8b93ddf37f6e38e2941258922c9717f51376d2950759b4822aed030c6b90d20
-  data.tar.gz: 45da70fe84a3cbdbf3edac26d7d55d276fb93057cbaa6a408f91d5e960e8090e
+  metadata.gz: d1c927758f152c126931344ac38ad2b7cfdf454b5a70d2c4508e67bfaece250b
+  data.tar.gz: f7a78226339aa88ae1bc5cfe59ad0947431e065b9ef66fbfd3fc5d2baac3ccac
 SHA512:
-  metadata.gz: 3e9f9eb33d0109f203fecef632fe6d42599cc2932a1a6dda8b1671742009c21faf69cdd9037c8406ca62582b6ad69dae95561aee88326d8051a61e348d6e0e37
-  data.tar.gz: 7c00620c3ff14846ab2371bab8c9a3873d558f01925ea0d22074cd2ce4259389f88e8a23fc0b02fd32174c0e3f9213ad0d1418a31b6cd03515f4a028e8f49bff
+  metadata.gz: 26666e659ad3fa593545112f5fdf5f61c8bf124b7d8c9a7fc4d9a01d3280550e6b86bce8db84c6fa4abdd6b7cd69d964b774bca36d868965ad731bce29c1354b
+  data.tar.gz: eac4324c8a183c0d8bb5ad952bf7302f563b07f0685efa7e05f34a589689086e6fa8fe19501dd7a0551df6dbd7c8f84580e2625bb2f083fec4731448eb702542

data/.yardopts

@@ -2,4 +2,5 @@ lib/cm_admin/models/dsl_method.rb
 -
 docs/ShowHideContent.md
 docs/ListingSelectTwoItems.md
-docs/ListingSelectTwoAjax.md
+docs/ListingSelectTwoAjax.md
+docs/AddingAlert.md

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cm-admin (1.5.49)
+    cm-admin (1.5.50)
       caxlsx_rails
       cocoon (~> 1.2.15)
       csv-importer (~> 0.8.2)

data/app/assets/stylesheets/cm_admin/base/alertbanner.scss

@@ -0,0 +1,36 @@
+.alert {
+  .alert-banner-body {
+    display: flex;
+    justify-content: space-between;
+    align-items: flex-start;
+
+    .alert-banner-icon {
+      margin: 1px;
+
+      svg {
+        width: 16px;
+        height: 16px;
+      }
+    }
+
+    .alert-banner-content {
+      margin-left: 10px;
+      display: flex;
+      flex-direction: column;
+
+      .alert-banner-header {
+        p {
+          font-size: 1.1rem;
+          font-weight: bold;
+          margin-bottom: 0;
+        }
+      }
+
+      .alert-banner-text {
+        p.mb-0 {
+          margin-bottom: 0;
+        }
+      }
+    }
+  }
+}

data/app/assets/stylesheets/cm_admin/cm_admin.css.scss

@@ -17,6 +17,7 @@
 @import "./base/common";
 @import "./base/cardView";
 @import "./base/kanban";
+@import "./base/alertbanner";
 @import "./components/index";
 @import "./dependency/flatpickr.min";
 @import "./dependency/fontawesome.all";

data/app/controllers/cm_admin/resource_controller.rb

@@ -32,6 +32,7 @@ module CmAdmin
       @current_action = CmAdmin::Models::Action.find_by(@model, name: 'show')
       scoped_model = "CmAdmin::#{@model.name}Policy::Scope".constantize.new(Current.user, @model.name.constantize).resolve
       @ar_object = fetch_ar_object(scoped_model, params[:id])
+      @alerts = @model.alerts
       resource_identifier
       respond_to do |format|
         if request.xhr?

data/app/views/cm_admin/main/_alert_banner.html.slim

@@ -0,0 +1,9 @@
+.alert class="alert-#{alert.type}" *alert.html_attrs
+  .alert-banner-body
+    .alert-banner-icon
+      i.fas class="fa-#{icon_class} fs-5 ms-2"
+    .alert-banner-content
+      .alert-banner-header
+        p== alert.header
+      .alert-banner-text
+        p.mb-0== alert.body

data/app/views/cm_admin/main/_show_content.html.slim

@@ -2,6 +2,8 @@
   == render 'cm_admin/main/top_navbar'
   == render 'cm_admin/main/tabs', via_xhr: defined?(via_xhr) ? via_xhr : false
 .show-page__inner
+  - unless @alerts.empty?
+    == create_alerts(@alerts,@ar_object)
   - if @action.partial
     == render @action.partial
   - else

data/docs/AddingAlert.md

@@ -0,0 +1,84 @@
+# Adding Alert Feature ⚠️
+
+## Overview
+
+The Alert feature has been added to CmAdmin to provide a standardized method for displaying alerts and notifications to users. This documentation outlines how to use the Alert, including its configuration, types, and examples.
+
+## Features
+
+- **Customizable Alerts:** Display alerts with headers, bodies, and specific types.
+- **Conditional Display:** Control when alerts should be shown based on dynamic conditions.
+- **Type Support:** Supports four predefined types of alerts: `info`, `success`, `danger`, and `warning`.
+
+## Usage
+
+The Alert Banner is implemented using the `alert_box` helper. Below are the key elements and their usage:
+
+### Syntax
+
+**1. Using Parameters:**
+
+```ruby
+alert_box header:"Title", body:"Body1", type: :info, display_if:->(arg){arg.present?}, html_attrs:{}
+```
+
+**2. Using a Partial:**
+
+```ruby
+alert_box partial:"/users/sessions/alert", display_if:->(arg){arg.present?}, html_attrs:{}
+```
+
+### Parameters
+
+- **`header:`** (optional) - The title text for the alert.
+- **`body:`** (optional) - A string to display as the body of the alert.
+- **`type:`** (optional) - The type of alert. Accepts one of the following symbols: `:info`, `:success`, `:danger`, `:warning`.
+- **`partial:`** (optional) - The path to a custom partial or HTML for the alert.
+- **`display_if:`** (optional) - A lambda function that determines whether the alert should be shown. Should return a boolean.
+- **`html_attrs:`** (optional) - Additional HTML attributes to apply to the alert. Note: This has no effect on partials.
+
+## Types of Alerts
+
+The following types are supported:
+
+- **`info`** - Blue alert for informational messages.
+- **`success`** - Green alert for successful actions or positive feedback.
+- **`danger`** - Red alert for errors or critical warnings.
+- **`warning`** - Yellow alert for cautionary messages.
+
+### Examples
+
+#### Example 1: Basic Info Alert
+
+```ruby
+alert_box header:"Information", body:"This is an informational message.", type: :info, display_if:->(arg){arg.present?}
+```
+
+- **Screenshot:** ![image](https://github.com/user-attachments/assets/cb0c9a09-5084-4204-ae83-64ac06065cf9)
+- **Screenshot:** ![image](https://github.com/user-attachments/assets/8bc1c066-03c0-4e34-8e38-217062db4579)
+- **Description:** Displays an alert with a title and body text.
+
+#### Example 2: Using Custom Body
+
+```ruby
+alert_box header:"Information", body:"This is an informational message. <br>This is a break text.", type: :info, display_if:->(arg){arg.present?}
+```
+- **Screenshot:** ![image](https://github.com/user-attachments/assets/5614e104-4675-49e8-a2db-034a890fd581)
+- **Screenshot:** ![image](https://github.com/user-attachments/assets/41c22856-4647-4c47-ba48-d144833c2074)
+- **Description:** Displays a custom body for the alert, allowing for more customized content.
+
+
+#### Example 3: Using Partial
+
+```ruby
+alert_box partial:"/check/alert", display_if:->(arg){arg.present?}
+```
+- **Screenshot:** ![image](https://github.com/user-attachments/assets/5614e104-4675-49e8-a2db-034a890fd581)
+- **Screenshot:** ![image](https://github.com/user-attachments/assets/41c22856-4647-4c47-ba48-d144833c2074)
+- **Description:** Displays a custom partial for the alert, allowing for more customized HTML or content.
+
+
+### Important Notes
+
+- **Nested Sections:** Alerts cannot be placed inside nested sections. If added within a nested section, the alert will appear on the wrapped `cm_show_section`.
+- **Unsupported Types:** Only the specified types (`info`, `success`, `danger`, `warning`) are supported. Any other type will default to a standard div.

data/lib/cm_admin/model.rb

@@ -14,6 +14,7 @@ require_relative 'models/section'
 require_relative 'models/row'
 require_relative 'models/tab'
 require_relative 'models/dsl_method'
+require_relative 'models/alert'
 require 'pagy'
 require 'axlsx'
 require 'cocoon'
@@ -29,7 +30,7 @@ module CmAdmin
     include CmAdmin::Engine.routes.url_helpers
 
     attr_accessor :available_actions, :actions_set, :available_fields, :additional_permitted_fields,
-                  :current_action, :params, :filters, :available_tabs, :icon_name, :bulk_actions, :display_name
+                  :current_action, :params, :filters, :available_tabs, :icon_name, :bulk_actions, :display_name, :alerts
     attr_reader :name, :ar_model, :is_visible_on_sidebar, :importer
 
     def initialize(entity, &block)
@@ -42,9 +43,10 @@ module CmAdmin
       @additional_permitted_fields ||= []
       @current_action = nil
       @available_tabs ||= []
-      @available_fields ||= {index: [], show: [], edit: [], new: []}
+      @available_fields ||= { index: [], show: [], edit: [], new: [] }
       @params = nil
       @filters ||= []
+      @alerts = []
       instance_eval(&block) if block_given?
       actions unless @actions_set
       $available_actions = @available_actions.dup
@@ -112,6 +114,10 @@ module CmAdmin
       @display_name.present? ? @display_name : @ar_model.table_name
     end
 
+    def alert_box(options = {})
+      @alerts << CmAdmin::Models::Alert.new(options)
+    end
+
     def model_name
       @display_name.present? ? @display_name : @name
     end

data/lib/cm_admin/models/alert.rb

@@ -0,0 +1,23 @@
+module CmAdmin
+  module Models
+    class Alert
+      attr_accessor :header, :body, :type, :partial, :display_if, :html_attrs
+
+      def initialize(attributes = {})
+        set_default_values
+        attributes.each do |key, value|
+          send("#{key}=", value)
+        end
+      end
+
+      def set_default_values
+        self.header = nil
+        self.body = nil
+        self.type = :info
+        self.partial = nil
+        self.display_if = ->(_args) { true }
+        self.html_attrs = {}
+      end
+    end
+  end
+end

data/lib/cm_admin/models/dsl_method.rb

@@ -335,6 +335,44 @@ module CmAdmin
       def sort_column(column = :created_at)
         @current_action.sort_column = column.to_sym if @current_action
       end
+
+      # Adds a new alert to the current section.
+      #
+      # @param [String, nil] header The title text for the alert.
+      # @param [String, nil] body A string to display as the body of the alert.
+      # @param [Symbol, nil] type The type of alert. Accepts one of the following symbols: :info, :success, :danger, :warning.
+      # @param [String, nil] partial The path to a custom partial or HTML for the alert.
+      # @param [Proc, nil] display_if A lambda function that determines whether the alert should be shown. Should return a boolean.
+      # @param [Hash] html_attrs Additional HTML attributes to apply to the alert. Has no effect on partials.
+      #
+      # @example Basic info alert
+      #   alert_box(header: "Information", body: "This is an informational message.", type: :info)
+      #
+      # @example Basic info alert with custom body
+      #   alert_box(header: "Information", body: "This is an informational message. <br>This is a break text", type: :info)
+      #
+      # @example Alert with custom partial
+      #   alert_box(partial: "/users/sessions/alert", display_if: ->(arg) { arg.present? })
+      #
+      # @example Alert with conditional display and custom HTML attributes
+      #   alert_box(
+      #     header: "Warning",
+      #     body: "Please review your submission.",
+      #     type: :warning,
+      #     display_if: ->(user) { user.submissions.any?(&:incomplete?) },
+      #     html_attrs: { id: "submission-warning", data: { turbo_frame: "warnings" } }
+      #   )
+      #
+      # @note Alerts cannot be placed inside nested sections. If added within a nested section,
+      #   the alert will appear on the wrapped cm_show_section.
+      # @note Only the specified types (info, success, danger, warning) are supported.
+      #   Any other type will default to a standard div.
+      #
+      # @see file:docs/AddingAlert.md For more information on how to add alerts to your model.
+      #
+      def alert_box(header: nil, body: nil, type: nil, partial: nil, display_if: nil, html_attrs: {})
+        @section_fields << CmAdmin::Models::Alert.new(header, body, type, partial: partial, display_if: display_if, html_attrs: html_attrs)
+      end
     end
   end
 end

data/lib/cm_admin/models/section.rb

@@ -33,6 +33,10 @@ module CmAdmin
         end
       end
 
+      def alert_box(options = {})
+        @section_fields << CmAdmin::Models::Alert.new(options)
+      end
+
       def form_field(field_name, options = {}, arg = nil)
         if @current_nested_field
           @current_nested_field.fields << CmAdmin::Models::FormField.new(field_name, options[:input_type], options)

data/lib/cm_admin/version.rb

@@ -1,3 +1,3 @@
 module CmAdmin
-  VERSION = '1.5.49'
+  VERSION = '1.5.50'
 end

data/lib/cm_admin/view_helpers/field_display_helper.rb

@@ -1,9 +1,17 @@
 module CmAdmin
   module ViewHelpers
     module FieldDisplayHelper
+      ALERT_ICON_CLASSES = {
+        warning: 'triangle-exclamation',
+        danger: 'triangle-exclamation',
+        success: 'circle-check'
+      }.freeze
+
       def show_field(ar_object, field)
+        return create_alert(field, ar_object) if field.is_a?(CmAdmin::Models::Alert)
         return unless field.display_if.call(ar_object)
-        content_tag(:div, class: "card-info") do
+
+        content_tag(:div, class: 'card-info') do
           concat show_field_label(ar_object, field) if field.label
           concat value_with_prefix_and_suffix(ar_object, field)
         end
@@ -16,7 +24,7 @@ module CmAdmin
               next unless field.display_if.call(ar_object)
 
               content_tag(:div, class: "col-#{col_size}") do
-                content_tag(:div, class: "card-info") do
+                content_tag(:div, class: 'card-info') do
                   concat show_field_label(ar_object, field) if field.label
                   concat value_with_prefix_and_suffix(ar_object, field)
                 end
@@ -26,6 +34,21 @@ module CmAdmin
         end.join.html_safe
       end
 
+      def create_alerts(alerts, ar_object)
+        alerts.map do |alert|
+          create_alert(alert, ar_object)
+        end.join.html_safe
+      end
+
+      def create_alert(alert, ar_object)
+        return unless alert.display_if.call(ar_object)
+
+        return render partial: alert.partial if alert.partial
+
+        icon_class = ALERT_ICON_CLASSES.fetch(alert.type, 'circle-info')
+        render partial: 'cm_admin/main/alert_banner', locals: { alert: alert, icon_class: icon_class }
+      end
+
       def show_field_label(ar_object, field)
         content_tag(:div, class: "card-info__label") do
           field_label = if field.label.present?

data/lib/cm_admin/view_helpers/form_helper.rb

@@ -106,6 +106,7 @@ module CmAdmin
 
       def set_form_field(resource, form_obj, field)
         return unless field.display_if.call(form_obj.object)
+        return create_alert(field, form_obj.object) if field.is_a?(CmAdmin::Models::Alert)
 
         is_required = is_field_presence_validated?(form_obj, field)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cm-admin
 version: !ruby/object:Gem::Version
-  version: 1.5.49
+  version: 1.5.50
 platform: ruby
 authors:
 - Michael
@@ -14,7 +14,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-09-06 00:00:00.000000000 Z
+date: 2024-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: caxlsx_rails
@@ -218,6 +218,7 @@ files:
 - app/assets/javascripts/cm_admin/scaffolds.js
 - app/assets/javascripts/cm_admin/shared_scaffolds.js
 - app/assets/stylesheets/cm_admin/actiontext.scss
+- app/assets/stylesheets/cm_admin/base/alertbanner.scss
 - app/assets/stylesheets/cm_admin/base/auth.scss
 - app/assets/stylesheets/cm_admin/base/cardView.scss
 - app/assets/stylesheets/cm_admin/base/comments.scss
@@ -367,6 +368,7 @@ files:
 - app/models/file_import.rb
 - app/policies/cm_admin/file_import_policy.rb
 - app/views/cm_admin/main/_actions_dropdown.html.slim
+- app/views/cm_admin/main/_alert_banner.html.slim
 - app/views/cm_admin/main/_associated_table.html.slim
 - app/views/cm_admin/main/_card.html.slim
 - app/views/cm_admin/main/_cm_pagy_nav.html.slim
@@ -419,6 +421,7 @@ files:
 - config/webpack/production.js
 - config/webpack/test.js
 - config/webpacker.yml
+- docs/AddingAlert.md
 - docs/ListingSelectTwoAjax.md
 - docs/ListingSelectTwoItems.md
 - docs/ShowHideContent.md
@@ -431,6 +434,7 @@ files:
 - lib/cm_admin/model.rb
 - lib/cm_admin/models/action.rb
 - lib/cm_admin/models/actions/blocks.rb
+- lib/cm_admin/models/alert.rb
 - lib/cm_admin/models/blocks.rb
 - lib/cm_admin/models/bulk_action.rb
 - lib/cm_admin/models/column.rb