solidusio · elia · Dec 19, 2023 · Dec 19, 2023
@@ -6,7 +6,7 @@ A Rails engine that provides an administrative interface to the Solidus ecommerc
 
 - [Customizing tailwind](docs/customizing_tailwind.md)
 - [Customizing view components](docs/customizing_view_components.md)
-- [Customizing the main navigation](docs/customizing_main_navigation.md)
+- [Customizing the main navigation](docs/customizing_menu_items.md)
 
 ### Adding components to Solidus Admin
 

@@ -9,8 +9,8 @@ def initialize(
   )
     @logo_path = logo_path
     @items = items.map do |attrs|
-      children = attrs[:children].to_a.map { SolidusAdmin::MainNavItem.new(**_1, top_level: false) }
-      SolidusAdmin::MainNavItem.new(**attrs, children: children, top_level: true)
+      children = attrs[:children].to_a.map { SolidusAdmin::MenuItem.new(**_1, top_level: false) }
+      SolidusAdmin::MenuItem.new(**attrs, children: children, top_level: true)
     end
     @store = store
   end

@@ -4,7 +4,7 @@
 class SolidusAdmin::Layout::Navigation::Item::Component < SolidusAdmin::BaseComponent
   with_collection_parameter :item
 
-  # @param item [SolidusAdmin::MainNavItem]
+  # @param item [SolidusAdmin::MenuItem]
   # @param fullpath [String] the current path
   # @param url_helpers [#solidus_admin, #spree] context for generating paths
   def initialize(

@@ -1,6 +1,6 @@
 en:
   solidus_admin:
-    main_nav:
+    menu_item:
       orders: Orders
       products: Products
       option_types: Option Types

@@ -1,6 +1,6 @@
 # Customizing the main navigation
 
-You are allowed to add your custom links to the main navigation. To do so, you can access `SolidusAdmin::Config.main_nav` in an initializer:
+You are allowed to add your custom links to the main navigation. To do so, you can access `SolidusAdmin::Config.menu_items` in an initializer:
 
 ```ruby
 # config/initializers/solidus_admin.rb
@@ -13,7 +13,7 @@ SolidusAdmin::Config.menu_items << {
 ```
 
 - The key you provide will be used to translate the link's label under the
-`solidus_admin.main_nav.#{key}` key.
+`solidus_admin.menu_item.#{key}` key.
 - Icon needs to be an icon name from [Remixicon](https://remixicon.com/).
 - Position tells Solidus where to place the link in the main navigation. The
  default items are placed with 10 points of difference between them.

@@ -11,18 +11,12 @@ All the components Solidus Admin uses are located in the [`app/components`](../a
 - They are grouped in sidecar directories, where the main component file and
   all its related files (assets, i18n files, etc.) live together.
 
-For instance, the component for the main navigation is located in
-[`app/components/solidus_admin/main_nav/component.rb`](../app/components/solidus_admin/main_nav/component.rb).
-
 Solidus Admin components are designed to be easily customizable by the host
 application. Because of that, if you look at how they are designed, you'll find
 a series of patterns are followed consistently:
 
 - Components are always resolved from a global registry in
-  `SolidusAdmin::Config.components` instead of being referenced by their constant. For
-  example, we call `component('main_nav')` instead of referencing
-  `SolidusAdmin::MainNav::Component` directly. As you'll see later, this makes
-  it easy to replace or tweak a component.
+  `SolidusAdmin::Config.components` instead of being referenced by their constant.
 - It's possible to override the registry locally inside a component by redefining
   the `#component` method. This is useful when you need to use a component that
   is not registered in the global registry or need to address some edge case.
@@ -50,37 +44,22 @@ end
 # render component('foo').new
 ```
 
-## Customizing components
-
-Some of the customizations detailed below require you to match Solidus Admin's
-component paths in your application. For instance, if we talk about the
-component in `solidus_admin` gem's
-`app/components/solidus_admin/main_nav/component.rb`, the matching path in your
-application would be
-`app/components/my_application/solidus_admin/main_nav/component.rb`, where
-`my_application` is the underscored name of your application (you can get it by
-running `Rails.application.class.module_parent_name`).
-
 ### Replacing a component's template
 
 In the most typical case, you'll only need to replace the template used by a
 component. You can do that by creating a new component with a maching path in
 your application, inheriting from the default one. Then, you can create a new
-template for it. For example, to replace the main nav template:
+template for it. For example, to replace the menu item template:
 
-```erb
-# app/components/my_application/solidus_admin/main_nav/component.rb %>
-class MyApplication::SolidusAdmin::MainNav::Component < ::SolidusAdmin::MainNav::Component
+```rb
+# app/components/my_admin/navigation/item/component.rb
+class MyAdmin::Navigation::Item::Component < SolidusAdmin::Layout::Navigation::Item::Component
 end
+```
 
-<%# app/components/my_application/solidus_admin/main_nav/component.html.erb %>
-<nav class="my_own_classes">
-  <%=
-    render main_nav_item_component.with_collection(
-      sorted_items
-    )
-  %>
-</nav>
+```erb
+<%# app/components/my_admin/navigation/item/component.html.erb %>
+<li><%= link_to @item.name, path %></li>
 ```
 
 ### Prepending or appending to a component's template
@@ -90,9 +69,9 @@ component. You can easily do that by rendering the Solidus Admin component and
 adding your markup before or after it.
 
 ```erb
-<%# app/components/my_application/solidus_admin/main_nav/component.html.erb %>
+<%# app/components/my_admin/menu_item/component.html.erb %>
 <h1>MY STORE ADMINISTRATION</h1>
-<%= render SolidusAdmin::MainNav::Component.new %>
+<%= render SolidusAdmin::MenuItem::Component.new %>
 ```
 
 ### Replacing a component
@@ -109,12 +88,12 @@ There are two considerations to keep in mind:
   [SolidusAdmin::BaseComponent](../app/components/solidus_admin/base_component.rb).
   You can consider doing the same if you need to use one of its helpers.
 
-For example, the following replaces the main nav component:
+For example, the following replaces the menu item component:
 
 ```ruby
-# app/components/my_application/solidus_admin/main_nav/component.rb
-class MyApplication::SolidusAdmin::MainNav::Component < SolidusAdmin::BaseComponent
-  # do your thing
+# app/components/my_admin/menu_item/component.rb
+class MyAdmin::MenuItem::Component < SolidusAdmin::BaseComponent
+  # Here goes your code
 end
 ```
 
@@ -138,8 +117,8 @@ matching path from within your application (or manually add it to the
 registry) and override the methods you need to change:
 
 ```ruby
-# app/components/my_application/solidus_admin/main_nav/component.rb
-class MyApplication::SolidusAdmin::MainNav::Component < ::SolidusAdmin::MainNav::Component
+# app/components/my_admin/menu_item/component.rb
+class MyAdmin::MenuItem::Component < SolidusAdmin::MenuItem::Component
   def sorted_items
     super.reverse
   end

@@ -23,7 +23,7 @@ SolidusAdmin::Config.configure do |config|
   # config.importmap_paths << Rails.root.join("config/solidus_admin_importmap.rb")
   #
   # Configure the main navigation.
-  # See SolidusAdmin::MainNavItem for more details.
+  # See SolidusAdmin::MenuItem for more details.
   # config.menu_items << {
   #   key: :my_custom_link,
   #   route: :my_custom_link_path,

@@ -6,7 +6,7 @@
 module SolidusAdmin
   require "solidus_admin/version"
   require "solidus_admin/importmap"
-  require "solidus_admin/main_nav_item"
+  require "solidus_admin/menu_item"
   require "solidus_admin/preview"
 
   require "solidus_admin/configuration"

@@ -2,7 +2,7 @@
 
 module SolidusAdmin
   # Encapsulates the data for a main navigation item.
-  class MainNavItem
+  class MenuItem
     # @!attribute [r] key
     #  @return [String] a unique identifier for this item
     attr_reader :key
@@ -45,7 +45,7 @@ def initialize(
     end
 
     def name
-      I18n.t("solidus_admin.main_nav.#{key}", default: key.to_s.humanize)
+      I18n.t("solidus_admin.menu_item.#{key}", default: key.to_s.humanize)
     end
 
     # @return [Boolean] whether this item has any children

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "solidus_admin/main_nav_item"
+require "solidus_admin/menu_item"
 
 # @component "layout/navigation"
 class SolidusAdmin::Layout::Navigation::ComponentPreview < ViewComponent::Preview
@@ -9,11 +9,11 @@ class SolidusAdmin::Layout::Navigation::ComponentPreview < ViewComponent::Previe
   # The item component is used to render main navigation items, which are
   # rendered within the sidebar.
   #
-  # It needs to be passed a {SolidusAdmin::MainNavItem} instance, which
+  # It needs to be passed a {SolidusAdmin::MenuItem} instance, which
   # represents the data for a main navigation item.
   #
   # ```ruby
-  # item = SolidusAdmin::MainNavItem.new(
+  # item = SolidusAdmin::MenuItem.new(
   #   key: :overview,
   #   position: 80
   # )

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "solidus_admin/main_nav_item"
+require "solidus_admin/menu_item"
 
 # @component "layout/navigation/item"
 class SolidusAdmin::Layout::Navigation::Item::ComponentPreview < ViewComponent::Preview
@@ -14,7 +14,7 @@ class SolidusAdmin::Layout::Navigation::Item::ComponentPreview < ViewComponent::
   # @param key text { description: "ID also used for i18n" }
   # @param icon text { description: "RemixIcon name (https://remixicon.com/)" }
   def overview(active: false, key: "orders", icon: "inbox-line")
-    item = SolidusAdmin::MainNavItem.new(
+    item = SolidusAdmin::MenuItem.new(
       key: key,
       icon: icon,
       position: 1,

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "solidus_admin/main_nav_item"
+require "solidus_admin/menu_item"
 
 class SolidusAdmin::Typography::TypographyPreview < ViewComponent::Preview
   layout "solidus_admin/preview"

@@ -15,7 +15,7 @@ def url_helpers(solidus_admin: {}, spree: {})
   end
 
   it "renders the item" do
-    item = SolidusAdmin::MainNavItem.new(key: "orders", route: :orders_path, position: 1)
+    item = SolidusAdmin::MenuItem.new(key: "orders", route: :orders_path, position: 1)
     component = described_class.new(
       item: item,
       url_helpers: url_helpers(solidus_admin: { orders_path: "/admin/foo" })
@@ -27,8 +27,8 @@ def url_helpers(solidus_admin: {}, spree: {})
   end
 
   it "renders nested items" do
-    item = SolidusAdmin::MainNavItem.new(key: "products", route: :products_path, position: 1, children: [
-      SolidusAdmin::MainNavItem.new(key: "option_types", route: :option_types_path, position: 1, top_level: false)
+    item = SolidusAdmin::MenuItem.new(key: "products", route: :products_path, position: 1, children: [
+      SolidusAdmin::MenuItem.new(key: "option_types", route: :option_types_path, position: 1, top_level: false)
     ])
     component = described_class.new(
       item: item,
@@ -41,8 +41,8 @@ def url_helpers(solidus_admin: {}, spree: {})
   end
 
   it "syles top level items differently from nested items" do
-    item = SolidusAdmin::MainNavItem.new(key: "products", route: :products_path, position: 1, children: [
-      SolidusAdmin::MainNavItem.new(key: "option_types", route: :option_types_path, position: 1, top_level: false)
+    item = SolidusAdmin::MenuItem.new(key: "products", route: :products_path, position: 1, children: [
+      SolidusAdmin::MenuItem.new(key: "option_types", route: :option_types_path, position: 1, top_level: false)
     ])
     component = described_class.new(
       item: item,
@@ -59,9 +59,9 @@ def url_helpers(solidus_admin: {}, spree: {})
   end
 
   it "syles active items differently from the others" do
-    inactive_item = SolidusAdmin::MainNavItem
+    inactive_item = SolidusAdmin::MenuItem
                     .new(key: "orders", route: :orders_path, position: 1)
-    active_item = SolidusAdmin::MainNavItem
+    active_item = SolidusAdmin::MenuItem
                   .new(key: "products", route: :products_path, position: 1)
     inactive_component = described_class.new(
       item: inactive_item,

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe SolidusAdmin::MainNavItem do
+RSpec.describe SolidusAdmin::MenuItem do
   def url_helpers(solidus_admin: {}, spree: {})
     double(
       solidus_admin: double(**solidus_admin),