Storefront Pages - Spree

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	`/`
Product Details	Individual product display page	Spree::Pages::ProductDetails	`/products/:id`
Taxon	Shows products filtered by taxon	Spree::Pages::Taxon	`/t/:permalink`
Search Results	Displays search results for products	Spree::Pages::SearchResults	`/search`
Shop All	Shows all products	Spree::Pages::ShopAll	`/products`
Blog	Shows your store's blog posts and articles	Spree::Pages::PostList	`/posts`
Post	Individual blog post	Spree::Pages::Post	`/posts/:permalink`
Password	Password page, when password protected storefront is enabled	Spree::Pages::Password	`/`

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. 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 the Admin -> Storefront -> Pages and clicking on the New Page button. More on this in the Create a Landing Page guide. Each custom landing page can be customized via page builder.

Under the hood they use Spree::Pages::Custom 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:

<Tabs> <Tab title="Spree 5.2+"> ```ruby config/initializers/spree.rb Rails.application.config.after_initialize do Spree.page_builder.pages << Spree::Pages::PickupLocations end ``` </Tab> <Tab title="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 ``` </Tab> </Tabs>

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 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 %>