rails_templatable 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a6b1d092af3d36bb5050dc292d447db84040459eff960a6fb4f7e6d012ef07c
+  data.tar.gz: 0115da00cf3adc178efaccdacf79c1942894886931543f81d5620aa5467ecf2f
+SHA512:
+  metadata.gz: d2ec972556b40651aecfaba05b9a23ec0321126838fda933adef084baea0003e474d1b1f0e3dccd7d23c20ac836fb1ce55052ec32f2689ccf9cd1dc7bad9feb7
+  data.tar.gz: af8843f690fa3b1c6c2bef5e982d540c00f7ef44d573ff9976b80c3601bbd5c02b2799c62118a6a74425334d08c383f077909059eca7af1f0f5c96d1f38dff11

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright aric.zheng
+
+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,205 @@
+# RailsTemplatable
+
+A lightweight Rails Engine that enables any ActiveRecord model to associate with templates for content management. Built with a polymorphic many-to-many relationship, allowing any model to have multiple templates.
+
+## Features
+
+- 🎯 **Polymorphic Associations** - Attach templates to any ActiveRecord model
+- 📝 **Multiple Content Formats** - Support for HTML, Markdown, and plain text
+- 🔗 **Many-to-Many Relationship** - Models can have multiple templates, templates can be used by multiple models
+- 🏷️ **Flexible Categories** - User-defined template categories (no hardcoded types)
+- 🔒 **Database Constraints** - Unique constraints at database level
+- 🚀 **Easy Integration** - Simple concern-based inclusion
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails_templatable"
+```
+
+And then execute:
+```bash
+$ bundle install
+$ bin/rails railties:install:migrations FROM=rails_templatable
+$ bin/rails db:migrate
+```
+
+## Quick Start
+
+### 1. Enable templates in your models
+
+```ruby
+class Post < ApplicationRecord
+  include RailsTemplatable::HasTemplates
+end
+
+class WorkLog < ApplicationRecord
+  include RailsTemplatable::HasTemplates
+end
+```
+
+### 2. Create templates
+
+```ruby
+# HTML template
+email_template = RailsTemplatable::Template.create!(
+  category: "email_template",
+  content: "<h1>Welcome!</h1><p>Hello {{name}}</p>",
+  content_format: :html
+)
+
+# Markdown template
+doc_template = RailsTemplatable::Template.create!(
+  category: "documentation",
+  content: "# Documentation\n\nThis is a **markdown** template.",
+  content_format: :markdown
+)
+```
+
+### 3. Associate templates with models
+
+```ruby
+post = Post.create(title: "My Post", content: "Content here")
+
+# Add templates
+post.templates << email_template
+post.templates << doc_template
+
+# Query templates
+post.templates.where(category: "email_template")
+```
+
+## Content Formats
+
+The engine supports three content formats out of the box:
+
+- `html` (0) - HTML content
+- `markdown` (1) - Markdown content
+- `txt` (2) - Plain text content (default)
+
+```ruby
+RailsTemplatable::Template.create!(
+  category: "notification",
+  content: "Simple text notification",
+  content_format: :txt
+)
+```
+
+## Database Schema
+
+### rails_templatable_templates
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `category` | string | Template category (user-defined) |
+| `content` | text | Template content |
+| `content_format` | integer | Content format (0: html, 1: markdown, 2: txt) |
+| `created_at` | datetime | Creation timestamp |
+| `updated_at` | datetime | Update timestamp |
+
+### rails_templatable_assignments
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `template_id` | integer | Foreign key to template |
+| `templatable_id` | integer | Polymorphic foreign key ID |
+| `templatable_type` | string | Polymorphic foreign key type |
+| `created_at` | datetime | Creation timestamp |
+| `updated_at` | datetime | Update timestamp |
+
+## Advanced Usage
+
+### Query helper methods
+
+```ruby
+# Get all objects using a specific template
+template.assigned_to(Post)
+
+# Get all templates used on a specific model class
+RailsTemplatable::Template.for_model(Post)
+```
+
+### Checking template associations
+
+```ruby
+# Check if a post has email templates
+post.templates.where(category: "email_template").exists?
+
+# Get all HTML format templates
+post.templates.html
+```
+
+## Why `category` instead of `type`?
+
+We use `category` instead of `type` to avoid conflicts with Rails' Single Table Inheritance (STI) feature, which reserves the `type` column for storing class names.
+
+## Development
+
+### Running tests in the dummy app
+
+```bash
+cd test/dummy
+ruby test_templatable.rb
+```
+
+### Database schema
+
+After running migrations, your schema will include:
+
+```ruby
+create_table "rails_templatable_templates" do |t|
+  t.string "category", null: false
+  t.text "content"
+  t.integer "content_format", default: 2, null: false
+  t.index ["category"], name: "index_rails_templatable_templates_on_category"
+end
+
+create_table "rails_templatable_assignments" do |t|
+  t.integer "template_id", null: false
+  t.string "templatable_type", null: false
+  t.integer "templatable_id", null: false
+  t.index ["template_id", "templatable_type", "templatable_id"],
+          name: "index_templatable_assignments", unique: true
+end
+```
+
+## Architecture
+
+This engine follows the same pattern as [rails_badgeable](https://github.com/afeiship/rails_badgeable):
+
+- **Isolated namespace** - All models namespaced under `RailsTemplatable`
+- **Polymorphic associations** - Using `templatable` for flexible model associations
+- **Concern-based inclusion** - Simple `include RailsTemplatable::HasTemplates` to enable
+- **Database-level constraints** - Unique indexes prevent duplicate associations
+
+## Comparison with rails_badgeable
+
+| Feature | rails_badgeable | rails_templatable |
+|---------|-----------------|-------------------|
+| Main Model | Badge | Template |
+| Fields | name, description | category, content, content_format |
+| Enum Support | No | Yes (content_format) |
+| Polymorphic Name | assignable | templatable |
+| Concern | HasBadges | HasTemplates |
+
+## Future Enhancements
+
+- Template variable interpolation
+- Template versioning
+- Template inheritance
+- Template preview functionality
+- I18n multi-language support
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Built with inspiration from [rails_badgeable](https://github.com/afeiship/rails_badgeable).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/rails_templatable/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/rails_templatable/application_controller.rb

@@ -0,0 +1,4 @@
+module RailsTemplatable
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/rails_templatable/application_helper.rb

@@ -0,0 +1,4 @@
+module RailsTemplatable
+  module ApplicationHelper
+  end
+end

data/app/jobs/rails_templatable/application_job.rb

@@ -0,0 +1,4 @@
+module RailsTemplatable
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/rails_templatable/application_mailer.rb

@@ -0,0 +1,6 @@
+module RailsTemplatable
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/concerns/rails_templatable/has_templates.rb

@@ -0,0 +1,16 @@
+module RailsTemplatable
+  module HasTemplates
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :rails_templatable_assignments,
+               as: :templatable,
+               class_name: "RailsTemplatable::TemplateAssignment",
+               dependent: :destroy
+
+      has_many :templates,
+               through: :rails_templatable_assignments,
+               class_name: "RailsTemplatable::Template"
+    end
+  end
+end

data/app/models/rails_templatable/application_record.rb

@@ -0,0 +1,5 @@
+module RailsTemplatable
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/rails_templatable/template.rb

@@ -0,0 +1,25 @@
+module RailsTemplatable
+  class Template < ApplicationRecord
+    self.table_name = "rails_templatable_templates"
+
+    has_many :assignments, class_name: "RailsTemplatable::TemplateAssignment", dependent: :destroy
+
+    enum :content_format, { html: 0, markdown: 1, txt: 2 }
+
+    validates :category, presence: true
+    validates :content, presence: true
+    validates :content_format, presence: true
+
+    # Returns all associated records of the given class that have this template
+    def assigned_to(klass)
+      templatable_ids = assignments.where(templatable_type: klass.base_class.name).pluck(:templatable_id)
+      klass.where(id: templatable_ids)
+    end
+
+    # Class method: Returns all templates ever used on the given model class
+    def self.for_model(klass)
+      template_ids = TemplateAssignment.where(templatable_type: klass.base_class.name).distinct.pluck(:template_id)
+      where(id: template_ids)
+    end
+  end
+end

data/app/models/rails_templatable/template_assignment.rb

@@ -0,0 +1,12 @@
+module RailsTemplatable
+  class TemplateAssignment < ApplicationRecord
+    self.table_name = "rails_templatable_assignments"
+
+    belongs_to :template, class_name: "RailsTemplatable::Template"
+    belongs_to :templatable, polymorphic: true
+
+    validates :template, presence: true
+    validates :templatable, presence: true
+    validates :template_id, uniqueness: { scope: [:templatable_type, :templatable_id] }
+  end
+end

data/app/views/layouts/rails_templatable/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Rails templatable</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "rails_templatable/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+RailsTemplatable::Engine.routes.draw do
+end

data/db/migrate/20250207000000_create_rails_templatable_tables.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class CreateRailsTemplatableTables < ActiveRecord::Migration[6.0]
+  def change
+    # Create templates table
+    # To add custom fields to templates, add columns here, e.g.:
+    #   t.string :name
+    #   t.text :description
+    create_table :rails_templatable_templates do |t|
+      t.string :category, null: false
+      t.text :content
+      t.integer :content_format, null: false, default: 2
+
+      t.timestamps
+    end
+
+    add_index :rails_templatable_templates, :category
+
+    # Create join table for polymorphic associations
+    # To add custom fields to assignments, add columns here, e.g.:
+    #   t.integer :priority
+    #   t.boolean :active, default: true
+    create_table :rails_templatable_assignments do |t|
+      t.references :template, null: false, foreign_key: { to_table: :rails_templatable_templates }
+      t.references :templatable, polymorphic: true, null: false, index: false
+
+      t.timestamps
+    end
+
+    # Custom composite index with short name
+    add_index :rails_templatable_assignments,
+              [:template_id, :templatable_type, :templatable_id],
+              unique: true,
+              name: "index_templatable_assignments"
+  end
+end

data/lib/rails_templatable/engine.rb

@@ -0,0 +1,5 @@
+module RailsTemplatable
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsTemplatable
+  end
+end

data/lib/rails_templatable/version.rb

@@ -0,0 +1,3 @@
+module RailsTemplatable
+  VERSION = "0.1.1"
+end

data/lib/rails_templatable.rb

@@ -0,0 +1,6 @@
+require "rails_templatable/version"
+require "rails_templatable/engine"
+
+module RailsTemplatable
+  # Your code goes here...
+end

data/lib/tasks/rails_templatable_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :rails_templatable do
+#   # Task goes here
+# end

data/llms.txt

@@ -0,0 +1,433 @@
+# Rails Templatable
+
+> Rails Templatable is a lightweight, reusable Rails Engine that enables any ActiveRecord model to associate with templates for content management via polymorphic many-to-many relationships.
+
+It provides a clean, namespace-isolated way to add template functionality to your Rails applications without polluting your models or database schema. The engine uses standard Rails conventions and is fully compatible with Rails 6.0+.
+
+**Important notes for AI agents:**
+- This is a Rails Engine, not a mountable engine (no routes, controllers, or views)
+- All models are namespaced under `RailsTemplatable` module
+- Table names are explicitly set to avoid conflicts: `rails_templatable_templates` and `rails_templatable_assignments`
+- The engine uses polymorphic associations, allowing templates to be assigned to ANY model
+- Uses `category` instead of `type` to avoid Rails STI (Single Table Inheritance) conflicts
+- Supports three content formats: HTML (0), Markdown (1), and TXT (2)
+- The `content_format` field uses Rails enum with new syntax: `enum :content_format, { html: 0, markdown: 1, txt: 2 }`
+
+## Documentation
+
+- [GitHub Repository](https://github.com/afeiship/rails_templatable): Source code and issue tracking
+- [README](README.md): Installation guide and basic usage examples
+- [PRD](docs/01-prd.md): Detailed product requirements and design specifications
+- [Usage Guide](docs/02-usage.md): Comprehensive usage examples
+- [Implementation Summary](docs/03-implementation-summary.md): Implementation details and testing results
+
+## Key Features
+
+- **Polymorphic Associations:** Assign templates to any ActiveRecord model (Post, WorkLog, User, etc.)
+- **Multiple Content Formats:** Support for HTML, Markdown, and plain text templates
+- **Database-level Constraints:** Unique indexes prevent duplicate template assignments
+- **Namespace Isolated:** All models under `RailsTemplatable` namespace to avoid conflicts
+- **Explicit Table Names:** No reliance on Rails auto-inflection
+- **Flexible Categories:** User-defined template categories (no hardcoded types)
+- **Rails 6.0+ Compatible:** Works with modern Rails versions (tested on Rails 8.1.2)
+- **Zero Configuration:** Works out of the box after migration
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'rails_templatable'
+```
+
+Run migrations:
+
+```bash
+rails railties:install:migrations FROM=rails_templatable
+rails db:migrate
+```
+
+## Basic Usage
+
+### Include the Concern
+
+```ruby
+class Post < ApplicationRecord
+  include RailsTemplatable::HasTemplates
+end
+
+class WorkLog < ApplicationRecord
+  include RailsTemplatable::HasTemplates
+end
+```
+
+### Create and Assign Templates
+
+```ruby
+# Create an HTML template
+email_template = RailsTemplatable::Template.create!(
+  category: "email_template",
+  content: "<h1>Welcome!</h1><p>Hello {{name}}</p>",
+  content_format: :html
+)
+
+# Create a Markdown template
+doc_template = RailsTemplatable::Template.create!(
+  category: "documentation",
+  content: "# Documentation\n\nThis is a **markdown** template.",
+  content_format: :markdown
+)
+
+# Assign to a post
+post = Post.create(title: "Hello World")
+post.templates << email_template
+post.templates << doc_template
+
+# Check if post has the template
+post.templates.include?(email_template) # => true
+```
+
+### Query Methods
+
+```ruby
+# Get all posts with a specific template
+template.assigned_to(Post)
+# => [#<Post id: 1, ...>, #<Post id: 3, ...>]
+
+# Get all templates ever used on Post model
+RailsTemplatable::Template.for_model(Post)
+# => [#<RailsTemplatable::Template category: "email_template">, ...]
+
+# Filter templates by category
+post.templates.where(category: "email_template")
+
+# Filter templates by content format
+post.templates.html      # HTML templates only
+post.templates.markdown  # Markdown templates only
+post.templates.txt       # Plain text templates only
+```
+
+### Remove Templates
+
+```ruby
+# Remove a specific template
+post.templates.destroy(email_template)
+
+# Remove all templates
+post.templates.clear
+```
+
+## Database Schema
+
+### templates table
+
+```ruby
+create_table :rails_templatable_templates do |t|
+  t.string :category, null: false
+  t.text :content
+  t.integer :content_format, null: false, default: 2
+  t.timestamps
+end
+
+add_index :rails_templatable_templates, :category
+```
+
+**Field Details:**
+- `category` (string) - User-defined template category (e.g., "email_template", "documentation")
+- `content` (text) - Template content (static text, no variable replacement)
+- `content_format` (integer) - Content format: 0=HTML, 1=Markdown, 2=TXT (default)
+- Index on `category` for fast lookups
+
+### assignments table (join table)
+
+```ruby
+create_table :rails_templatable_assignments do |t|
+  t.references :template, null: false, foreign_key: { to_table: :rails_templatable_templates }
+  t.references :templatable, polymorphic: true, null: false
+  t.timestamps
+end
+
+add_index :rails_templatable_assignments,
+          [:template_id, :templatable_type, :templatable_id],
+          unique: true,
+          name: "index_templatable_assignments"
+```
+
+**Constraint:** Unique composite index prevents duplicate template assignments to the same record.
+
+## Content Formats
+
+The engine supports three content formats via Rails enum:
+
+```ruby
+enum :content_format, {
+  html: 0,      # HTML content
+  markdown: 1,  # Markdown content
+  txt: 2        # Plain text content (default)
+}
+```
+
+**Usage:**
+
+```ruby
+# Create different format templates
+html_template = RailsTemplatable::Template.create!(
+  category: "email",
+  content: "<h1>Welcome</h1>",
+  content_format: :html
+)
+
+markdown_template = RailsTemplatable::Template.create!(
+  category: "docs",
+  content: "# Guide\n\nInstructions here",
+  content_format: :markdown
+)
+
+txt_template = RailsTemplatable::Template.create!(
+  category: "notification",
+  content: "Simple text message",
+  content_format: :txt
+)
+
+# Query by format
+post.templates.html      # => [#<RailsTemplatable::Template content_format: 0>]
+post.templates.markdown  # => [#<RailsTemplatable::Template content_format: 1>]
+post.templates.txt       # => [#<RailsTemplatable::Template content_format: 2>]
+```
+
+## Available Methods
+
+### Template Instance Methods
+
+- `template.assigned_to(klass)` - Returns all records of the given class that have this template
+  ```ruby
+  template.assigned_to(Post)     # => [post1, post2]
+  template.assigned_to(WorkLog)  # => [work_log1, work_log3]
+  ```
+
+### Template Class Methods
+
+- `RailsTemplatable::Template.for_model(klass)` - Returns all templates ever used on the given model class
+  ```ruby
+  RailsTemplatable::Template.for_model(Post)  # => [template1, template2]
+  ```
+
+### Model Methods (with HasTemplates concern)
+
+- `model.templates` - Returns all templates assigned to this record
+- `model.templates << template` - Assign a template to this record
+- `model.templates.delete(template)` - Remove a specific template
+- `model.templates.clear` - Remove all templates
+- `model.rails_templatable_assignments` - Direct access to join records
+- `model.templates.where(category: "email_template")` - Filter by category
+- `model.templates.html` - Get HTML format templates only
+- `model.templates.markdown` - Get Markdown format templates only
+- `model.templates.txt` - Get plain text templates only
+
+## Advanced Usage
+
+### Custom Fields
+
+You can add custom fields to templates or assignments via migrations:
+
+```ruby
+# Add custom fields to templates
+add_column :rails_templatable_templates, :name, :string
+add_column :rails_templatable_templates, :description, :text
+add_column :rails_templatable_templates, :locale, :string, default: 'en'
+
+# Add custom fields to assignments
+add_column :rails_templatable_assignments, :priority, :integer, default: 0
+add_column :rails_templatable_assignments, :active, :boolean, default: true
+add_column :rails_templatable_assignments, :assigned_at, :datetime
+```
+
+### Accessing Assignment Data
+
+```ruby
+# Get assignment metadata
+assignment = post.rails_templatable_assignments.find_by(template_id: 1)
+assignment.priority  # => 1
+assignment.created_at  # => assignment time
+```
+
+### Conditional Scopes
+
+Add scopes to your models:
+
+```ruby
+class Post < ApplicationRecord
+  include RailsTemplatable::HasTemplates
+
+  scope :with_email_template, -> {
+    joins(:templates)
+      .where(rails_templatable_templates: { category: 'email_template' })
+  }
+
+  scope :with_html_templates, -> {
+    joins(:templates)
+      .where(rails_templatable_templates: { content_format: 0 })
+  }
+end
+
+# Usage
+Post.with_email_template  # All posts with email templates
+Post.with_html_templates  # All posts with HTML templates
+```
+
+### Checking Template Existence
+
+```ruby
+# Check if a post has templates from a specific category
+post.templates.where(category: "email_template").exists?  # => true/false
+
+# Check if a post has HTML templates
+post.templates.html.any?  # => true/false
+
+# Count templates by format
+post.templates.html.count      # => 2
+post.templates.markdown.count  # => 1
+post.templates.txt.count       # => 0
+```
+
+## Testing
+
+Run the test script in the dummy app:
+
+```bash
+cd test/dummy
+ruby test_templatable.rb
+```
+
+Expected output:
+```
+🚀 Testing Rails Templatable Engine
+==================================================
+
+📝 Creating templates...
+✓ Created HTML email template
+✓ Created Markdown documentation template
+✓ Created text notification template
+
+📄 Creating Posts and WorkLogs...
+✓ Created 2 Posts and 2 WorkLogs
+
+🔗 Associating templates with models...
+✓ Templates associated successfully
+
+🔍 Testing queries...
+  Post1 has 2 templates
+  Post1 templates: email_template, documentation
+  ...
+
+✅ All tests passed successfully!
+==================================================
+```
+
+## Project Structure
+
+```
+lib/
+├── rails_templatable.rb              # Main entry point
+├── rails_templatable/
+│   ├── engine.rb                     # Engine definition
+│   └── version.rb                    # Version info
+app/models/
+├── rails_templatable/
+│   ├── application_record.rb         # Base AR class
+│   ├── template.rb                   # Template model
+│   └── template_assignment.rb        # Join model
+└── models/concerns/
+    └── rails_templatable/
+        └── has_templates.rb          # Concern for host models
+db/migrate/
+└── 20250207000000_create_rails_templatable_tables.rb  # Migration
+test/dummy/
+├── app/models/
+│   ├── post.rb                       # Example: Post with HasTemplates
+│   └── work_log.rb                   # Example: WorkLog with HasTemplates
+├── db/schema.rb                      # Database schema
+└── test_templatable.rb               # Integration test script
+docs/
+├── 01-prd.md                         # Product Requirements Document
+├── 02-usage.md                       # Usage Guide
+└── 03-implementation-summary.md      # Implementation Summary
+```
+
+## Comparison with rails_badgeable
+
+| Feature | rails_badgeable | rails_templatable |
+|---------|-----------------|-------------------|
+| Main Model | Badge | Template |
+| Fields | name, description | category, content, content_format |
+| Enum Support | No | Yes (content_format: html/markdown/txt) |
+| Polymorphic Name | assignable | templatable |
+| Concern | HasBadges | HasTemplates |
+| STI Conflict Handling | N/A | Uses `category` to avoid `type` conflict |
+
+## Usage Notes for Agents
+
+- **Always use full namespace:** `RailsTemplatable::Template` (no alias generator yet)
+- **Categories are user-defined:** No predefined categories, use any string value
+- **Content formats are enforced:** Use symbols: `:html`, `:markdown`, `:txt`
+- **Polymorphic type stores class name:** Uses `base_class.name` for STI support
+- **Database prevents duplicates:** Unique index on `[template_id, templatable_type, templatable_id]`
+- **Engine is not mountable:** No routes, controllers, or views included
+- **Migrations must be copied:** Use `rails railties:install:migrations FROM=rails_templatable`
+- **Custom fields require migration:** Add columns directly to tables if needed
+- **Join table accessible:** `model.rails_templatable_assignments` for metadata access
+- **`category` field is indexed:** Efficient queries by category
+- **Default content_format is TXT:** New templates default to plain text (2)
+- **Rails 8.x enum syntax:** Must use `enum :content_format, { ... }` not `enum content_format: { ... }`
+
+## Architecture Decisions
+
+### Why `category` instead of `type`?
+
+Rails reserves the `type` column for Single Table Inheritance (STI). To avoid conflicts:
+- We use `category` for template classification
+- Users can define any category string (email_template, documentation, etc.)
+- No hardcoded enum or predefined types
+
+### Why explicit table names?
+
+To prevent any naming conflicts:
+- `rails_templatable_templates` - Template storage
+- `rails_templatable_assignments` - Polymorphic join table
+- No reliance on Rails auto-inflection
+
+### Why enum for content_format?
+
+Using Rails enum provides:
+- Type safety (only valid formats)
+- Helper methods (`html`, `markdown`, `txt`)
+- Integer storage for efficiency
+- Easy to extend with new formats
+
+## Development
+
+- Rails Engine (non-mountable)
+- Ruby 3.0+ required
+- Rails 6.0+ compatible (tested on Rails 8.1.2)
+- MIT License
+- Author: aric.zheng <1290657123@qq.com>
+- Version: 0.1.0
+
+## Future Enhancements
+
+Planned features for future versions:
+- Template variable interpolation (replace `{{name}}` with actual data)
+- Template versioning system
+- Template inheritance and overriding
+- Template preview functionality
+- I18n multi-language support
+- Short alias generator (like rails_badgeable)
+
+## Contributing
+
+When contributing to rails_templatable:
+1. Follow the existing architecture patterns
+2. Maintain backward compatibility
+3. Add tests for new features
+4. Update this llms.txt file with API changes
+5. Ensure Rails 6.0+ compatibility

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: rails_templatable
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- aric.zheng
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: A lightweight Rails Engine that enables any ActiveRecord model to use
+  templates for content generation and management.
+email:
+- 1290657123@qq.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/rails_templatable/application.css
+- app/controllers/rails_templatable/application_controller.rb
+- app/helpers/rails_templatable/application_helper.rb
+- app/jobs/rails_templatable/application_job.rb
+- app/mailers/rails_templatable/application_mailer.rb
+- app/models/concerns/rails_templatable/has_templates.rb
+- app/models/rails_templatable/application_record.rb
+- app/models/rails_templatable/template.rb
+- app/models/rails_templatable/template_assignment.rb
+- app/views/layouts/rails_templatable/application.html.erb
+- config/routes.rb
+- db/migrate/20250207000000_create_rails_templatable_tables.rb
+- lib/rails_templatable.rb
+- lib/rails_templatable/engine.rb
+- lib/rails_templatable/version.rb
+- lib/tasks/rails_templatable_tasks.rake
+- llms.txt
+homepage: https://github.com/afeiship/rails_templatable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/afeiship/rails_templatable
+  changelog_uri: https://github.com/afeiship/rails_templatable/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/afeiship/rails_templatable/blob/main/README.md
+  ai_assistant_uri: https://github.com/afeiship/rails_templatable/blob/main/llms.txt
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Rails engine for templatable models.
+test_files: []