Module: SuperSettings::Helper

Included in:: Application

Defined in:: lib/super_settings/application/helper.rb

Overview

Helper functions used for rendering the Super Settings HTML application. These methods are mixed in to the Application class so they are accessible from the ERB templates.

Constant Summary collapse

ICON_SVG =

Dir.glob(File.join(__dir__, "images", "*.svg")).each_with_object({}) do |file, cache|
  svg = File.read(file).chomp
  cache[File.basename(file, ".svg")] = svg
end.freeze

GEAR_SVG =

'<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z"/><circle cx="12" cy="12" r="3"/></svg>'

ICON_BUTTON_STYLE =

{
  cursor: "pointer",
  width: "1.35rem",
  height: "1.35rem",
  "min-width": "20px",
  "min-height": "20px",
  "margin-top": "0.25rem",
  "margin-right": "0.5rem"
}.freeze

DEFAULT_ICON_STYLE =

{
  width: "1rem",
  height: "1rem",
  display: "inline-block"
}.freeze

Class Method Summary collapse

.application_header(locale: nil) ⇒ String
Render the header HTML for the web pages using values set in the configuration.

Instance Method Summary collapse

#add_to_head ⇒ String
Additional HTML code that should go into the element on the page.
#api_base_url ⇒ String
The base URL for the REST API.
#application_header ⇒ String
Render the header for the web pages using values set in the configuration.
#application_name ⇒ Object
Return the application name set by the configuration or a default value.
#color_scheme ⇒ Boolean^?
Whether to use dark mode for the application UI.
#content_tag(tag, body, options) ⇒ Object
Render an HTML tag with body content.
#dark_mode_selector ⇒ String^?
A CSS selector that sets dark mode when it matches an element in the page.
#html_attributes(options) ⇒ Object
Format a hash into HTML attributes.
#html_escape(text) ⇒ String
Escape text for use in HTML.
#icon_button(icon, title:, color:, js_class:, url: nil, disabled: false, style: {}, link_style: nil) ⇒ String
Render an icon image as a link tag.
#icon_image(name, options = {}) ⇒ String
Render an image tag for one of the SVG images in the images directory.

#javascript_tag ⇒ Object

Render the scripts.js file as an inline

Render the header HTML for the web pages using values set in the configuration. Uses the custom application name as the title if set, otherwise falls back to the localized brand title. Uses the gear icon if no application logo is configured.

Parameters:

locale (String) (defaults to: nil) —
the locale code for translations.

Returns:

(String) —
raw HTML string.

# File 'lib/super_settings/application/helper.rb', line 146

def application_header(locale: nil)
  config = SuperSettings.configuration.controller
  locale ||= SuperSettings::MiniI18n::DEFAULT_LOCALE
  escape = ->(text) { ERB::Util.html_escape(text) }

  mark_content = if Coerce.present?(config.application_logo)
    "<img src=\"#{escape.call(config.application_logo)}\" alt=\"\">"
  else
    GEAR_SVG
  end
  mark = "<div class=\"super-settings-page-header-mark\" aria-hidden=\"true\">" \
    "#{mark_content}</div>"

  title_text = escape.call(config.application_name || SuperSettings::MiniI18n.t("page.brand_title", locale: locale))
  title = "<h1 class=\"super-settings-page-header-title\">#{title_text}</h1>"

  brand_content = mark + title
  if config.application_link
    href = escape.call(config.application_link)
    "<a href=\"#{href}\" class=\"super-settings-page-header-brand\">" \
      "#{brand_content}</a>"
  else
    "<div class=\"super-settings-page-header-brand\">#{brand_content}</div>"
  end
end

Instance Method Details

#add_to_head ⇒ `String`

Additional HTML code that should go into the element on the page.

Returns:

(String)



207
208
209

# File 'lib/super_settings/application/helper.rb', line 207

def add_to_head
  @add_to_head if defined?(@add_to_head)
end

#api_base_url ⇒ `String`

The base URL for the REST API.

Returns:

(String)



214
215
216

# File 'lib/super_settings/application/helper.rb', line 214

def api_base_url
  @api_base_url if defined?(@api_base_url)
end

#application_header ⇒ `String`

Render the header for the web pages using values set in the configuration.

Returns:

(String) —
raw HTML string.



181
182
183

# File 'lib/super_settings/application/helper.rb', line 181

def application_header
  Helper.application_header(locale: @locale)
end

#application_name ⇒ `Object`

Return the application name set by the configuration or a default value.



174
175
176

# File 'lib/super_settings/application/helper.rb', line 174

def application_name
  html_escape(SuperSettings.configuration.controller.application_name || "Application")
end

#color_scheme ⇒ `Boolean`^?

Whether to use dark mode for the application UI.

Returns:

(Boolean, nil)



221
222
223

# File 'lib/super_settings/application/helper.rb', line 221

def color_scheme
  @color_scheme if defined?(@color_scheme)
end

#content_tag(tag, body, options) ⇒ `Object`

Render an HTML tag with body content.



191
192
193

# File 'lib/super_settings/application/helper.rb', line 191

def content_tag(tag, body, options)
  "<#{tag} #{html_attributes(options)}>#{body}</#{tag}>"
end

#dark_mode_selector ⇒ `String`^?

A CSS selector that sets dark mode when it matches an element in the page. This is an alternative to using the color_scheme option.

Returns:

(String, nil)



229
230
231

# File 'lib/super_settings/application/helper.rb', line 229

def dark_mode_selector
  @dark_mode_selector if defined?(@dark_mode_selector)
end

#html_attributes(options) ⇒ `Object`

Format a hash into HTML attributes.

# File 'lib/super_settings/application/helper.rb', line 196

def html_attributes(options)
  html_options = []
  options.each do |name, value|
    html_options << "#{name}=\"#{html_escape(value.to_s)}\""
  end
  html_options.join(" ")
end

#html_escape(text) ⇒ `String`

Escape text for use in HTML.

Parameters:

text (String) —
the text to escape

Returns:

(String) —
the escaped text



98
99
100

# File 'lib/super_settings/application/helper.rb', line 98

def html_escape(text)
  ERB::Util.html_escape(text)
end

#icon_button(icon, title:, color:, js_class:, url: nil, disabled: false, style: {}, link_style: nil) ⇒ `String`

Render an icon image as a link tag.

Parameters:

icon (String) —
the name of the icon to render
title (String) —
the title/tooltip for the button
color (String) —
the color for the icon
js_class (String) —
CSS class for JavaScript behavior
url (String) (defaults to: nil) —
the URL for the link (optional)
disabled (Boolean) (defaults to: false) —
whether the button is disabled
style (Hash) (defaults to: {}) —
CSS styles for the icon
link_style (String) (defaults to: nil) —
CSS styles for the link

Returns:

(String) —
the HTML for the icon button

# File 'lib/super_settings/application/helper.rb', line 133

def icon_button(icon, title:, color:, js_class:, url: nil, disabled: false, style: {}, link_style: nil)
  url = "#" if Coerce.blank?(url)
  image = icon_image(icon, alt: title, style: ICON_BUTTON_STYLE.merge(style).merge(color: color))
  content_tag(:a, image, href: url, class: js_class, disabled: disabled, style: link_style, title: title)
end

#icon_image(name, options = {}) ⇒ `String`

Render an image tag for one of the SVG images in the images directory. If the :color option is specified, it will be applied to the SVG image.

Parameters:

name (String) —
the name of the icon to render
options (Hash) (defaults to: {}) —
options for the icon (style, color, etc.)

Returns:

(String) —
the HTML for the icon

# File 'lib/super_settings/application/helper.rb', line 108

def icon_image(name, options = {})
  svg = ICON_SVG[name.to_s]
  style = options[:style] || {}
  css = DEFAULT_ICON_STYLE.merge(style).map { |name, value| "#{name}: #{value}" }.join("; ")
  options = options.merge(style: css, class: "super-settings-icon")
  if options[:data].is_a?(Hash)
    options[:data].each do |key, value|
      options["data-#{key}"] = value
    end
    options.delete(:data)
  end
  content_tag(:span, svg, options)
end

#javascript_tag ⇒ `Object`

Render the scripts.js file as an inline

Render the styles.css as an inline

Module: SuperSettings::Helper

Overview

Constant Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Method Details

#add_to_head ⇒ String

#api_base_url ⇒ String

#application_header ⇒ String

#application_name ⇒ Object

#color_scheme ⇒ Boolean?

#content_tag(tag, body, options) ⇒ Object

#dark_mode_selector ⇒ String?

#html_attributes(options) ⇒ Object

#html_escape(text) ⇒ String

#icon_button(icon, title:, color:, js_class:, url: nil, disabled: false, style: {}, link_style: nil) ⇒ String

#icon_image(name, options = {}) ⇒ String

#javascript_tag ⇒ Object

#add_to_head ⇒ `String`

#api_base_url ⇒ `String`

#application_header ⇒ `String`

#application_name ⇒ `Object`

#color_scheme ⇒ `Boolean`^?

#content_tag(tag, body, options) ⇒ `Object`

#dark_mode_selector ⇒ `String`^?

#html_attributes(options) ⇒ `Object`

#html_escape(text) ⇒ `String`

#icon_button(icon, title:, color:, js_class:, url: nil, disabled: false, style: {}, link_style: nil) ⇒ `String`

#icon_image(name, options = {}) ⇒ `String`

#javascript_tag ⇒ `Object`