module Alchemy

Additional importmaps to be included in the Alchemy admin UI

Be sure to also pin modules with Alchemy.importmap.

Example¶ ↑

# config/alchemy/importmap.rb
Alchemy.importmap.pin "alchemy_solidus", to: "alchemy_solidus.js", preload: true
Alchemy.importmap.pin_all_from Alchemy::Solidus::Engine.root.join("app/javascript/alchemy_solidus"),
  under: "alchemy_solidus",
  preload: true

# lib/alchemy/solidus/engine.rb
initializer "alchemy_solidus.assets", before: "alchemy.importmap" do |app|
  Alchemy.admin_importmaps.add({
    importmap_path: root.join("config/importmap.rb"),
    source_paths: [
      root.join("app/javascript")
    ],
    name: "alchemy_solidus"
  })
  app.config.assets.precompile << "alchemy_solidus/manifest.js"
end

@return [Set<Hash>]

# File lib/alchemy.rb, line 90
def self.admin_importmaps
  @_admin_importmaps ||= Set.new([{
    importmap_path: Engine.root.join("config/importmap.rb"),
    source_paths: [
      Engine.root.join("app/javascript"),
      Engine.root.join("vendor/javascript")
    ],
    name: "alchemy_admin"
  }])
end

Additional JS modules to be imported in the Alchemy admin UI

Be sure to also pin the modules with Alchemy.importmap.

Example¶ ↑

Alchemy.importmap.pin "flatpickr/de",
  to: "https://ga.jspm.io/npm:flatpickr@4.6.13/dist/l10n/de.js"

Alchemy.admin_js_imports << "flatpickr/de"

# File lib/alchemy.rb, line 57
def self.admin_js_imports
  @_admin_js_imports ||= Set.new
end

Configure tabs in the link dialog

With this configuration that tabs in the link dialog can be extended without overwriting or defacing the Admin Interface.

Example¶ ↑

# components/acme/link_tab.rb
module Acme
  class LinkTab < ::Alchemy::Admin::LinkDialog::BaseTab
    def title
      "Awesome Tab Title"
    end

    def name
      :unique_name
    end

    def fields
       [ title_input, target_select ]
    end
  end
end

# config/initializers/alchemy.rb
Alchemy.link_dialog_tabs << Acme::LinkTab

# File lib/alchemy.rb, line 169
def self.link_dialog_tabs
  @_link_dialog_tabs ||= Set.new([
    Alchemy::Admin::LinkDialog::InternalTab,
    Alchemy::Admin::LinkDialog::AnchorTab,
    Alchemy::Admin::LinkDialog::ExternalTab,
    Alchemy::Admin::LinkDialog::FileTab
  ])
end

Define page preview sources

A preview source is a Ruby class returning an URL that is used as source for the preview frame in the admin UI.

Example¶ ↑

# lib/acme/preview_source.rb
class Acme::PreviewSource < Alchemy::Admin::PreviewUrl
  def url_for(page)
    if page.site.name == "Next"
      "https://user:#{ENV['PREVIEW_HTTP_PASS']}@next.acme.com"
    else
      "https://www.acme.com"
    end
  end
end

# config/initializers/alchemy.rb
require "acme/preview_source"
Alchemy.preview_sources << Acme::PreviewSource

# config/locales/de.yml
de:
  activemodel:
    models:
      acme/preview_source: Acme Vorschau

# File lib/alchemy.rb, line 38
def self.preview_sources
  @_preview_sources ||= Set.new << Alchemy::Admin::PreviewUrl
end

Define page publish targets

A publish target is a ActiveJob that gets performed whenever a user clicks the publish page button.

Use this to trigger deployment hooks of external services in an asychronous way.

Example¶ ↑

# app/jobs/publish_job.rb
class PublishJob < ApplicationJob
  def perform(page)
    RestClient.post(ENV['BUILD_HOOK_URL'])
  end
end

# config/initializers/alchemy.rb
Alchemy.publish_targets << PublishJob

# File lib/alchemy.rb, line 121
def self.publish_targets
  @_publish_targets ||= Set.new
end

Register a CanCan Ability class

# File lib/alchemy/auth_accessors.rb, line 124
def self.register_ability(klass)
  @abilities ||= []
  @abilities << klass
end

All CanCan Ability classes registered to Alchemy

# File lib/alchemy/auth_accessors.rb, line 131
def self.registered_abilities
  @abilities ||= []
end

Alchemy shortcut translation method

Instead of having to call:

Alchemy::I18n.translate(:hello)

You can use this shortcut method:

Alchemy.t(:hello)

# File lib/alchemy/i18n.rb, line 15
def t(msg, **kwargs)
  Alchemy::I18n.translate(msg, **kwargs)
end

Prefix with

when getting to avoid constant name conflicts

# File lib/alchemy/auth_accessors.rb, line 82
def self.user_class_name
  if !@@user_class_name.is_a?(String)
    raise TypeError, "Alchemy.user_class_name must be a String, not a Class."
  end

  "::#{@@user_class_name}"
end