tramway 4.1.0.1 → 4.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7992bbaa872dc64b21203cb0350463136687e0bfe033a1b461c87bf15804f6b
-  data.tar.gz: 24024ccfa23c7e0718a8dcfd708ce4fcfe232e67c352e5fa28360b017f0b323e
+  metadata.gz: aba7799f773e66098f92d1471963e6fe5da4079b095264c249dc4545a1a84a00
+  data.tar.gz: 98866e7d39aa6d9a31eb9b750949d69ccd16cd2d2f8cb2421f9eb9b96b450046
 SHA512:
-  metadata.gz: 5a8e09bf7ab1d4c09d881f87d99cd1ab5841e92b29a17e2bab144bc009e70263af0cf3ffc71930a027dd589beb13f50c933f4ffcc9fb292e3c36e75f2015b699
-  data.tar.gz: 0110e0d22d0f745d459021d97b929ed4915e08d292a706d7a06dd0c409cd2426c42f2fdb0e40af5ef243e1609b8c37c5ad20204c38b7d16db4f4d0f9d5599b89
+  metadata.gz: 27c456947b97709869bf23bab9eb3f72b4f30799766755fd53c58dad2ec070f0df73b574c16cea5983d3f560983ee9adb0194d84535553ba89d1748a90490005
+  data.tar.gz: b3b705af11f591965764edac7608d8af72e156d1a78d029a887e96b20b30945818df89f4ea947a0f6d945f06f90bf6db702b1a8951597c5cadb9f196c45e6227

data/README.md

@@ -177,6 +177,30 @@ Tramway.configure do |config|
 end
 ```
 
+**icon**
+
+Set `icon` on an entity to render a Font Awesome class string before its auto-generated link in the Tramway Navbar
+(the entity-based items rendered when `tramway_navbar` is called with `with_entities: true`, the default — see
+[Icons on navbar items](#icons-on-navbar-items)):
+
+*config/initializers/tramway.rb*
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    {
+      name: :campaign,
+      namespace: :admin,
+      icon: 'fa-solid fa-bullhorn',
+      pages: [
+        { action: :index }
+      ]
+    }
+  ]
+end
+```
+
+Entities without an `icon` keep rendering as plain text links.
+
 **scope**
 
 By default, Tramway lists all records for an entity on the index page. You can narrow the records displayed by providing a
@@ -331,6 +355,18 @@ end
 With this configuration in place, visiting the show page displays a two-column table where the left column contains the
 localized attribute names and the right column renders their values.
 
+Each entry in `show_attributes` can also be a Hash instead of a plain symbol, to pass options to the `tramway_cell`
+rendering that attribute's value. The Hash requires an `attribute:` key (the method to display) and accepts an
+`options:` key (a Hash forwarded as-is to `tramway_cell`, e.g. `truncate: false`):
+
+```ruby
+class CampaignDecorator < Tramway::BaseDecorator
+  def show_attributes
+    [:name, { attribute: :status, options: { truncate: false } }, :starts_at]
+  end
+end
+```
+
 **create page**
 
 To render a create page for an entity, declare a `:create` action inside the `pages` array in
@@ -430,6 +466,62 @@ Tramway.configure do |config|
 end
 ```
 
+**custom page**
+
+Besides the built-in `index`, `show`, `create`, `update`, and `destroy` pages, an entity can declare **Custom Pages**:
+your own controller action and view, loaded through the same routing, layout, and navbar as the rest of the entity's
+pages. Use a Custom Page for anything that doesn't fit the built-in CRUD actions — a report, a bulk tool, an
+"impersonate" button's target page, and so on.
+
+Declare it by adding a page whose `action` is not one of the built-in ones:
+
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    {
+      name: :user,
+      namespace: :admin,
+      pages: [
+        { action: :index },
+        {
+          action: :impersonate,
+          member: true,       # nests the route under /:id (default: false, an entity-level route)
+          via: :post,         # HTTP method(s) the route accepts (default: :get); also accepts an array, e.g. %i[get post]
+          params: [:redirect_to] # extra required path segments, e.g. /admin/users/:id/impersonate/:redirect_to
+        }
+      ]
+    }
+  ]
+end
+```
+
+Then implement the action yourself, by Rails naming convention, in the controller Tramway would otherwise generate
+for that namespace/entity (here, `Admin::UsersController`), inheriting from `Tramway::EntitiesController` so it gets
+the same layout, navbar, and `entity`/`model_class` lookups as the built-in pages:
+
+```ruby
+# app/controllers/admin/users_controller.rb
+module Admin
+  class UsersController < Tramway::EntitiesController
+    def impersonate
+      @user = model_class.find(params[:id])
+      # ...
+    end
+  end
+end
+```
+
+And add its view at the conventional Rails path for that controller/action:
+
+```haml
+-# app/views/admin/users/impersonate.html.haml
+= tramway_container do
+  %p Impersonating #{@user.email}
+```
+
+See [docs/users/tramway_custom_pages.md](docs/users/tramway_custom_pages.md) for how the routing/controller/view
+resolution works under the hood.
+
 **route_helper**
 
 To get routes Tramway generated just Tramway::Engine.
@@ -990,7 +1082,9 @@ will render [this](https://play.tailwindcss.com/UZPTCudFw5)
 
 #### Icons on navbar items
 
-`nav.item` accepts an optional `icon:` option with a Font Awesome class string, rendered before the item's label:
+`nav.item` accepts an optional `icon:` option with a Font Awesome class string, rendered before the item's label.
+This also applies to the auto-generated entity links described in [Define entities with options](#define-entities-with-options) —
+set `icon` on an entity in `config/initializers/tramway.rb` to add an icon to its link without writing a custom `nav.item` call.
 
 ```ruby
 nav.left do
@@ -1319,6 +1413,15 @@ interactivity.
 Cell content that does not fit its column is truncated with an ellipsis. This is a pure CSS behavior (`truncate` +
 `min-w-0` on each cell) — no JavaScript is involved, and no configuration is needed to enable it.
 
+Pass `truncate: false` to `tramway_cell` to opt a specific cell out of this behavior and let its content wrap/overflow
+normally:
+
+```erb
+<%= tramway_cell truncate: false do %>
+  <%= user.bio %>
+<% end %>
+```
+
 On narrow screens all columns always render, and the table scrolls horizontally within itself (the page never
 stretches past the viewport width) so every column stays reachable. See
 [docs/users/tramway_table.md](docs/users/tramway_table.md) for the full details of the mobile scroll behavior.

data/app/components/tramway/form/tramway_select_component.rb

@@ -78,14 +78,16 @@ module Tramway
 
       private
 
+      # Selections round-trip as a comma-joined string; normalize back to an array here so the
+      # stimulus controller's JSON.parse(data-value) doesn't crash on a saved value.
+      def value = Array(super).flat_map { |item| item.is_a?(String) ? item.split(',') : item }.map(&:to_s)
+
       def tramway_select_size_class
         classes = size_class(:tramway_select_input)
         multiple ? classes.gsub(/\bh-/, 'min-h-') : classes
       end
 
-      def action
-        'click->tramway-select#toggleDropdown'
-      end
+      def action = 'click->tramway-select#toggleDropdown'
 
       def items
         collection

data/app/components/tramway/table/cell_component.rb

@@ -5,17 +5,17 @@ module Tramway
     # Component for rendering a cell in a table
     class CellComponent < Tramway::BaseComponent
       SIZE_CLASSES = {
-        small: 'div-table-cell truncate min-w-0 bg-transparent px-4 py-2 text-sm font-medium text-zinc-100',
-        medium: 'div-table-cell truncate min-w-0 bg-transparent px-6 py-4 text-base font-medium ' \
-                'text-zinc-100',
-        large: 'div-table-cell truncate min-w-0 bg-transparent px-6 py-6 text-lg font-medium ' \
-               'text-zinc-100'
+        small: 'div-table-cell min-w-0 bg-transparent px-4 py-2 text-sm font-medium text-zinc-100',
+        medium: 'div-table-cell min-w-0 bg-transparent px-6 py-4 text-base font-medium text-zinc-100',
+        large: 'div-table-cell min-w-0 bg-transparent px-6 py-6 text-lg font-medium text-zinc-100'
       }.freeze
 
       option :options, optional: true, default: -> { {} }
+      option :truncate, optional: true, default: -> { true }
 
       def cell_classes
-        SIZE_CLASSES.fetch(tramway_table_size) { SIZE_CLASSES[:medium] }
+        base_classes = SIZE_CLASSES.fetch(tramway_table_size) { SIZE_CLASSES[:medium] }
+        truncate ? "#{base_classes} truncate" : base_classes
       end
     end
   end

data/app/views/tramway/entities/show.html.haml

@@ -35,11 +35,13 @@
           = association[:record].title
 
     - @record.show_attributes.each do |attribute|
+      - attribute_name = @record.show_attribute_name(attribute)
+      - attribute_options = @record.show_attribute_options(attribute)
       = tramway_row do
         = tramway_cell do
-          = @model_class.human_attribute_name(attribute)
-        = tramway_cell do
-          = @record.public_send(attribute)
+          = @model_class.human_attribute_name(attribute_name)
+        = tramway_cell(**attribute_options) do
+          = @record.public_send(attribute_name)
 
   - @associations.select { _1[:association_type] == :has_many }.each do |association|
     .flex.flex-row.justify-between.mt-8.text-white

data/config/routes.rb

@@ -13,9 +13,10 @@ Tramway::Engine.routes.draw do
     end => segments
 
     resource_name = segments.pop
+    controller_path = (segments + [resource_name.pluralize]).join('/')
 
     define_resource = proc do
-      entity.pages.reduce([]) do |acc, page|
+      entity.built_in_pages.reduce([]) do |acc, page|
         case page.action
         when 'index'
           acc << :index
@@ -27,15 +28,24 @@ Tramway::Engine.routes.draw do
           acc + %i[edit update]
         when 'destroy'
           acc << :destroy
-        else
-          acc
         end
       end => actions
 
       resources resource_name.pluralize.to_sym,
                 only: actions.map(&:to_sym),
                 controller: '/tramway/entities',
-                defaults: { entity: }
+                defaults: { entity: } do
+        entity.custom_pages.each do |page|
+          path = ([page.action] + page.params.map { |param| ":#{param}" }).join('/')
+          to = "/#{controller_path}##{page.action}"
+
+          if page.member
+            member { match path, to:, via: page.via, defaults: { entity: } }
+          else
+            collection { match path, to:, via: page.via, defaults: { entity: } }
+          end
+        end
+      end
     end
 
     if segments.empty?

data/lib/tramway/base_decorator.rb

@@ -92,6 +92,20 @@ module Tramway
       []
     end
 
+    def show_attribute_name(attribute)
+      return attribute unless attribute.is_a?(Hash)
+
+      attribute.fetch(:attribute) do
+        raise ArgumentError, 'Each show_attributes Hash entry must include an :attribute key'
+      end
+    end
+
+    def show_attribute_options(attribute)
+      return {} unless attribute.is_a?(Hash)
+
+      attribute.fetch(:options, {})
+    end
+
     def show_associations
       []
     end

data/lib/tramway/configs/entities/page.rb

@@ -11,6 +11,9 @@ module Tramway
         attribute? :search, Types::Bool
         attribute? :includes, Types::Array.default([].freeze)
         attribute? :filters, Types::Array.default([].freeze)
+        attribute? :member, Types::Bool.default(false)
+        attribute? :via, (Types::Coercible::Symbol | Types::Array.of(Types::Coercible::Symbol)).default(:get)
+        attribute? :params, Types::Array.of(Types::Coercible::Symbol).default([].freeze)
       end
     end
   end

data/lib/tramway/configs/entity.rb

@@ -11,11 +11,16 @@ module Tramway
       attribute? :pages, Types::Array.of(Tramway::Configs::Entities::Page).default([].freeze)
       attribute? :route, Tramway::Configs::Entities::Route
       attribute? :namespace, Types::Coercible::String
+      attribute? :icon, Types::Coercible::String
 
       # Route Struct contains implemented in Tramway CRUD and helpful routes for the entity
       ACTIONS = %i[index show new create edit update destroy].freeze
       RouteStruct = Struct.new(*ACTIONS)
 
+      # Page#action values handled by Tramway's built-in CRUD controller and routing.
+      # Any other page is a Custom Page, routed to a host app controller instead.
+      BUILT_IN_PAGE_ACTIONS = %w[index show create update destroy].freeze
+
       # HumanName Struct contains human names forms for the entity
       HumanNameStruct = Struct.new(:single, :plural)
 
@@ -39,6 +44,14 @@ module Tramway
         pages.find { |page| page.action == name.to_s }
       end
 
+      def built_in_pages
+        pages.select { |page| BUILT_IN_PAGE_ACTIONS.include?(page.action) }
+      end
+
+      def custom_pages
+        pages.reject { |page| BUILT_IN_PAGE_ACTIONS.include?(page.action) }
+      end
+
       def show_helper_method
         build_helper_method(name, route:, namespace:, plural: false)
       end

data/lib/tramway/helpers/views_helper.rb

@@ -50,8 +50,8 @@ module Tramway
                   &
       end
 
-      def tramway_cell(**options, &)
-        component 'tramway/table/cell', options:, &
+      def tramway_cell(truncate: true, **options, &)
+        component 'tramway/table/cell', truncate:, options:, &
       end
 
       def tramway_button(path: nil, text: nil, method: :get, form_options: {}, **options, &)

data/lib/tramway/navbar.rb

@@ -59,7 +59,8 @@ module Tramway
       entities.each do |entity|
         next if entity.routes.index.blank?
 
-        item entity.human_name.plural, Tramway::Engine.routes.url_helpers.public_send(entity.routes.index)
+        item entity.human_name.plural, Tramway::Engine.routes.url_helpers.public_send(entity.routes.index),
+             icon: entity.icon
       end
 
       reset_filling

data/lib/tramway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tramway
-  VERSION = '4.1.0.1'
+  VERSION = '4.1.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: 4.1.0.1
+  version: 4.1.2
 platform: ruby
 authors:
 - kalashnikovisme