katalyst-navigation 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94de0bbf95ab99d4893ec9decb52fa6c1a7231f1d58d17b1263e63124baaf10a
-  data.tar.gz: 3ec009c2845a80e4371aca788ac2b06de9a602cc468afecbbb5666d5a50fcb07
+  metadata.gz: 94cc7f739764b2d65865d91d0d6f1431671bee909e285b51238f4343dd15883e
+  data.tar.gz: 51a2493050682848606784167c351865776daa9cc403e59e096e269b55afc208
 SHA512:
-  metadata.gz: 043ce598613d8f99b98d777be94b0805d1504989eab5dba1e651a8d7fa2a2d8d4f89135530e300e65d37fea900237cba0e2a30caa7e95e81ab17000639bba5bb
-  data.tar.gz: c0795c1f30ed8ecea198e90d90097bcb6728bcbe2e7116ecd106e0c21c6e97e9c68a4ff981586bfa9436a22a7e63adf8c33da00f593541b17e77d316675fe4bb
+  metadata.gz: 51127826086e93bdc9d6796f8eab5096c0d4a1d6af14a0623f3387a6c567263b6f28351507f5bcb683cce7f88f0a5832ac7583e2a28d59b31463eeeba8b09710
+  data.tar.gz: 1b7b2e4b291da7ae044b6c5de3c5df0a0d56b5ba111d7fbf454648916baf2a8634cfbc2c94216a3f327ad5ffba51440b00ca5d052bcf0d55b070b345de2a72ea

data/app/assets/javascripts/controllers/navigation/editor/menu_controller.js

@@ -6,6 +6,9 @@ import RulesEngine from "utils/navigation/editor/rules-engine";
 
 export default class MenuController extends Controller {
   static targets = ["menu"];
+  static values = {
+    maxDepth: Number,
+  };
 
   connect() {
     this.state = this.menu.state;
@@ -85,7 +88,7 @@ export default class MenuController extends Controller {
       if (!this.updateRequested) return;
 
       this.updateRequested = false;
-      const engine = new RulesEngine();
+      const engine = new RulesEngine(this.maxDepthValue);
       this.menu.items.forEach((item) => engine.update(item));
 
       this.#notifyChange();

data/app/assets/javascripts/utils/navigation/editor/rules-engine.js

@@ -9,6 +9,10 @@ export default class RulesEngine {
     "denyEdit",
   ];
 
+  constructor(maxDepth = null) {
+    this.maxDepth = maxDepth;
+  }
+
   /**
    * Apply rules to the given item by computing a ruleset then merging it
    * with the item's current state.
@@ -22,11 +26,13 @@ export default class RulesEngine {
     this.firstItemDepthZero(item);
     this.depthMustBeSet(item);
     this.itemCannotHaveInvalidDepth(item);
+    this.itemCannotExceedDepthLimit(item);
 
     // behavioural rules define what the user is allowed to do
     this.parentsCannotDeNest(item);
     this.rootsCannotDeNest(item);
     this.nestingNeedsParent(item);
+    this.nestingCannotExceedMaxDepth(item);
     this.leavesCannotCollapse(item);
     this.needHiddenItemsToExpand(item);
     this.parentsCannotBeDeleted(item);
@@ -69,6 +75,22 @@ export default class RulesEngine {
     }
   }
 
+  /**
+   * Depth must not exceed menu's depth limit.
+   *
+   * @param {Item} item
+   */
+  itemCannotExceedDepthLimit(item) {
+    if (this.maxDepth > 0 && this.maxDepth <= item.depth) {
+      // Note: this change can cause an issue where the previous item is treated
+      // like a parent even though it no longer has children. This is because
+      // items are processed in order. This issue does not seem worth solving
+      // as it only occurs if the max depth is altered. The issue can be worked
+      // around by saving the menu.
+      item.depth = this.maxDepth - 1;
+    }
+  }
+
   /**
    * De-nesting an item would create a gap of 2 between itself and its children
    *
@@ -115,6 +137,17 @@ export default class RulesEngine {
     if (!previous || previous.depth < item.depth) this.#deny("denyNest");
   }
 
+  /**
+   * An item can't be nested (indented) if doing so would exceed the max depth.
+   *
+   * @param {Item} item
+   */
+  nestingCannotExceedMaxDepth(item) {
+    if (this.maxDepth > 0 && this.maxDepth >= item.depth + 1) {
+      this.#deny("denyNest");
+    }
+  }
+
   /**
    * An item can't be deleted if it has visible children.
    *

data/app/controllers/concerns/katalyst/navigation/has_navigation.rb

@@ -2,20 +2,87 @@
 
 module Katalyst
   module Navigation
+    # Preloads navigation menus before content is rendered.
     module HasNavigation
       extend ActiveSupport::Concern
 
+      # Override the default navigation builder for all views rendered by this
+      # controller and any of its descendants. Accepts a subclass of
+      # Katalyst::Navigation::Frontend::Builder.
+      #
+      # For example, given a form builder:
+      #
+      #   class AdminNavBuilder < Katalyst::Navigation::Frontend::Builder
+      #     def render_item(item)
+      #     end
+      #   end
+      #
+      # The controller specifies a form builder as its default:
+      #
+      #   class AdminAreaController < ApplicationController
+      #     default_navigation_builder AdminNavBuilder
+      #   end
+      #
+      # Then in the view any form using +navigation_menu_with+ will be an instance of the
+      # specified navigation builder:
+      #
+      #   <%= navigation_menu_with(menu: @menu) %>
+      module NavigationBuilder
+        extend ActiveSupport::Concern
+
+        included do
+          class_attribute :_default_navigation_builder, instance_accessor: false
+        end
+
+        class_methods do
+          # Set the navigation builder to be used as the default for all navs
+          # in the views rendered by this controller and its subclasses.
+          #
+          # @param builder {Katalyst::Navigation::Frontend::Builder}
+          def default_navigation_builder(builder)
+            self._default_navigation_builder = builder
+          end
+        end
+
+        # Default navigation builder for the controller
+        #
+        # @return {Katalyst::Navigation::Frontend::Builder}
+        def default_navigation_builder
+          self.class._default_navigation_builder
+        end
+      end
+
+      # Provide an accessor for navigation menus
       module NavigationHelper
+        # Retrieves the preloaded menu that matches the given slug.
+        #
+        # @return {Katalyst::Navigation::Menu} menu with the given slug
         def navigation_menu_for(slug)
           @navigation_menus[slug.to_s]
         end
+
+        # @see ActionView::Helpers::ControllerHelper#assign_controller
+        def assign_controller(controller)
+          super
+
+          if controller.respond_to?(:default_navigation_builder)
+            @_default_navigation_builder = controller.default_navigation_builder
+          end
+        end
       end
 
       included do
+        include NavigationBuilder
+
         helper Katalyst::Navigation::FrontendHelper
         helper NavigationHelper
 
-        before_action :set_navigation_menus
+        # @see ActionController::Rendering#render
+        def render(*args)
+          set_navigation_menus
+
+          super
+        end
       end
 
       protected

data/app/controllers/katalyst/navigation/menus_controller.rb

@@ -39,7 +39,7 @@ module Katalyst
       def update
         menu = Menu.find(params[:id])
 
-        menu.attributes = navigation_params
+        menu.attributes = menu_params
 
         unless menu.valid?
           return render :show, locals: { menu: menu }, status: :unprocessable_entity
@@ -68,14 +68,9 @@ module Katalyst
       private
 
       def menu_params
-        params.require(:menu).permit(:title, :slug)
-      end
-
-      def navigation_params
         return {} if params[:menu].blank?
 
-        params.require(:menu)
-          .permit(:title, :slug, items_attributes: %i[id index depth])
+        params.require(:menu).permit(:title, :slug, :depth, items_attributes: %i[id index depth])
       end
     end
   end

data/app/helpers/katalyst/navigation/editor/item.rb

@@ -8,7 +8,7 @@ module Katalyst
 
         def build(item, **options, &block)
           self.item = item
-          content_tag(:div, default_options(id: dom_id(item), **options)) do
+          tag.div **default_options(id: dom_id(item), **options) do
             concat(capture { yield self }) if block
             concat fields(item)
           end

data/app/helpers/katalyst/navigation/editor/list.rb

@@ -14,7 +14,7 @@ module Katalyst
         ACTIONS
 
         def build(options, &_block)
-          content_tag :ol, default_options(id: menu_form_id, **options) do
+          tag.ol **default_options(id: menu_form_id, **options) do
             yield self
           end
         end

data/app/helpers/katalyst/navigation/editor/menu.rb

@@ -29,6 +29,10 @@ module Katalyst
           add_option(options, :data, :controller, MENU_CONTROLLER)
           add_option(options, :data, :action, ACTIONS)
 
+          depth = options.delete(:depth) || menu.depth
+
+          add_option(options, :data, :"#{MENU_CONTROLLER}-max-depth-value", depth) if depth
+
           options
         end
       end

data/app/helpers/katalyst/navigation/editor/new_item.rb

@@ -10,7 +10,7 @@ module Katalyst
 
         def build(item, **options, &block)
           capture do
-            concat(content_tag(:div, **default_options(options)) do
+            concat(tag.div(**default_options(options)) do
               concat capture(&block)
               concat item_template(item)
             end)
@@ -31,7 +31,7 @@ module Katalyst
         # events when the user initiates drag so that it can be copied into the
         # editor list on drop.
         def item_template(item)
-          content_tag(:template, data: { "#{NEW_ITEM_CONTROLLER}-target" => "template" }) do
+          tag.template data: { "#{NEW_ITEM_CONTROLLER}-target" => "template" } do
             navigation_editor_items(item: item)
           end
         end

data/app/helpers/katalyst/navigation/editor/status_bar.rb

@@ -9,7 +9,7 @@ module Katalyst
         ACTIONS
 
         def build(**options)
-          content_tag(:div, default_options(**options)) do
+          tag.div **default_options(**options) do
             concat status(:published, last_update: l(menu.updated_at, format: :short))
             concat status(:draft)
             concat status(:dirty)
@@ -24,7 +24,7 @@ module Katalyst
         end
 
         def actions
-          content_tag(:menu) do
+          tag.menu do
             concat action(:discard, class: "button button--text")
             concat action(:revert, class: "button button--text") if menu.state == :draft
             concat action(:save, class: "button button--secondary")

data/app/helpers/katalyst/navigation/frontend/builder.rb

@@ -8,15 +8,15 @@ module Katalyst
 
         delegate_missing_to :@template
 
-        def initialize(template, menu: {}, list: {}, item: {})
+        def initialize(template, list: {}, item: {}, **menu_options)
           self.template     = template
-          self.menu_options = menu
+          self.menu_options = menu_options
           self.list_options = list
           self.item_options = item
         end
 
         def render(tree)
-          content_tag(:ul, menu_options) do
+          tag.ul **menu_options do
             tree.each do |item|
               concat render_item(item)
             end
@@ -26,14 +26,14 @@ module Katalyst
         def render_item(item)
           return unless item.visible?
 
-          content_tag :li, item_options do
+          tag.li **item_options do
             concat public_send("render_#{item.model_name.param_key}", item)
             concat render_list(item.children) if item.children.any?
           end
         end
 
         def render_list(items)
-          content_tag :ul, list_options do
+          tag.ul **list_options do
             items.each do |child|
               concat render_item(child)
             end

data/app/helpers/katalyst/navigation/frontend_helper.rb

@@ -5,15 +5,19 @@ module Katalyst
     module FrontendHelper
       mattr_accessor :navigation_builder
 
+      attr_internal :default_navigation_builder
+
       # Render a navigation menu. Caches based on the published version's id.
       #
       # @param(menu: Katalyst::Navigation::Menu)
       # @return Structured HTML containing top level + nested navigation links
-      def render_navigation_menu(menu, item: {}, list: {}, **options)
+      def navigation_menu_with(menu:, **options)
+        builder = navigation_builder(**options)
+        menu    = menu.is_a?(Symbol) ? navigation_menu_for(menu) : menu
+
         return unless menu&.published_version&.present?
 
         cache menu.published_version do
-          builder = default_navigation_builder_class.new(self, menu: options, item: item, list: list)
           concat builder.render(menu.published_tree)
         end
       end
@@ -22,8 +26,9 @@ module Katalyst
       #
       # @param(items: [Katalyst::Navigation::Item])
       # @return Structured HTML containing top level + nested navigation links
-      def render_navigation_items(items, list: {}, **options)
-        builder = default_navigation_builder_class.new(self, item: options, list: list)
+      def navigation_items_with(items:, **options)
+        builder = navigation_builder(**options)
+
         capture do
           items.each do |item|
             concat builder.render_item(item)
@@ -33,8 +38,13 @@ module Katalyst
 
       private
 
+      def navigation_builder(**options)
+        builder = options.delete(:builder) || default_navigation_builder_class
+        builder.new(self, **options)
+      end
+
       def default_navigation_builder_class
-        builder = controller.try(:default_navigation_builder) || Frontend::Builder
+        builder = default_navigation_builder || Frontend::Builder
         builder.respond_to?(:constantize) ? builder.constantize : builder
       end
     end

data/app/models/katalyst/navigation/menu.rb

@@ -45,6 +45,7 @@ module Katalyst
 
       validates :title, :slug, presence: true
       validates :slug, uniqueness: true
+      validates :depth, numericality: { greater_than: 0, only_integer: true, allow_nil: true }
 
       # A menu is in draft mode if it has an unpublished draft or it has no published version.
       # @return the current state of the menu, either `published` or `draft`

data/app/views/katalyst/navigation/menus/edit.html.erb

@@ -1,16 +1,21 @@
 <% content_for :title, "Edit navigation" %>
 
 <%= form_with model: menu do |form| %>
-  <div class="field">
+  <div class="field required">
     <%= form.label :title %>
     <%= form.text_field :title %>
   </div>
 
-  <div class="field">
+  <div class="field required">
     <%= form.label :slug %>
     <%= form.text_field :slug %>
   </div>
 
+  <div class="field optional">
+    <%= form.label :depth %>
+    <%= form.text_field :depth %>
+  </div>
+
   <div class="button-row">
     <%= form.submit :save %>
     <%= link_to "Delete", url_for(action: :show),

data/app/views/katalyst/navigation/menus/new.html.erb

@@ -1,15 +1,20 @@
 <% content_for :title, "New navigation" %>
 
 <%= form_with model: menu do |form| %>
-  <div class="field">
+  <div class="field required">
     <%= form.label :title %>
     <%= form.text_field :title %>
   </div>
 
-  <div class="field">
+  <div class="field required">
     <%= form.label :slug %>
     <%= form.text_field :slug %>
   </div>
 
+  <div class="field optional">
+    <%= form.label :depth %>
+    <%= form.text_field :depth %>
+  </div>
+
   <%= form.submit %>
 <% end %>

data/db/migrate/20220908044500_add_depth_limit_to_menus.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddDepthLimitToMenus < ActiveRecord::Migration[7.0]
+  def change
+    add_column :katalyst_navigation_menus, :depth, :integer
+  end
+end

data/lib/katalyst/navigation/version.rb

@@ -2,6 +2,6 @@
 
 module Katalyst
   module Navigation
-    VERSION = "1.0.3"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: katalyst-navigation
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Katalyst Interactive
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-07 00:00:00.000000000 Z
+date: 2022-09-09 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -73,6 +73,7 @@ files:
 - config/routes.rb
 - db/migrate/20220826034057_create_katalyst_navigation_menus.rb
 - db/migrate/20220826034507_create_katalyst_navigation_items.rb
+- db/migrate/20220908044500_add_depth_limit_to_menus.rb
 - lib/katalyst/navigation.rb
 - lib/katalyst/navigation/engine.rb
 - lib/katalyst/navigation/version.rb