Class: Phlexi::Menu::Item

Inherits:
Object
  • Object
show all
Defined in:
lib/phlexi/menu/item.rb

Overview

Represents a single menu item in the navigation hierarchy. Each item can have a label, URL, icon, badges, and nested child items.

Examples:

Basic menu item

item = Item.new("Home", url: "/")

Menu item with badges and icon

item = Item.new("Products",
  url: "/products",
  icon: ProductIcon,
  leading_badge: "New",
  trailing_badge: "5")

Nested menu items

item = Item.new("Admin") do |admin|
  admin.item "Users", url: "/admin/users"
  admin.item "Settings", url: "/admin/settings"
end

Custom active state logic

Item.new("Dashboard", url: "/dashboard", active: -> (context) {
  context.controller.controller_name == "dashboards"
})

Direct Known Subclasses

Builder::Item

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(label, url: nil, icon: nil, leading_badge: nil, trailing_badge: nil, **options) {|item| ... } ⇒ Item

Initializes a new menu item.

Parameters:

  • label (String) —

    The display text for the menu item

  • url (String, nil) (defaults to: nil) —

    The URL the menu item links to

  • icon (Class, nil) (defaults to: nil) —

    The icon component class

  • leading_badge (String, Component, nil) (defaults to: nil) —

    Badge displayed before the label

  • trailing_badge (String, Component, nil) (defaults to: nil) —

    Badge displayed after the label

  • options (Hash) —

    Additional options (e.g., :active for custom active state logic)

Yields:

  • (item) —

    Optional block for adding nested items

Yield Parameters:

  • item (Item) —

    The newly created menu item

Raises:

  • (ArgumentError) —

    If the label is nil or empty



67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/phlexi/menu/item.rb', line 67

def initialize(label, url: nil, icon: nil, leading_badge: nil, trailing_badge: nil, **options, &)
  raise ArgumentError, "Label cannot be nil" unless label
  @label = label
  @url = url
  @icon = icon
  @items = []
  @options = options
  setup_badges(leading_badge, trailing_badge, options)

  yield self if block_given?
end

Instance Attribute Details

#icon ⇒ Class? (readonly)

Returns The icon component class to be rendered.

Returns:

  • (Class, nil) —

    The icon component class to be rendered



36
37
38
 
# File 'lib/phlexi/menu/item.rb', line 36

def icon
  @icon
end

#items ⇒ Array<Item> (readonly)

Returns Collection of nested menu items.

Returns:

  • (Array<Item>) —

    Collection of nested menu items



51
52
53
 
# File 'lib/phlexi/menu/item.rb', line 51

def items
  @items
end

#label ⇒ String (readonly)

Returns The display text for the menu item.

Returns:

  • (String) —

    The display text for the menu item



30
31
32
 
# File 'lib/phlexi/menu/item.rb', line 30

def label
  @label
end

#leading_badge ⇒ String, ... (readonly)

Returns The badge displayed before the label.

Returns:

  • (String, Component, nil) —

    The badge displayed before the label



39
40
41
 
# File 'lib/phlexi/menu/item.rb', line 39

def leading_badge
  @leading_badge
end

#leading_badge_options ⇒ Hash (readonly)

Returns Options for the leading badge.

Returns:

  • (Hash) —

    Options for the leading badge



42
43
44
 
# File 'lib/phlexi/menu/item.rb', line 42

def leading_badge_options
  @leading_badge_options
end

#options ⇒ Hash (readonly)

Returns Additional options for customizing the menu item.

Returns:

  • (Hash) —

    Additional options for customizing the menu item



54
55
56
 
# File 'lib/phlexi/menu/item.rb', line 54

def options
  @options
end

#trailing_badge ⇒ String, ... (readonly)

Returns The badge displayed after the label.

Returns:

  • (String, Component, nil) —

    The badge displayed after the label



45
46
47
 
# File 'lib/phlexi/menu/item.rb', line 45

def trailing_badge
  @trailing_badge
end

#trailing_badge_options ⇒ Hash (readonly)

Returns Options for the trailing badge.

Returns:

  • (Hash) —

    Options for the trailing badge



48
49
50
 
# File 'lib/phlexi/menu/item.rb', line 48

def trailing_badge_options
  @trailing_badge_options
end

#url ⇒ String? (readonly)

Returns The URL the menu item links to.

Returns:

  • (String, nil) —

    The URL the menu item links to



33
34
35
 
# File 'lib/phlexi/menu/item.rb', line 33

def url
  @url
end

Instance Method Details

#active?(context) ⇒ Boolean

Determines if this menu item should be shown as active. Checks in the following order:

  1. Custom active logic if provided in options

  2. URL match with current page

  3. Active state of any child items

Parameters:

  • context (Object) —

    The context object (typically a controller) for active state checking

Returns:

  • (Boolean) —

    true if the item should be shown as active, false otherwise



128
129
130
131
132
 
# File 'lib/phlexi/menu/item.rb', line 128

def active?(context)
  check_custom_active_state(context) ||
    check_current_page_match(context) ||
    check_nested_items_active(context)
end

#inspect ⇒ String

Returns a string representation of the menu item.

Returns:

  • (String) —

    A human-readable representation of the menu item



137
138
139
 
# File 'lib/phlexi/menu/item.rb', line 137

def inspect
  "#<#{self.class} label=#{@label.inspect} url=#{@url.inspect} items=#{@items.inspect}>"
end

#item(label, **args) {|item| ... } ⇒ Item

Creates and adds a nested menu item.

Parameters:

  • label (String) —

    The display text for the nested item

  • args (Hash) —

    Additional options passed to the Item constructor

Yields:

  • (item) —

    Optional block for adding further nested items

Yield Parameters:

  • item (Item) —

    The newly created nested item

Returns:

  • (Item) —

    The created nested item



86
87
88
89
90
 
# File 'lib/phlexi/menu/item.rb', line 86

def item(label, **args, &)
  new_item = self.class.new(label, **args, &)
  @items << new_item
  new_item
end

#with_leading_badge(badge, **opts) ⇒ self

Add a leading badge to the menu item

Parameters:

  • badge (String, Component) —

    The badge content

  • opts (Hash) —

    Additional options for the badge

Returns:

  • (self) —

    Returns self for method chaining

Raises:

  • (ArgumentError) —

    If badge is nil



98
99
100
101
102
103
104
 
# File 'lib/phlexi/menu/item.rb', line 98

def with_leading_badge(badge, **opts)
  raise ArgumentError, "Badge cannot be nil" if badge.nil?

  @leading_badge = badge
  @leading_badge_options = opts.freeze
  self
end

#with_trailing_badge(badge, **opts) ⇒ self

Add a trailing badge to the menu item

Parameters:

  • badge (String, Component) —

    The badge content

  • opts (Hash) —

    Additional options for the badge

Returns:

  • (self) —

    Returns self for method chaining

Raises:

  • (ArgumentError) —

    If badge is nil



112
113
114
115
116
117
118
 
# File 'lib/phlexi/menu/item.rb', line 112

def with_trailing_badge(badge, **opts)
  raise ArgumentError, "Badge cannot be nil" if badge.nil?

  @trailing_badge = badge
  @trailing_badge_options = opts.freeze
  self
end