@spree/docs 0.1.0 → 0.1.2

package/dist/developer/storefront/links.md

@@ -1,298 +0,0 @@
----
-title: "Links"
-sidebarTitle: "Links"
-description: "Learn how to use links for navigation in your Spree Storefront"
----
-
-Links are used to create navigation throughout the storefront. They can be assigned to [sections](/developer/storefront/sections) and [blocks](/developer/storefront/blocks), enabling users to navigate to different pages, products, categories, or external URLs.
-
-## How Links Work
-
-The `Spree::PageLink` model provides a flexible way to link to various content types:
-
-- **Internal pages** - Link to Pages, Products, Taxons, Posts
-- **External URLs** - Link to any external website
-- **Special links** - Email (`mailto:`) and phone (`tel:`) links
-
-Links are managed through the Page Builder interface, where store staff can select what each link points to.
-
-## Link Model
-
-The [Spree::PageLink](https://github.com/spree/spree/blob/main/core/app/models/spree/page_link.rb) model has these key attributes:
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `label` | String | Display text for the link |
-| `url` | String | Custom URL (for external links) |
-| `linkable` | Polymorphic | Reference to internal content (Page, Product, etc.) |
-| `parent` | Polymorphic | Section or Block the link belongs to |
-| `open_in_new_tab` | Boolean | Whether to open in new browser tab |
-| `position` | Integer | Order when multiple links exist |
-
-## Linkable Types
-
-Links can point to various Spree models:
-
-| Linkable Type | Description |
-|---------------|-------------|
-| `Spree::Page` | Internal pages (Home, Shop All, Custom pages) |
-| `Spree::Product` | Product detail pages |
-| `Spree::Taxon` | Category/collection pages |
-| `Spree::Post` | Blog posts |
-| Custom URL | Any external or internal URL |
-
-## Using Links in Sections
-
-### Single Link
-
-For sections that need one link (like a banner):
-
-```ruby app/models/spree/page_sections/promo_banner.rb
-module Spree
-  module PageSections
-    class PromoBanner < Spree::PageSection
-      has_one :link, ->(ps) { ps.links },
-              class_name: 'Spree::PageLink',
-              as: :parent,
-              dependent: :destroy,
-              inverse_of: :parent
-      accepts_nested_attributes_for :link
-
-      def default_links
-        @default_links.presence || [
-          Spree::PageLink.new(label: Spree.t(:shop_now))
-        ]
-      end
-    end
-  end
-end
-```
-
-### Multiple Links
-
-For sections that need multiple links (like navigation):
-
-```ruby app/models/spree/page_sections/footer.rb
-module Spree
-  module PageSections
-    class Footer < Spree::PageSection
-      # Links are provided by Spree::HasPageLinks concern
-      # which is included in Spree::PageSection by default
-
-      def default_links
-        @default_links.presence || [
-          Spree::PageLink.new(label: 'About Us'),
-          Spree::PageLink.new(label: 'Contact'),
-          Spree::PageLink.new(label: 'Privacy Policy')
-        ]
-      end
-    end
-  end
-end
-```
-
-## Using Links in Blocks
-
-Blocks can also have links. Use the `Spree::HasOneLink` concern for single links:
-
-```ruby app/models/spree/page_blocks/cta_button.rb
-module Spree
-  module PageBlocks
-    class CtaButton < Spree::PageBlock
-      include Spree::HasOneLink
-
-      preference :button_style, :string, default: 'primary'
-
-      # Called when the link is deleted
-      def link_destroyed(_link)
-        destroy if page_links_count.zero?
-      end
-    end
-  end
-end
-```
-
-## Accessing Links
-
-```ruby
-# Single link on a section
-section.link
-section.link.label
-section.link.linkable_url
-
-# Multiple links on a section
-section.links
-section.links.each do |link|
-  link.label
-  link.linkable_url
-end
-
-# Link on a block
-block.link
-block.link.label if block.link.present?
-```
-
-## Rendering Links
-
-### Using the Helper
-
-The `page_builder_link_to` helper renders links with Page Builder support:
-
-```erb
-<%# Basic usage %>
-<%= page_builder_link_to section.link %>
-
-<%# With custom label %>
-<%= page_builder_link_to section.link, label: 'Click Here' %>
-
-<%# With CSS class %>
-<%= page_builder_link_to section.link, class: 'btn-primary' %>
-
-<%# Open in new tab %>
-<%= page_builder_link_to section.link,
-    target: (section.link.open_in_new_tab ? '_blank' : nil),
-    rel: (section.link.open_in_new_tab ? 'noopener noreferrer' : nil) %>
-
-<%# With block content %>
-<%= page_builder_link_to section.link do %>
-  <span class="icon">→</span>
-  <%= section.link.label %>
-<% end %>
-```
-
-### Manual Link Rendering
-
-For more control, you can render links manually:
-
-```erb
-<% if section.link.present? %>
-  <%= link_to section.link.linkable_url,
-      target: (section.link.open_in_new_tab ? '_blank' : nil),
-      rel: (section.link.open_in_new_tab ? 'noopener noreferrer' : nil),
-      class: 'btn-primary' do %>
-    <%= section.link.label %>
-  <% end %>
-<% end %>
-```
-
-### Rendering Multiple Links
-
-```erb
-<nav class="footer-links">
-  <% section.links.each do |link| %>
-    <%= page_builder_link_to link, class: 'footer-link' %>
-  <% end %>
-</nav>
-```
-
-## Admin Form for Links
-
-In your section's admin form, render the link editor:
-
-### Single Link
-
-```erb app/views/spree/admin/page_sections/forms/_promo_banner.html.erb
-<%= render 'spree/admin/shared/page_section_image', f: f %>
-
-<div class="py-2">
-  <%= f.fields_for :link do |lf| %>
-    <div class="form-group">
-      <%= lf.label :linkable_type, Spree.t(:link) %>
-      <%= lf.select :linkable_type,
-          @page_section.allowed_linkable_types,
-          { include_blank: false },
-          { class: 'custom-select mb-3', data: { action: 'auto-submit#submit' } } %>
-
-      <div id="linkable_type_dropdown">
-        <%= render 'spree/admin/page_links/linkable_type_dropdown',
-            page_link: lf.object,
-            form_name: 'page_section[link_attributes]' %>
-      </div>
-    </div>
-
-    <div class="custom-control custom-checkbox">
-      <%= lf.check_box :open_in_new_tab,
-          class: 'custom-control-input',
-          data: { action: 'auto-submit#submit' } %>
-      <%= lf.label :open_in_new_tab, class: 'custom-control-label' %>
-    </div>
-  <% end %>
-</div>
-```
-
-## Link URL Resolution
-
-The `linkable_url` method returns the appropriate URL:
-
-```ruby
-link = Spree::PageLink.new(linkable: product)
-link.linkable_url
-# => "/products/red-shirt"
-
-link = Spree::PageLink.new(url: "https://example.com")
-link.linkable_url
-# => "https://example.com"
-
-link = Spree::PageLink.new(url: "example.com")
-link.formatted_url
-# => "http://example.com"  # Adds protocol automatically
-
-link = Spree::PageLink.new(url: "mailto:info@example.com")
-link.formatted_url
-# => "mailto:info@example.com"  # Preserves mailto: protocol
-```
-
-## Creating Links Programmatically
-
-```ruby
-# Link to an internal page
-link = Spree::PageLink.create!(
-  parent: section,
-  label: 'Shop Now',
-  linkable: store.pages.find_by(type: 'Spree::Pages::ShopAll')
-)
-
-# Link to a product
-link = Spree::PageLink.create!(
-  parent: section,
-  label: product.name,
-  linkable: product
-)
-
-# Link to a taxon
-link = Spree::PageLink.create!(
-  parent: section,
-  label: 'New Arrivals',
-  linkable: store.taxons.find_by(name: 'New Arrivals')
-)
-
-# External link
-link = Spree::PageLink.create!(
-  parent: section,
-  label: 'Visit Our Blog',
-  url: 'https://blog.example.com',
-  open_in_new_tab: true
-)
-```
-
-## Automatic Label Setting
-
-When a link's `linkable` is set, the label is automatically populated from the linked resource:
-
-```ruby
-link = Spree::PageLink.new(linkable: product)
-link.valid?
-link.label
-# => "Red T-Shirt" (from product.name)
-```
-
-The label is derived from (in order):
-1. `linkable.title`
-2. `linkable.display_name`
-3. `linkable.name`
-
-## Related Documentation
-
-- [Sections](/developer/storefront/sections) - Adding links to sections
-- [Blocks](/developer/storefront/blocks) - Adding links to blocks
-- [Pages](/developer/storefront/pages) - Understanding internal page linking

package/dist/developer/storefront/pages.md

@@ -1,163 +0,0 @@
----
-title: "Storefront Pages"
-sidebarTitle: "Pages"
-description: "Learn how to create and use pages in your Spree storefront"
----
-
-## Built-in Pages
-
-Spree Storefront comes with a full set of built-in pages that you can customize via page builder.
-
-| Page | Description | Class | URL |
-|------|-------------|-------|------------|
-| Home | The main landing page of your store | [Spree::Pages::Homepage](https://github.com/spree/spree/blob/main/core/app/models/spree/pages/homepage.rb) | `/` |
-| Product Details | Individual product display page | [Spree::Pages::ProductDetails](https://github.com/spree/spree/blob/main/core/app/models/spree/pages/product_details.rb) | `/products/:id` |
-| Taxon | Shows products filtered by taxon | [Spree::Pages::Taxon](https://github.com/spree/spree/blob/main/core/app/models/spree/pages/taxon.rb) | `/t/:permalink` |
-| Search Results | Displays search results for products | [Spree::Pages::SearchResults](https://github.com/spree/spree/blob/main/core/app/models/spree/pages/search_results.rb) | `/search` |
-| Shop All | Shows all products | [Spree::Pages::ShopAll](https://github.com/spree/spree/blob/main/core/app/models/spree/pages/shop_all.rb) | `/products` |
-| Blog | Shows your store's blog posts and articles | [Spree::Pages::PostList](https://github.com/spree/spree/blob/main/core/app/models/spree/pages/post_list.rb) | `/posts` |
-| Post | Individual blog post | [Spree::Pages::Post](https://github.com/spree/spree/blob/main/core/app/models/spree/pages/post.rb) | `/posts/:permalink` |
-| Password | Password page, when password protected storefront is enabled | [Spree::Pages::Password](https://github.com/spree/spree/blob/main/core/app/models/spree/pages/password.rb) | `/` |
-
-All of these page can be fully customized via page builder. You can add/remove sections, etc.
-
-We're planning to add page builder support for the following pages in the next Spree releases:
-
-- Cart
-- Checkout
-- Account
-
-## Sections
-
-Each page is made of [sections](/developer/storefront/sections). Sections are the building blocks of a page. They are used to create the page content.
-
-You can fetch page sections using:
-
-```ruby
-current_page.sections
-```
-
-## Custom Landing Pages in the Admin
-
-You can easily create your own landing pages by going to to the `Admin -> Storefront -> Pages` and clicking on the `New Page` button. More on this in the [Create a Landing Page](/user/storefront/create-page) guide. Each custom landing page can be customized via page builder. 
-
-![Landing Pages](/images/spree_admin_custom_landing_pages.png)
-
-Under the hood they use [Spree::Pages::Custom](https://github.com/spree/spree/blob/main/core/app/models/spree/pages/custom.rb) class.
-
-## Building a new Page from scratch
-
-If you need to build a page that is not one of the built-in pages, you can create your own page class. This will allow you to create a dedicated page for your business needs and at the same time allow your non-technical team to manage the page content without bugging you :)
-
-Let's assume you need to create a page that displays pickup locations. You already created a new model `Spree::PickupLocation` and added some data to the database. Now you want to create a page that displays these pickup locations.
-
-First, let's add a route for the new page.
-
-```ruby
-# config/routes.rb
-Spree::Core::Engine.add_routes do
-  scope '(:locale)', locale: /#{Spree.available_locales.join('|')}/, defaults: { locale: nil } do # this line will enable translations for the new page
-    resources :pickup_locations, only: [:index]
-  end
-end
-```
-
-Now, create the new page class file:
-
-```bash
-mkdir -p app/models/spree/pages && touch app/models/spree/pages/pickup_locations.rb
-```
-
-Now, let's add the new page class:
-
-```ruby
-module Spree
-  module Pages
-    class PickupLocations < Spree::Page
-      # use https://tabler.io/icons to find the icon name
-      def icon_name
-        'map-marker-alt'
-      end
-
-      # This method is used to determine if the page is customizable via page builder
-      def customizable?
-        true
-      end
-
-      # this is the URL used to preview the page in the page builder UI
-      def page_builder_url
-        return unless page_builder_url_exists?(:pickup_locations_path)
-
-        Spree::Core::Engine.routes.url_helpers.pickup_locations_path
-      end
-
-      # this is the default sections that will be shown on the page
-      # in the later guide for sections you will learn how to add custom sections
-      def default_sections
-        [
-          Spree::PageSections::PageTitle.new
-        ]
-      end
-    end
-  end
-end
-```
-
-You will need to register the new page in the `config/initializers/spree.rb` file:
-
-**Spree 5.2+:**
-
-```ruby config/initializers/spree.rb
-    Rails.application.config.after_initialize do
-      Spree.page_builder.pages << Spree::Pages::PickupLocations
-    end
-    ```
-
-  **Spree 5.1 and below:**
-
-```ruby config/initializers/spree.rb
-    Rails.application.config.after_initialize do
-      Rails.application.config.spree.pages << Spree::Pages::PickupLocations
-    end
-    ```
-
-
-Now, the controller:
-
-```bash
-mkdir -p app/controllers/spree && touch app/controllers/spree/pickup_locations_controller.rb
-```
-
-```ruby
-# app/controllers/spree/pickup_locations_controller.rb
-module Spree
-  class PickupLocationsController < StoreController
-    def index
-      @current_page = current_theme.pages.find_by(type: 'Spree::Pages::PickupLocations') # this is very important, without this the page will not be found
-      @pickup_locations = current_store.pickup_locations
-    end
-  end
-end
-```
-
-Lastly we need to add a view file for the page:
-
-```bash
-mkdir -p app/views/spree/pickup_locations && touch app/views/spree/pickup_locations/index.html.erb
-```
-
-And add the following code to the view file:
-
-```erb
-<%= render_page(current_page, pickup_locations: @pickup_locations) %>
-```
-
-`render_page` is a helper method defined in the [Spree::PageHelper](https://github.com/spree/spree/blob/main/storefront/app/helpers/spree/page_helper.rb) module that renders the page. It fetches all page sections and renders them one by one in the order they are set in the page builder by store staff.
-
-Passing `pickup_locations` variable to the `render_page` method allows you to use it in the page sections templates, eg.
-
-```erb
-<%= pickup_locations.each do |pickup_location| %>
-  <%= pickup_location.name %>
-<% end %>
-```