From 67f99c590c55a425762cf70da41643aa7a5bf6a9 Mon Sep 17 00:00:00 2001 From: Elia Schito Date: Tue, 19 Dec 2023 10:30:27 +0100 Subject: [PATCH] Rename SolidusAdmin::MainNavItem to SolidusAdmin::MenuItem Match the name in Backend to make it easier to reason about it. --- admin/README.md | 2 +- .../layout/navigation/component.rb | 4 +- .../layout/navigation/item/component.rb | 2 +- .../{main_nav.en.yml => menu_item.en.yml} | 2 +- ...avigation.md => customizing_menu_items.md} | 4 +- admin/docs/customizing_view_components.md | 55 ++++++------------- .../config/initializers/solidus_admin.rb.tt | 2 +- admin/lib/solidus_admin.rb | 2 +- .../{main_nav_item.rb => menu_item.rb} | 4 +- .../layout/navigation/component_preview.rb | 6 +- .../navigation/item/component_preview.rb | 4 +- .../typography/typography_preview.rb | 2 +- .../layout/navigation/item/component_spec.rb | 14 ++--- ...ain_nav_item_spec.rb => menu_item_spec.rb} | 2 +- 14 files changed, 42 insertions(+), 63 deletions(-) rename admin/config/locales/{main_nav.en.yml => menu_item.en.yml} (95%) rename admin/docs/{customizing_main_navigation.md => customizing_menu_items.md} (91%) rename admin/lib/solidus_admin/{main_nav_item.rb => menu_item.rb} (96%) rename admin/spec/solidus_admin/{main_nav_item_spec.rb => menu_item_spec.rb} (98%) diff --git a/admin/README.md b/admin/README.md index f3597311e39..6d9fc930feb 100644 --- a/admin/README.md +++ b/admin/README.md @@ -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 diff --git a/admin/app/components/solidus_admin/layout/navigation/component.rb b/admin/app/components/solidus_admin/layout/navigation/component.rb index d1945e48570..aa39629eb28 100644 --- a/admin/app/components/solidus_admin/layout/navigation/component.rb +++ b/admin/app/components/solidus_admin/layout/navigation/component.rb @@ -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 diff --git a/admin/app/components/solidus_admin/layout/navigation/item/component.rb b/admin/app/components/solidus_admin/layout/navigation/item/component.rb index 7a0a4443c50..17ac8a62f74 100644 --- a/admin/app/components/solidus_admin/layout/navigation/item/component.rb +++ b/admin/app/components/solidus_admin/layout/navigation/item/component.rb @@ -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( diff --git a/admin/config/locales/main_nav.en.yml b/admin/config/locales/menu_item.en.yml similarity index 95% rename from admin/config/locales/main_nav.en.yml rename to admin/config/locales/menu_item.en.yml index 6349c086e41..4fd38dbeb5c 100644 --- a/admin/config/locales/main_nav.en.yml +++ b/admin/config/locales/menu_item.en.yml @@ -1,6 +1,6 @@ en: solidus_admin: - main_nav: + menu_item: orders: Orders products: Products option_types: Option Types diff --git a/admin/docs/customizing_main_navigation.md b/admin/docs/customizing_menu_items.md similarity index 91% rename from admin/docs/customizing_main_navigation.md rename to admin/docs/customizing_menu_items.md index 47a12e124cf..64cb3b384ec 100644 --- a/admin/docs/customizing_main_navigation.md +++ b/admin/docs/customizing_menu_items.md @@ -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. diff --git a/admin/docs/customizing_view_components.md b/admin/docs/customizing_view_components.md index 9b80970dc22..79e1169fc15 100644 --- a/admin/docs/customizing_view_components.md +++ b/admin/docs/customizing_view_components.md @@ -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 %> - +```erb +<%# app/components/my_admin/navigation/item/component.html.erb %> +
  • <%= link_to @item.name, path %>
    • ``` ### 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 %>

    MY STORE ADMINISTRATION

    -<%= 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 diff --git a/admin/lib/generators/solidus_admin/install/templates/config/initializers/solidus_admin.rb.tt b/admin/lib/generators/solidus_admin/install/templates/config/initializers/solidus_admin.rb.tt index 7ae53e0de53..232d839007b 100644 --- a/admin/lib/generators/solidus_admin/install/templates/config/initializers/solidus_admin.rb.tt +++ b/admin/lib/generators/solidus_admin/install/templates/config/initializers/solidus_admin.rb.tt @@ -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, diff --git a/admin/lib/solidus_admin.rb b/admin/lib/solidus_admin.rb index 7a09f8f2911..d6961ea3f65 100644 --- a/admin/lib/solidus_admin.rb +++ b/admin/lib/solidus_admin.rb @@ -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" diff --git a/admin/lib/solidus_admin/main_nav_item.rb b/admin/lib/solidus_admin/menu_item.rb similarity index 96% rename from admin/lib/solidus_admin/main_nav_item.rb rename to admin/lib/solidus_admin/menu_item.rb index 33c2e012273..30fb803a35a 100644 --- a/admin/lib/solidus_admin/main_nav_item.rb +++ b/admin/lib/solidus_admin/menu_item.rb @@ -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 diff --git a/admin/spec/components/previews/solidus_admin/layout/navigation/component_preview.rb b/admin/spec/components/previews/solidus_admin/layout/navigation/component_preview.rb index 22d9004c239..b9081974bf6 100644 --- a/admin/spec/components/previews/solidus_admin/layout/navigation/component_preview.rb +++ b/admin/spec/components/previews/solidus_admin/layout/navigation/component_preview.rb @@ -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 # ) diff --git a/admin/spec/components/previews/solidus_admin/layout/navigation/item/component_preview.rb b/admin/spec/components/previews/solidus_admin/layout/navigation/item/component_preview.rb index 494ee181f61..b97b1c00392 100644 --- a/admin/spec/components/previews/solidus_admin/layout/navigation/item/component_preview.rb +++ b/admin/spec/components/previews/solidus_admin/layout/navigation/item/component_preview.rb @@ -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, diff --git a/admin/spec/components/previews/solidus_admin/typography/typography_preview.rb b/admin/spec/components/previews/solidus_admin/typography/typography_preview.rb index bac3190cc71..4830bf57bfd 100644 --- a/admin/spec/components/previews/solidus_admin/typography/typography_preview.rb +++ b/admin/spec/components/previews/solidus_admin/typography/typography_preview.rb @@ -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" diff --git a/admin/spec/components/solidus_admin/layout/navigation/item/component_spec.rb b/admin/spec/components/solidus_admin/layout/navigation/item/component_spec.rb index 566ec3fbf79..edc230ea2c6 100644 --- a/admin/spec/components/solidus_admin/layout/navigation/item/component_spec.rb +++ b/admin/spec/components/solidus_admin/layout/navigation/item/component_spec.rb @@ -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, diff --git a/admin/spec/solidus_admin/main_nav_item_spec.rb b/admin/spec/solidus_admin/menu_item_spec.rb similarity index 98% rename from admin/spec/solidus_admin/main_nav_item_spec.rb rename to admin/spec/solidus_admin/menu_item_spec.rb index ee3c8b78045..10905df1ce0 100644 --- a/admin/spec/solidus_admin/main_nav_item_spec.rb +++ b/admin/spec/solidus_admin/menu_item_spec.rb @@ -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),