Class: Inkpen::Extensions::Mention

Inherits:
Base
  • Object
show all
Defined in:
lib/inkpen/extensions/mention.rb

Overview

Mention extension for @mentions functionality.

Enables users to mention other users or entities using the @ symbol. When triggered, a popup appears with suggestions that can be filtered by typing.

The suggestion data is fetched from a configurable endpoint.

Examples:

Basic usage

extension = Inkpen::Extensions::Mention.new(
  search_url: "/api/users/search"
)

With custom trigger and styling

extension = Inkpen::Extensions::Mention.new(
  search_url: "/api/users/search",
  trigger: "@",
  suggestion_class: "mention-suggestion",
  item_class: "mention-item"
)

See Also:

Author:

  • Inkpen Team

Since:

  • 0.2.0

Constant Summary collapse

DEFAULT_TRIGGER =

Default trigger character for mentions.

Since:

  • 0.2.0

"@"
DEFAULT_MIN_CHARS =

Default minimum characters to start searching.

Since:

  • 0.2.0

1

Instance Attribute Summary

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods inherited from Base

#enabled?, #initialize, #to_h, #to_json

Constructor Details

This class inherits a constructor from Inkpen::Extensions::Base

Instance Method Details

#allow_custom? ⇒ Boolean

Whether to allow creating new mentions not in the suggestion list.

Returns:

  • (Boolean) —

    true to allow custom mentions

Since:

  • 0.2.0



113
114
115
 
# File 'lib/inkpen/extensions/mention.rb', line 113

def allow_custom?
  options.fetch(:allow_custom, false)
end

#html_attributes ⇒ Hash

HTML attributes rendered on the mention node.

Returns:

  • (Hash) —

    HTML attributes

Since:

  • 0.2.0



122
123
124
 
# File 'lib/inkpen/extensions/mention.rb', line 122

def html_attributes
  options.fetch(:html_attributes, { class: "inkpen-mention" })
end

#item_class ⇒ String

CSS class for individual suggestion items.

Returns:

  • (String) —

    CSS class name

Since:

  • 0.2.0



104
105
106
 
# File 'lib/inkpen/extensions/mention.rb', line 104

def item_class
  options.fetch(:item_class, "inkpen-mention-item")
end

#items ⇒ Array<Hash>?

Static items to show in the suggestion popup.

Use this instead of search_url for fixed suggestion lists.

Returns:

  • (Array<Hash>, nil) —

    array of suggestion items

Since:

  • 0.2.0



77
78
79
 
# File 'lib/inkpen/extensions/mention.rb', line 77

def items
  options[:items]
end

#min_chars ⇒ Integer

Minimum characters before triggering search.

Returns:

  • (Integer) —

    minimum character count

Since:

  • 0.2.0



86
87
88
 
# File 'lib/inkpen/extensions/mention.rb', line 86

def min_chars
  options.fetch(:min_chars, DEFAULT_MIN_CHARS)
end

#name ⇒ Symbol

The unique name of this extension.

Returns:

  • (Symbol) —

    :mention

Since:

  • 0.2.0



45
46
47
 
# File 'lib/inkpen/extensions/mention.rb', line 45

def name
  :mention
end

#search_url ⇒ String?

URL endpoint for fetching mention suggestions.

The endpoint receives a ‘query` parameter with the search text. Expected response format: [{ id: 1, label: “Username”, … }]

Returns:

  • (String, nil) —

    search URL or nil if using static items

Since:

  • 0.2.0



66
67
68
 
# File 'lib/inkpen/extensions/mention.rb', line 66

def search_url
  options[:search_url]
end

#suggestion_class ⇒ String

CSS class for the suggestion popup container.

Returns:

  • (String) —

    CSS class name

Since:

  • 0.2.0



95
96
97
 
# File 'lib/inkpen/extensions/mention.rb', line 95

def suggestion_class
  options.fetch(:suggestion_class, "inkpen-mention-suggestions")
end

#to_config ⇒ Hash

Convert to configuration hash for JavaScript.

Returns:

  • (Hash) —

    configuration for the TipTap extension

Since:

  • 0.2.0



131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/inkpen/extensions/mention.rb', line 131

def to_config
  {
    trigger: trigger,
    searchUrl: search_url,
    items: items,
    minChars: min_chars,
    suggestionClass: suggestion_class,
    itemClass: item_class,
    allowCustom: allow_custom?,
    HTMLAttributes: html_attributes
  }.compact
end

#trigger ⇒ String

The character that triggers the mention popup.

Returns:

  • (String) —

    trigger character (default: “@”)

Since:

  • 0.2.0



54
55
56
 
# File 'lib/inkpen/extensions/mention.rb', line 54

def trigger
  options.fetch(:trigger, DEFAULT_TRIGGER)
end