@spree/docs 0.1.0

package/dist/developer/tutorial/file-uploads.md

@@ -0,0 +1,121 @@
+---
+title: File Uploads
+description: Learn how to add file uploads to the Brands feature
+---
+
+> **INFO:** This guide assumes you've completed the [Model](/developer/tutorial/model), [Admin](/developer/tutorial/admin), and [Rich Text](/developer/tutorial/rich-text) tutorials.
+
+In this tutorial, we'll add a logo image upload to our Brand model. Spree uses [Rails Active Storage](https://guides.rubyonrails.org/active_storage_overview.html) for handling file attachments, image processing, and storage.
+
+## Step 1: Add Attachment to the Model
+
+First, let's add a logo attachment to the Brand model:
+
+```ruby app/models/spree/brand.rb {3}
+module Spree
+  class Brand < Spree::Base
+    has_one_attached :logo
+
+    # ... existing code ...
+  end
+end
+```
+
+## Step 2: Permit the Attachment Attribute
+
+For the admin form to accept the file upload, we need to permit the `logo` attribute in the controller.
+
+Update your brands controller:
+
+```ruby app/controllers/spree/admin/brands_controller.rb {10}
+module Spree
+  module Admin
+    class BrandsController < ResourceController
+      private
+
+      def permitted_resource_params
+        params.require(:brand).permit(
+          :name,
+          :description,
+          :logo
+        )
+      end
+    end
+  end
+end
+```
+
+## Step 3: Add File Upload Field to the Admin Form
+
+Now let's add the file upload field to the brand form. Spree provides a `spree_file_field` helper that handles everything including:
+
+- Drag and drop upload
+- Image preview
+- Direct upload to storage
+- Optional image cropping
+
+Update your brand form partial:
+
+```erb app/views/spree/admin/brands/_form.html.erb {11-19}
+<div class="card mb-6">
+  <div class="card-header">
+    <h5 class="card-title"><%= Spree.t(:general_settings) %></h5>
+  </div>
+  <div class="card-body">
+    <%= f.spree_text_field :name, required: true %>
+    <%= f.spree_rich_text_area :description %>
+  </div>
+</div>
+
+<div class="card mb-6">
+  <div class="card-header">
+    <h5 class="card-title"><%= Spree.t(:logo) %></h5>
+  </div>
+  <div class="card-body">
+    <%= f.spree_file_field :logo, width: 300, height: 300 %>
+  </div>
+</div>
+```
+
+### Add cropping functionality
+
+To enable cropping functionality, add the `crop: true` option to the `spree_file_field` helper.
+
+## Step 4: Display the Logo in the Index Table
+
+Let's show a thumbnail of the brand logo in the admin index view.
+
+Update the table header partial:
+
+```erb app/views/spree/admin/brands/_table_header.html.erb {2}
+<tr>
+  <th><%= Spree.t(:logo) %></th>
+  <th><%= Spree.t(:name) %></th>
+  <th></th>
+</tr>
+```
+
+Update the table row partial to display the logo:
+
+```erb app/views/spree/admin/brands/_table_row.html.erb {3-12}
+<tr id="<%= spree_dom_id brand %>" class="cursor-pointer" data-controller="row-link">
+  <td data-action="click->row-link#openLink" class="w-70">
+    <div class="d-flex align-items-center gap-2">
+      <% if brand.logo.attached? %>
+        <%= spree_image_tag brand.logo, width: 48, height: 48, class: 'rounded' %>
+      <% else %>
+        <div class="bg-light rounded d-flex align-items-center justify-content-center" style="width: 48px; height: 48px;">
+          <%= icon('photo-off', class: 'text-muted') %>
+        </div>
+      <% end %>
+      <span class="font-weight-bold"><%= brand.name %></span>
+    </div>
+  </td>
+  <td data-action="click->row-link#openLink" class="w-20">
+    <%= spree_date(brand.created_at) %>
+  </td>
+  <td class="actions w-10">
+    <%= link_to_edit(brand, data: { row_link_target: :link, turbo_frame: '_top' }) if can? :edit, brand %>
+  </td>
+</tr>
+```

package/dist/developer/tutorial/introduction.md

@@ -0,0 +1,33 @@
+---
+title: Tutorial
+sidebarTitle: Introduction
+description: Learn how to build a custom feature from scratch, covering models, Admin dashboard, API and Storefront.
+---
+
+This tutorial walks you through creating a complete Spree feature from scratch, covering models, Admin dashboard and API. 
+You will also learn how to extend core Spree features to connect them with your new feature.
+By the end, you'll understand how to add new manageable features to the Spree platform.
+
+## Overview
+
+To fully implement a new feature, you will typically create the following components:
+
+* Database model
+* Admin Dashboard controllers and views
+* Storefront views
+* Automated tests
+
+## Tutorial Sections
+
+
+  - [1. Model](/developer/tutorial/model) — Create the Brand model with migrations, validations, and associations
+  - [2. Admin Dashboard](/developer/tutorial/admin) — Build admin interface for managing brands
+  - [3. Rich Text](/developer/tutorial/rich-text) — Add rich text descriptions using Action Text
+  - [4. File Uploads](/developer/tutorial/file-uploads) — Add logo images with Active Storage
+  - [5. Extending Core Models](/developer/tutorial/extending-models) — Connect Brands to Products using associations
+  - [7. Testing](/developer/tutorial/testing) — Write automated tests for your feature
+
+
+## Example: Building a Brands Feature
+
+In this guide we will create a complete "Brands" feature that allows admins to manage [Product](/developer/core-concepts/products) brands.

package/dist/developer/tutorial/model.md

@@ -0,0 +1,41 @@
+---
+title: Model
+description: Learn how to create a database model for the Brands feature
+---
+
+## Step 1: Create the Model and Database Migration
+
+To create a new model and database migration file, run the following command:
+
+```bash
+bin/rails g spree:model Spree::Brand name:string:index
+```
+
+This will create a couple of files:
+- `app/models/spree/brand.rb` - the model file
+- `db/migrate/XXXXXXXXXXXXXX_create_spree_brands.rb` - the database migration file
+
+Now run the migration:
+
+```bash
+bin/rails db:migrate
+```
+
+This will create the table `spree_brands` with the column `name` in the database. The `name` column is indexed for faster lookups. Also the model file `app/models/spree/brand.rb` is created.
+
+## Step 2: Extend the Model file
+
+Now that the model file is created, let's add some additional functionality to it, starting with validations:
+
+```ruby app/models/spree/brand.rb {3-4}
+module Spree
+  class Brand < Spree::Base
+    # Validations
+    validates :name, presence: true
+  end
+end
+```
+
+This is a standard [Ruby on Rails ActiveRecord model](https://guides.rubyonrails.org/active_record_basics.html). Let's break down each part:
+- Inherits from `Spree::Base` to automatically inherit all Spree functionality. Also the model itself is namespaced under `Spree::` module, so it's available as `Spree::Brand` in the application.
+- `validates :name, presence: true` - using ActiveRecord validations to ensure that the name is present.

package/dist/developer/tutorial/page-builder.md

@@ -0,0 +1,487 @@
+---
+title: Page Builder Integration
+description: Learn how to connect your Brands feature to Page Builder for admin-manageable pages
+---
+
+In this tutorial, we'll enhance our brand pages by integrating them with Spree's Page Builder. This allows store administrators to customize page layouts, add sections, and modify designs without touching code.
+
+> **INFO:** This guide assumes you've completed the [Storefront](/developer/tutorial/storefront) tutorial and have working brand pages.
+
+## What We're Building
+
+By the end of this tutorial, you'll have:
+
+- A **Brand List** page type manageable via Page Builder
+- A **Brand** page type for individual brand pages
+- Custom sections: `BrandGrid` and `BrandBanner`
+- Full admin customization support
+
+## Understanding Page Builder Architecture
+
+Page Builder uses three main components:
+
+| Component | Purpose |
+|-----------|---------|
+| **Page** | Defines the page type (e.g., Homepage, Product Details, Brand List) |
+| **Section** | Reusable content blocks within a page (e.g., Hero Banner, Product Grid) |
+| **Block** | Smallest units within sections (e.g., Heading, Text, Button) |
+
+## Step 1: Create Page Types
+
+### Brand List Page
+
+Create a page type for the brands listing:
+
+```ruby app/models/spree/pages/brand_list.rb
+module Spree
+  module Pages
+    class BrandList < Spree::Page
+      def icon_name
+        'building-store'
+      end
+
+      def customizable?
+        true
+      end
+
+      def page_builder_url
+        return unless page_builder_url_exists?(:brands_path)
+
+        Spree::Core::Engine.routes.url_helpers.brands_path
+      end
+
+      def default_sections
+        [
+          Spree::PageSections::PageTitle.new(
+            preferred_heading: Spree.t(:brands)
+          ),
+          Spree::PageSections::BrandGrid.new
+        ]
+      end
+    end
+  end
+end
+```
+
+### Brand Page
+
+Create a page type for individual brand pages:
+
+```ruby app/models/spree/pages/brand.rb
+module Spree
+  module Pages
+    class Brand < Spree::Page
+      def icon_name
+        'tag'
+      end
+
+      def customizable?
+        true
+      end
+
+      def page_builder_url
+        return unless page_builder_url_exists?(:brands_path)
+
+        brand = Spree::Brand.first
+        return unless brand
+
+        Spree::Core::Engine.routes.url_helpers.brand_path(brand)
+      end
+
+      def default_sections
+        [
+          Spree::PageSections::BrandBanner.new,
+          Spree::PageSections::ProductGrid.new(
+            preferred_heading: Spree.t(:products)
+          )
+        ]
+      end
+    end
+  end
+end
+```
+
+## Step 2: Register Pages
+
+Add your pages to the Spree configuration:
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  # Register custom pages
+  Spree.page_builder.pages += [
+    Spree::Pages::BrandList,
+    Spree::Pages::Brand
+  ]
+end
+```
+
+## Step 3: Create Custom Sections
+
+### Brand Grid Section
+
+This section displays a grid of all brands:
+
+```ruby app/models/spree/page_sections/brand_grid.rb
+module Spree
+  module PageSections
+    class BrandGrid < Spree::PageSection
+      TOP_PADDING_DEFAULT = 40
+      BOTTOM_PADDING_DEFAULT = 40
+
+      preference :show_description, :boolean, default: false
+
+      def icon_name
+        'layout-grid'
+      end
+
+      # Content sections can be added/removed in Page Builder
+      def self.role
+        'content'
+      end
+
+      def brands
+        Spree::Brand.order(:name)
+      end
+    end
+  end
+end
+```
+
+### Brand Banner Section
+
+This section displays the brand header with logo and description:
+
+```ruby app/models/spree/page_sections/brand_banner.rb
+module Spree
+  module PageSections
+    class BrandBanner < Spree::PageSection
+      TOP_PADDING_DEFAULT = 60
+      BOTTOM_PADDING_DEFAULT = 40
+
+      preference :show_logo, :boolean, default: true
+      preference :show_description, :boolean, default: true
+      preference :layout, :string, default: 'horizontal'
+
+      before_validation :ensure_valid_layout
+
+      def icon_name
+        'id-badge'
+      end
+
+      # System sections are part of the core page functionality
+      def self.role
+        'system'
+      end
+
+      def can_be_deleted?
+        false
+      end
+
+      private
+
+      def ensure_valid_layout
+        self.preferred_layout = 'horizontal' unless %w[horizontal vertical].include?(preferred_layout)
+      end
+    end
+  end
+end
+```
+
+## Step 4: Register Sections
+
+Add your sections to the configuration:
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  # Register custom pages
+  Spree.page_builder.pages += [
+    Spree::Pages::BrandList,
+    Spree::Pages::Brand
+  ]
+
+  # Register custom sections
+  Spree.page_builder.page_sections += [
+    Spree::PageSections::BrandGrid,
+    Spree::PageSections::BrandBanner
+  ]
+end
+```
+
+## Step 5: Create Admin Forms
+
+Admin section forms use Spree's Admin Form Builder, which provides helper methods like `spree_select` and `spree_check_box` for consistent styling and functionality.
+
+### Brand Grid Admin Form
+
+```erb app/views/spree/admin/page_sections/forms/_brand_grid.html.erb
+<%= f.spree_check_box :preferred_show_description,
+    label: Spree.t(:show_description),
+    data: { action: 'auto-submit#submit' } %>
+```
+
+### Brand Banner Admin Form
+
+```erb app/views/spree/admin/page_sections/forms/_brand_banner.html.erb
+<%= f.spree_check_box :preferred_show_logo,
+    label: Spree.t(:show_logo),
+    data: { action: 'auto-submit#submit' } %>
+
+<%= f.spree_check_box :preferred_show_description,
+    label: Spree.t(:show_description),
+    data: { action: 'auto-submit#submit' } %>
+
+<% content_for(:design_tab) do %>
+  <%= f.spree_select :preferred_layout,
+      options_for_select([
+        [Spree.t(:horizontal), 'horizontal'],
+        [Spree.t(:vertical), 'vertical']
+      ], @page_section.preferred_layout),
+      { label: Spree.t(:layout) },
+      { data: { action: 'auto-submit#submit' } } %>
+  <hr />
+<% end %>
+```
+
+## Step 6: Create Storefront Views
+
+### Brand Grid Section View
+
+```erb app/views/themes/default/spree/page_sections/_brand_grid.html.erb
+<% cache_unless page_builder_enabled?, spree_storefront_base_cache_scope.call(section) do %>
+  <div style="<%= section_styles(section) %>">
+    <div class="page-container">
+      <% brands = section.brands %>
+      <% if brands.any? %>
+        <div class="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
+          <% brands.each do |brand| %>
+            <%= link_to spree.brand_path(brand),
+                class: 'block group',
+                data: { turbo_frame: '_top' } do %>
+              <div class="aspect-square bg-accent rounded-lg overflow-hidden mb-3">
+                <% if brand.logo.attached? %>
+                  <%= spree_image_tag brand.logo,
+                      width: 300,
+                      height: 300,
+                      class: 'w-full h-full object-contain p-6 group-hover:scale-105 transition-transform',
+                      alt: brand.name %>
+                <% else %>
+                  <div class="w-full h-full flex items-center justify-center">
+                    <span class="text-4xl font-medium text-neutral-400">
+                      <%= brand.name.first.upcase %>
+                    </span>
+                  </div>
+                <% end %>
+              </div>
+              <h3 class="font-medium group-hover:text-primary transition-colors">
+                <%= brand.name %>
+              </h3>
+              <% if section.preferred_show_description && brand.description.present? %>
+                <p class="mt-1 text-sm text-neutral-600 line-clamp-2">
+                  <%= brand.description.to_plain_text.truncate(100) %>
+                </p>
+              <% end %>
+            <% end %>
+          <% end %>
+        </div>
+      <% else %>
+        <p class="text-neutral-600"><%= Spree.t(:no_brands_found) %></p>
+      <% end %>
+    </div>
+  </div>
+<% end %>
+```
+
+### Brand Banner Section View
+
+```erb app/views/themes/default/spree/page_sections/_brand_banner.html.erb
+<% cache_unless page_builder_enabled?, spree_storefront_base_cache_scope.call(section) do %>
+  <div style="<%= section_styles(section) %>">
+    <div class="page-container">
+      <% if brand.present? %>
+        <div class="<%= section.preferred_layout == 'horizontal' ? 'flex flex-col md:flex-row gap-8 items-start' : 'text-center' %>">
+          <% if section.preferred_show_logo && brand.logo.attached? %>
+            <div class="<%= section.preferred_layout == 'horizontal' ? 'w-32 h-32 flex-shrink-0' : 'w-40 h-40 mx-auto mb-6' %> bg-accent rounded-lg">
+              <%= spree_image_tag brand.logo,
+                  width: 160,
+                  height: 160,
+                  class: 'w-full h-full object-contain p-4',
+                  alt: brand.name %>
+            </div>
+          <% end %>
+
+          <div>
+            <h1 class="text-2xl lg:text-3xl font-medium mb-4">
+              <%= brand.name %>
+            </h1>
+
+            <% if section.preferred_show_description && brand.description.present? %>
+              <div class="prose max-w-none text-neutral-600">
+                <%= brand.description %>
+              </div>
+            <% end %>
+          </div>
+        </div>
+      <% end %>
+    </div>
+  </div>
+<% end %>
+```
+
+## Step 7: Update the Controller
+
+Update your controller to use Page Builder pages:
+
+```ruby app/controllers/spree/brands_controller.rb
+module Spree
+  class BrandsController < StoreController
+    before_action :load_brand, only: [:show]
+
+    def index
+      # Load the Page Builder page
+      @current_page = current_theme.pages.find_by(type: 'Spree::Pages::BrandList')
+
+      # Fallback data if sections need it
+      @brands = Spree::Brand.order(:name)
+    end
+
+    def show
+      # Load the Page Builder page
+      @current_page = current_theme.pages.find_by(type: 'Spree::Pages::Brand')
+
+      # Load products for the ProductGrid section
+      @products = @brand.products
+                        .active(current_currency)
+                        .includes(storefront_products_includes)
+                        .page(params[:page])
+                        .per(12)
+    end
+
+    private
+
+    def load_brand
+      @brand = Spree::Brand.find(params[:id])
+    end
+
+    def accurate_title
+      if @brand
+        @brand.meta_title.presence || @brand.name
+      else
+        Spree.t(:brands)
+      end
+    end
+  end
+end
+```
+
+## Step 8: Update Views to Use Page Builder
+
+### Brand List Index View
+
+```erb app/views/themes/default/spree/brands/index.html.erb
+<%= render_page(@current_page, brands: @brands) %>
+```
+
+### Brand Show View
+
+```erb app/views/themes/default/spree/brands/show.html.erb
+<%= render_page(@current_page, brand: @brand, products: @products) %>
+```
+
+The `render_page` helper automatically renders all sections in the order defined in Page Builder.
+
+## Step 9: Passing Variables to Sections
+
+Section views receive variables passed to `render_page`. Update your section views to use them:
+
+```erb app/views/themes/default/spree/page_sections/_brand_banner.html.erb
+<% # 'brand' variable is passed from the controller via render_page %>
+<% cache_unless page_builder_enabled?, [spree_storefront_base_cache_scope.call(section), brand] do %>
+  <div style="<%= section_styles(section) %>">
+    <%# ... use 'brand' variable ... %>
+  </div>
+<% end %>
+```
+
+## Step 10: Add Translations
+
+```yaml config/locales/en.yml
+en:
+  spree:
+    brands: Brands
+    no_brands_found: No brands found.
+    products_by_brand: "Products by %{brand}"
+    show_description: Show description
+    show_logo: Show logo
+    layout: Layout
+    horizontal: Horizontal
+    vertical: Vertical
+```
+
+## Testing Page Builder Integration
+
+1. Start your Rails server
+2. Go to **Admin → Storefront → Pages**
+3. You should see "Brand List" and "Brand" pages
+4. Click on a page to customize it in Page Builder
+5. Add, remove, or reorder sections
+6. Customize section settings
+7. Preview changes in real-time
+
+## Section Roles Explained
+
+| Role | Description | Can Delete? | Example |
+|------|-------------|-------------|---------|
+| `content` | General content sections | Yes | BrandGrid, ImageBanner |
+| `system` | Core page functionality | No | BrandBanner, ProductDetails |
+| `header` | Layout header sections | No | Header, AnnouncementBar |
+| `footer` | Layout footer sections | No | Footer, Newsletter |
+
+## Complete File Structure
+
+After completing this tutorial, you should have:
+
+```
+app/
+├── controllers/spree/
+│   └── brands_controller.rb
+├── models/spree/
+│   ├── pages/
+│   │   ├── brand.rb
+│   │   └── brand_list.rb
+│   └── page_sections/
+│       ├── brand_banner.rb
+│       └── brand_grid.rb
+└── views/
+    ├── spree/admin/page_sections/forms/
+    │   ├── _brand_banner.html.erb
+    │   └── _brand_grid.html.erb
+    └── themes/default/spree/
+        ├── brands/
+        │   ├── index.html.erb
+        │   └── show.html.erb
+        └── page_sections/
+            ├── _brand_banner.html.erb
+            └── _brand_grid.html.erb
+
+config/
+├── initializers/
+│   └── spree.rb  (updated)
+└── locales/
+    └── en.yml    (updated)
+```
+
+## Benefits of Page Builder Integration
+
+| Without Page Builder | With Page Builder |
+|---------------------|-------------------|
+| Developers edit views for layout changes | Admins customize layouts in browser |
+| Code deployment required for design changes | Real-time preview and publish |
+| Fixed page structure | Drag-and-drop section ordering |
+| Hardcoded settings | Admin-configurable preferences |
+
+## Related Documentation
+
+- [Sections](/developer/storefront/sections) - Creating custom sections
+- [Blocks](/developer/storefront/blocks) - Adding blocks to sections
+- [Pages](/developer/storefront/pages) - Page types and routing
+- [Themes](/developer/storefront/themes) - Theme customization