How to register a new admin WebComponent?

[mbajur]

Hey! I'm creating a new module which is basically a masonry editor with option to reorder items via drag&drop. In order to do so, i have to probably create a new webcomponent and operate on my views with sortablejs - is there any particular place anyone could point me to in order to see how additional admin panel components can be registered and used in Alchemy? Thanks!

[tvdeyen]

Alchemy uses importmap-rails to handle JS imports.

We have two configurations that allow you to either add a single import

1. alchemy_cms/lib/alchemy.rb

   Lines 73 to 86 in e4aba31

   	# 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"
   	#
   	def admin_js_imports
   	@_admin_js_imports ||= Set.new
   	end

or add your own bundle with

2. alchemy_cms/lib/alchemy.rb

   Lines 92 to 117 in e4aba31

   	# 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>]
   	def admin_importmaps

A good example is the alchemy-solidus gem.

https://github.com/AlchemyCMS/alchemy-solidus/blob/58a279eb4815fa5e428d4d4e57794273f0319d15/lib/alchemy/solidus/engine.rb#L19-L28

It provides a lot of own web components that then can be used all over the admin. Since the browser handles initialization there is nothing else to do than registering the component and using in the DOM as with any other HTML element.

Take the <alchemy-product-select> as an example. It imports the Alchemy RemoteSelect and gets extended by it. The remote select uses the connectedCallback (called by the browser, whenever it is added to the DOM) to initialize the select2 library.

Or the <alchemy-elements-window> which initializes SortableJS in it's connectedCallback.

Lot's of ways to create composable and future proof JS in the Admin without any third party JS lib or framework. 🎉

[mbajur]

Thank you! That would totally fit in a separate article on the how-to guides :)

[tvdeyen]

Absolutely. Want to prepare a PR? https://github.com/AlchemyCMS/alchemy-guides

[mbajur]

I might try that once i have that tested and working in my app ;)

[tvdeyen]

Perfect. Thanks. Let me know if you need any more help with this.