elaine_crud 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b331198ebb4dcf4ce1e5d3718d65fb36e2fac98ef24c219f46206fc9cb450309
-  data.tar.gz: 690b1dd2f306cf3a6156dd35095471c283dd9674fe35f3895effec18d48cc047
+  metadata.gz: 6790f924718c05bea415357a3ace073990743e5e8c0014ea5380d674adbbc4f7
+  data.tar.gz: d1b352c734dbd526047a6503cdaed192dfa30daa05c3f92577f84f302d44e970
 SHA512:
-  metadata.gz: 40b0b2d357e3bd0b87360fe7f0ea59613fb7dab409534b7843181caa15e726681ff2d1fd0d42161765be50b79bb8ac1ba7aeab03d19eaf89288e858865abacdf
-  data.tar.gz: dbd100c7c1dcea367e12522c14fabb94f68b6ca7a19c6f42945da72752f475c0e2e6a8684611c33253ad1edcbb31d8e20bf31ff233b3cc912c1105bf08df3fc1
+  metadata.gz: 1cdcb91a0a27cbb97a1d9db7cab2588263933a99d46f81423a18c447c9bd58b6bf0d478d81a53403f0f31249768fcfdd383207542dc23a7d29f239600cfd9dcc
+  data.tar.gz: '085b69b219b226dd5d2c1cbced974603c5da07833113f5eca33f6311d9f3febf10d4e91c0c592f751efd9bb61c23239a1ef03b23ad213dd0a6cc15893faccaa5'

data/README.md

@@ -1,14 +1,26 @@
 # ElaineCrud
 
-A Rails engine for rapidly generating CRUD interfaces for ActiveRecord models with minimal configuration.
+A Rails engine for rapidly generating CRUD interfaces for ActiveRecord models with minimal configuration. This controller will create you the following CRUD interface:
+```ruby
+class TaskController < ElaineCrud::BaseController
+  layout 'application'
+
+  model Task # Your ActiveRecord model
+  permit_params :title, :description, :priority, :completed, :due_date
+end
+```
+![Image](docs/screenshots/screenshot1.png)
 
 ## Features
 
-- ✅ **Zero Configuration**: Works out of the box with any ActiveRecord model
-- ✅ **Minimal Code**: Just specify model and permitted params
-- ✅ **Modern UI**: Clean, responsive interface with TailwindCSS
-- ✅ **Extensible**: Override any view or behavior in your host app
-- ✅ **Rails Conventions**: Follows standard Rails patterns
+- **Zero Configuration**: Works out of the box with any ActiveRecord model
+- **Rails Conventions**: Follows standard Rails patterns
+- **Minimal Code**: Just specify model and permitted params
+- **Search & Filter**: Built-in search across text fields
+- **Sortable Columns**: Click column headers to sort
+- **Pagination**: Automatic pagination with configurable page size
+- **Export**: Download data as CSV, Excel, or JSON
+- **Extensible**: Override any view or behavior in your host app
 
 ## Installation
 
@@ -25,7 +37,43 @@ bundle install
 
 ## Quick Start
 
-### 1. Ensure Your Application Has a Layout
+### 1. Ensure you have ActiveRecord model representing your data.
+
+```bash
+bin/rails generate model Task title:string description:text priority:integer completed:boolean due_date:date
+bin/rails db:migrate
+```
+
+### 2. Create a Controller for your ActiveRecord Model
+
+This controller handles one ActiveRecord model and presents a CRUD interface to the user. It derives from the ElaineCrud::BaseController, which provides good defaults for how the CRUD view should operate. The controller requires a working layout (see step 4).
+
+The main configuration is setting the ActiveRecord model using the `model Task` keyword, where Task is an ActiveRecord model. You also need to explicitly specify which model fields are permitted using the `permit_params` command.
+
+The following example controller provides a fully working CRUD view for the ActiveRecord with pagination, sorting, filtering and exporting. You can customise the behaviour, which is explained in more details later.
+
+```ruby
+class TaskController < ElaineCrud::BaseController
+  layout 'application'  # Use your app's layout (wraps ElaineCrud's content)
+
+  model Task
+  permit_params :title, :description, :priority, :completed, :due_date
+end
+```
+
+### 3. Add Routes
+
+You need to add the created Controller to the Rails routes.rb. In this example you simply declare `resources :tasks` where `:tasks` maps to the TaskController.
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  resources :tasks
+  root "tasks#index"
+end
+```
+
+### 4. Ensure Your Application Has a Layout
 
 ElaineCrud is a **content-only engine** - it provides CRUD views but relies on your application to provide the HTML structure (layout, navigation, styling).
 
@@ -35,256 +83,272 @@ Your Rails app should have a layout file (typically `app/views/layouts/applicati
 - JavaScript imports (including Turbo)
 - Navigation/header/footer (optional, your choice)
 
-Most Rails apps with TailwindCSS already have this. If not, ensure you have:
+Here's an example layout file, which contains the critical stylesheet_link_tag for elaine_crud:
 
 ```erb
-<!-- app/views/layouts/application.html.erb -->
 <!DOCTYPE html>
 <html>
   <head>
-    <title>Your App</title>
+    <title><%= content_for(:title) || "Taskmanager" %></title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
     <%= csrf_meta_tags %>
     <%= csp_meta_tag %>
-    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
+
+    <%= stylesheet_link_tag "elaine_crud", "data-turbo-track": "reload" %>
+    <%= stylesheet_link_tag :app, "data-turbo-track": "reload" %>
     <%= javascript_importmap_tags %>
   </head>
-  <body>
-    <%= yield %>
+
+  <body class="bg-gray-100">
+    <main class="w-full px-4 py-6">
+      <%= yield %>
+    </main>
   </body>
 </html>
 ```
 
-### 2. Create a Controller
+### 5. Start Your Server
 
-Specify which layout ElaineCrud should use with the `layout` directive:
+```bash
+bin/dev
+```
 
-```ruby
-class PeopleController < ElaineCrud::BaseController
-  layout 'application'  # Use your app's layout (wraps ElaineCrud's content)
+## Usage
 
-  model Person
-  permit_params :name, :email, :phone, :active
-end
-```
+### Extending the default Controller
 
-**Important**: The `layout 'application'` line tells ElaineCrud to render its CRUD views inside your application's layout. Without this, you'll see unstyled content with no HTML structure.
+As described earlier, this example controller uses a lot of default from the `ElaineCrud::BaseController`.
 
-### 3. Add Routes
+One of the first things user usually wants to customise is how a certain ActiveRecord property is rendered to the user.
 
 ```ruby
-# config/routes.rb
-resources :people
-```
+class TaskController < ElaineCrud::BaseController
+  layout 'application'  # Use your app's layout (wraps ElaineCrud's content)
 
-### 4. Add Stylesheet (Choose One Approach)
+  model Task
+  permit_params :title, :description, :priority, :completed, :due_date
 
-ElaineCrud offers two ways to handle styling:
+  # Configures the ActiveRecord field :title
+  field :title do
 
-#### Option A: Use Precompiled CSS (Easiest, Zero Config)
+    # Human readable name for the field, shown in the column header.
+    title "Task title"
 
-Add the precompiled stylesheet to your layout:
+    # Description is shown in the edit form
+    description "Write a short title for your task, so that it's easily understandable"
 
-```erb
-<!-- app/views/layouts/application.html.erb -->
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>Your App</title>
-    <%= stylesheet_link_tag "elaine_crud", "data-turbo-track": "reload" %>
-    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
-  </head>
-  <body>
-    <%= yield %>
-  </body>
-</html>
-```
+    # Custom rendering. `value` is the raw value of the field and `record` is the entire ActiveRecord
+    display_as { |value, record| "<b>#{value}</b>" if value.present? }
 
-**Pros:** No Tailwind configuration needed, works immediately
-**Cons:** Cannot customize Tailwind theme
-
-#### Option B: Scan ElaineCrud Sources (For Customization)
-
-If you want to customize the Tailwind theme, add ElaineCrud's views to your `tailwind.config.js`:
-
-```javascript
-const path = require('path')
-const execSync = require('child_process').execSync
-
-// Get the gem path from bundler
-const gemPath = execSync('bundle show elaine_crud', { encoding: 'utf-8' }).trim()
-
-module.exports = {
-  content: [
-    './app/views/**/*.html.erb',
-    './app/helpers/**/*.rb',
-    './app/assets/stylesheets/**/*.css',
-    './app/javascript/**/*.js',
-    // Add ElaineCrud gem views and helpers
-    path.join(gemPath, 'app/views/**/*.html.erb'),
-    path.join(gemPath, 'app/helpers/**/*.rb')
-  ],
-  theme: {
-    extend: {
-      // Your custom theme here
-    },
-  },
-}
-```
+    # By default text columns are searchable but not filterable. You can set a field to be filterable
+    # so that it shows in Advanced Filters section, but then it's no longer searchable
+    filterable true
 
-**Pros:** Full theme customization
-**Cons:** Requires Tailwind CSS build setup
+    # By default text columns are searchable and other columns are not
+    searchable false
+  end
 
-### 5. Restart Your Server
+  field :priority do
+    # Gives a html dropdown for available options
+    options [1,2,3,4,5]
+  end
 
-```bash
-rails server
-```
+  # `read_only` can be used prevent field from being edited
+  field :modified_at do
+    read_only true
+  end
 
-Navigate to `/people` and you'll have a fully functional CRUD interface!
+  # We can also hide a field completely
+  field :created_at do
+    hidden true
+  end
 
-## Usage
+end
+```
 
-### Basic Controller
+### Virtual fields
 
-The minimal controller setup:
+It is possible to create a virtual column which is not backed by any actual field in the ActiveRecord, but instead its contents is calculated based on other fields. For example if your Order has `amount` and `price_per_unit` fields, you could have a `total_cost` virtual field:
 
 ```ruby
-class ArticlesController < ElaineCrud::BaseController
-  layout 'application'  # Host app controls layout (header/footer/styling)
-  
-  model Article
-  permit_params :title, :content, :published
+class OrderController < ElaineCrud::BaseController
+  layout 'application'  # Use your app's layout (wraps ElaineCrud's content)
+
+  model Order
+  permit_params :product, :amount, :price_per_unit
+
+  # The field `total_cost` simply does not exists in the ActiveRecord model
+  field :total_cost do
+    readonly true
+    display_as { |value,record|
+      # The `value` parameter will be nil as it does not exists.
+      record.amount * record.price_per_unit
+    }
+  end
 end
 ```
 
-### DSL Reference
+### Relations
+
+ElaineCrud supports ActiveRecord relations automatically, if they are configured in the underlying ActiveRecords. Lets assume these models:
+```
+bin/rails generate model Department name:string
+bin/rails generate model Employee name:string email:string department:references
+bin/rails db:migrate
 
-- `model(ModelClass)` - Specify the ActiveRecord model to manage
-- `permit_params(*attrs)` - Define permitted attributes for strong parameters
-- `columns(config)` - (Future) Configure column display options
+# app/models/department.rb
+class Department < ApplicationRecord
+  has_many :employees
+end
 
-### Customization
+# app/models/employee.rb
+class Employee < ApplicationRecord
+  belongs_to :department
+end
+```
 
-#### Override Views
+We can then have a simple EmployeesController and DepartmentsController
+```ruby
+# app/controllers/employees_controller.rb
+class EmployeesController < ElaineCrud::BaseController
+  layout 'application'
 
-Create views in your app with the same names to override engine views:
+  model Employee
+  permit_params :name, :email, :department_id
+end
 
-```
-app/views/articles/index.html.erb  # Overrides engine's index view
-```
+# app/controllers/departments_controller.rb
+class DepartmentsController < ElaineCrud::BaseController
+  layout 'application'
 
-#### Override Controller Methods
+  model Department
+  permit_params :name
 
-```ruby
-class ArticlesController < ElaineCrud::BaseController
-  model Article
-  permit_params :title, :content, :published
-  
-  private
-  
-  # Custom record fetching with scoping
-  def fetch_records
-    Article.published.order(:title)
-  end
-  
-  # Custom column selection
-  def determine_columns
-    %w[title published created_at]
-  end
 end
 ```
 
-#### Custom Helpers
+This will automatically create a relation to the Departments in the EmployeesController field like this:
+![Image](docs/screenshots/employees.png)
 
-Override the display helper in your application:
+Also the Departments controller will have a back reference to show how many Employees are boudn to the Department.
+![Image](docs/screenshots/departments.png)
 
+
+### Misc options
 ```ruby
-# app/helpers/application_helper.rb
-def display_column_value(record, column)
-  case column
-  when 'published'
-    record.published? ? '📘 Published' : '📝 Draft'
-  else
-    super # Call the engine's helper
-  end
+# app/controllers/employees_controller.rb
+class EmployeesController < ElaineCrud::BaseController
+  layout 'application'
+
+  model Employee
+  permit_params :name, :email, :department_id
+
+  # Sets default sorting when the controller is opened
+  default_sort column: :email, direction: :asc
+
+  # Instead of editing a row in the inline editor using turbo, the Edit button
+  # opens /controller/#{id}/edit page
+  disable_turbo
+
+  # This adds a View button next to Edit and Delete buttons, which links to
+  # /controller/#{id}
+  show_view_button
+
+  # Limit how many rows the export functionality will be exporting. The default is 10000
+  max_export(5000)
 end
 ```
 
 ## Requirements
 
-- Rails 6.0+
-- TailwindCSS (for styling)
+- Rails 7.0+
+- TailwindCSS (included via precompiled CSS)
 
 ## Examples
 
-### Complete Example: Managing Blog Posts
+### More detailed example with customisations
+
+A more comprehensive example showing custom field formatting, sorting, and relationships. This example uses the more verbose block syntax with fields. Both approaches work and are valid.
 
 ```ruby
-# app/controllers/posts_controller.rb
-class PostsController < ElaineCrud::BaseController
-  layout 'application'  # Use your app's layout
-  
-  model Post
-  permit_params :title, :content, :published, :category_id
-  
-  private
-  
-  def fetch_records
-    Post.includes(:category).order(created_at: :desc)
+# app/controllers/products_controller.rb
+class ProductsController < ElaineCrud::BaseController
+  layout 'application'
+
+  model Product
+  permit_params :name, :description, :price, :stock_quantity, :category_id, :active
+
+  # Sort by name alphabetically by default
+  default_sort column: :name, direction: :asc
+
+  # Show the View button in actions column
+  show_view_button
+
+  # Format price as currency
+  field :price do |f|
+    f.title "Price"
+    f.display_as { |value, record| number_to_currency(value) if value.present? }
   end
-end
 
-# config/routes.rb
-resources :posts
+  # Custom display for stock status
+  field :stock_quantity do |f|
+    f.title "Stock"
+    f.display_as { |value, record|
+      if value.to_i > 10
+        content_tag(:span, "#{value} in stock", class: "text-green-600")
+      elsif value.to_i > 0
+        content_tag(:span, "Low: #{value}", class: "text-yellow-600 font-semibold")
+      else
+        content_tag(:span, "Out of stock", class: "text-red-600 font-semibold")
+      end
+    }
+  end
 
-# Navigate to /posts for instant CRUD interface
+  # Boolean with badge display
+  field :active do |f|
+    f.title "Status"
+    f.display_as { |value, record|
+      if value
+        content_tag(:span, "Active", class: "px-2 py-1 text-xs rounded bg-green-100 text-green-800")
+      else
+        content_tag(:span, "Inactive", class: "px-2 py-1 text-xs rounded bg-gray-100 text-gray-600")
+      end
+    }
+  end
+
+  # Foreign key - automatically renders as dropdown in forms
+  field :category_id do |f|
+    f.foreign_key model: Category, display: :name
+  end
+end
 ```
 
 ### Example Output
 
 The generated interface includes:
-- **Index Page**: Responsive table with all records
+- **Index Page**: Responsive grid-based table with all records
+- **Inline Editing**: Click Edit to modify records in place (Turbo Frames)
+- **Sortable Columns**: Click headers to sort ascending/descending
+- **Search**: Filter records by text across searchable columns
+- **Pagination**: Navigate through large datasets with configurable page size
+- **Export**: Download as CSV, Excel (.xlsx), or JSON
 - **Smart Formatting**: Dates, booleans, and nil values formatted nicely
 - **Action Buttons**: Edit and Delete functionality
 - **Empty States**: Helpful messages when no records exist
-- **Modern Styling**: Clean TailwindCSS design
+- **Visual Feedback**: Row highlights after saving changes
 
 ## Architecture
 
-ElaineCrud follows a **separation of concerns** approach:
-
-- **Engine provides**: CRUD logic, data formatting, content templates
-- **Host app provides**: Layout, styling, HTML structure, navigation
-
-### Layout Control
-
-The gem doesn't impose any layout - your app controls the HTML structure:
-
-```ruby
-class UsersController < ElaineCrud::BaseController
-  layout 'admin'        # Use admin layout
-  # or layout 'public'  # Use public layout
-  # or layout false     # No layout (API mode)
-  
-  model User
-  permit_params :name, :email
-end
-```
-
-This means:
-- ✅ **Your app controls**: Headers, footers, navigation, CSS frameworks
-- ✅ **Engine provides**: Table content, buttons, data formatting
-- ✅ **Zero view files needed**: No templates to create in your app
-
 See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed technical documentation.
 
 ## Contributing
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Submit a pull request
+1. Open a new issue and suggest a feature
+2. Fork the repository
+3. Create a feature branch
+4. Make your changes
+5. Add tests
+6. Submit a pull request
 
 ## License
 

data/app/controllers/elaine_crud/base_controller.rb

@@ -133,9 +133,9 @@ module ElaineCrud
       @filterable_columns = determine_filterable_columns
       @total_count = total_unfiltered_count if search_active?
 
-      # If Turbo is disabled, always render the full edit page
+      # If Turbo is disabled, render standalone edit form (no table context)
       if turbo_disabled?
-        render 'elaine_crud/base/edit'
+        render 'elaine_crud/base/edit_standalone'
       elsif turbo_frame_request?
         # For Turbo Frame requests, return just the edit row partial
         render partial: 'elaine_crud/base/edit_row', locals: { record: @record, columns: @columns }

data/app/views/elaine_crud/base/edit_standalone.html.erb

@@ -0,0 +1,12 @@
+<div class="container mx-auto px-4 py-8">
+  <div class="flex justify-between items-center mb-6">
+    <h1 class="text-3xl font-bold text-gray-900">Edit <%= @model_name %></h1>
+    <%= link_to "Back to #{@model_name.pluralize}",
+        url_for(action: :index),
+        class: "text-gray-600 hover:text-gray-900" %>
+  </div>
+
+  <div class="bg-white shadow-md rounded-lg p-6">
+    <%= render 'form', record: @record, submit_text: "Update #{@model_name}" %>
+  </div>
+</div>

data/lib/elaine_crud/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ElaineCrud
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: elaine_crud
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Garo
@@ -209,6 +209,7 @@ files:
 - app/views/elaine_crud/base/_show_details.html.erb
 - app/views/elaine_crud/base/_view_row.html.erb
 - app/views/elaine_crud/base/edit.html.erb
+- app/views/elaine_crud/base/edit_standalone.html.erb
 - app/views/elaine_crud/base/index.html.erb
 - app/views/elaine_crud/base/new.html.erb
 - app/views/elaine_crud/base/new_modal.html.erb
@@ -223,6 +224,9 @@ files:
 - docs/HAS_MANY_IMPLEMENTATION.md
 - docs/LAYOUT_EXAMPLES.md
 - docs/TROUBLESHOOTING.md
+- docs/screenshots/departments.png
+- docs/screenshots/employees.png
+- docs/screenshots/screenshot1.png
 - elaine_crud.gemspec
 - lib/elaine_crud.rb
 - lib/elaine_crud/dsl_methods.rb