How to upgrade Elements to use ingredients instead of essences

[tvdeyen]

Upgrade essences to ingredients

In Alchemy 7.0 Ingredients will be the only option for new elements.

Existing elements can be updated with these simple steps:

Update element definitions

In your elements.yml

• replace contents with ingredients
• replace each contents name with role
• Remove the Essence prefix from the type *) See EssenceDate note

Example

 - name: article
   taggable: true
-  contents:
-    - name: intro
-      type: EssenceText
-    - name: headline
-      type: EssenceText
+  ingredients:
+    - role: intro
+      type: Text
+    - role: headline
+      type: Text
       settings:
         linkable: true
-    - name: image
-      type: EssencePicture
+    - role: image
+      type: Picture
       settings:
         size: 450x300
         crop: true
-    - name: text
-      type: EssenceRichtext
+    - role: text
+      type: Richtext
-    - name: date
-      type: EssenceDate
+    - role: date
+      type: Datetime

Update element partial

All helpers provided by the element_view_for helper are working with essences and ingredients. Most of the time there is no change necessary.

Global helpers

If you are using global helpers and not using the el.* methods defined on the object yielded by element_view_for, you need to update them.

All global helpers using content_* in its name are deprecated and should be replaced by their ingredient_* counterpart.

Examples

• content_by_name -> ingredient_by_role
• content_by_type -> ingredient_by_type
• contents_by_type -> ingredients_by_type

Have a look into the modules defining the helpers

Old helpers

• https://github.com/AlchemyCMS/alchemy_cms/blob/64194df72823dc8ce162741d2085d54a0a1ab152/app/models/alchemy/element/element_essences.rb
• https://github.com/AlchemyCMS/alchemy_cms/blob/64194df72823dc8ce162741d2085d54a0a1ab152/app/models/alchemy/element/element_essences.rb

New helpers

• https://github.com/AlchemyCMS/alchemy_cms/blob/76a39a4b91fc8f2ae6fddf51dfe55a309b9baacf/app/models/alchemy/element/element_ingredients.rb

element.ingredient

Using element.ingredient to get the value of an ingredient is deprecated and will change in Alchemy 7.0
If you want to read the value of an elements ingredient please use element.value_for(:ingredient_role) instead.
Alchemy 7.0 will return a Alchemy::Ingredient record instead.

Run the upgrade task

We have a rake task that converts existing elements in your database.

bin/rake alchemy:upgrade:6.0:create_ingredients

This task can run multiple times. It will skip already converted elements, so you could add this to your deploy task, right were you already run rake db:migrate or rake assets:precompile.

Notes

Take a look into your Rails log. We print out a lot of deprecation notes. Please follow them. Then you should be fine.

You do not have to update all elements at once. Ingredients and essences live side by side during Alchemy v6.x. So you can take your time and deploy each element on its own.

[afdev82]

Shouldn't be the title " How to upgrade Elements to use ingredients instead of essences" instead of "How to upgrade Elements to use essences instead of ingredients"?

[tvdeyen]

Yes, absolutely. Thanks. Changed

[afdev82]

I have found that the EssenceDate is now the ingredient Datetime.
Changing only the prefix in this case it doesn't work.

[tvdeyen]

To help the upgrade we introduced a task that visualizes the current element usage of your Alchemy installation.

bin/rake alchemy:element_usage

This will list all elements with its current count and displays a note about usage of contents vs. ingredients.

Example output of a very large Alchemy installation we currently migrate.

Alchemy elements usage
----------------------

64.644 𝗑 textblock · uses ingredients ✅
36.620 𝗑 paywall_product · uses ingredients ✅
23.209 𝗑 opengraph_metatags · uses ingredients ✅
22.849 𝗑 article_settings_elements
22.839 𝗑 article_settings · uses ingredients ✅
22.834 𝗑 article_intro · uses ingredients ✅
21.389 𝗑 ihv_teaser · uses ingredients ✅
19.105 𝗑 paywall · uses ingredients ✅
17.542 𝗑 figure · uses ingredients ✅
16.041 𝗑 pictures · uses ingredients ✅
8.728 𝗑 info_box · uses ingredients ✅
4.759 𝗑 picture · uses ingredients ✅
4.624 𝗑 article_teaser · uses ingredients ✅
4.128 𝗑 separator · uses ingredients ✅
3.243 𝗑 multicolumn_wrapper · uses ingredients ✅
3.114 𝗑 table · uses ingredients ✅
2.911 𝗑 two_col_wrapper · uses ingredients ✅
2.667 𝗑 world_in_figures · uses ingredients ✅
2.512 𝗑 text · uses ingredients ✅
1.606 𝗑 quote · uses ingredients ✅
1.567 𝗑 container
1.410 𝗑 twitter_card_metatags · uses ingredients ✅
1.192 𝗑 page_intro_elements
984 𝗑 image_gallery_picture · uses ingredients ✅
927 𝗑 html_code · still uses contents ‼️
707 𝗑 table_of_content_settings_elements
705 𝗑 issue_teaser · still uses contents ‼️
704 𝗑 table_of_content_settings · still uses contents ‼️
680 𝗑 landingpage_intro · still uses contents ‼️
474 𝗑 cta · still uses contents ‼️
353 𝗑 video · still uses contents ‼️
236 𝗑 image_gallery · uses ingredients ✅
181 𝗑 page_intro · still uses contents ‼️

It is safe to run this on your production machine.

This should help to plan the migration.

[mattlaoruckus]

if anyone is interested in upgrading their elements file with the new 7.0.1 upgrade this converter does the trick for me:

https://github.com/laomatt/alchemy_yml_converter

[afdev82]

After updating Alchemy to v7.0.0 I am getting this error if I try to use my custom ingredient in a view with:

uninitialized constant Alchemy::Ingredients::CountryView

  el.render country

Should I add something more for the ingredient definition? I have found no documentation about that in the release notes of v7.
I have obviously added the class and the partial views for the ingredient, it was all working fine in the latest version of v6.1 branch (v6.1.9).
I have noticed there are other classes for the built-in ingredients

[mamhoff]

In Alchemy 7.x, ingredients are rendered using view components (https://viewcomponent.org/). Here's a real-life example from one of the apps I work on:

Custom Ingredient:

# app/models/alchemy/ingredients/location.rb

module Alchemy
  module Ingredients
    class Location < Alchemy::Ingredient
      related_object_alias :location, class_name: "Location"

      def preview_text(max_length = 30)
        location&.title.to_s[0..max_length - 1]
      end
    end
  end
end

# app/components/alchemy/ingredients/location_view.rb

# frozen_string_literal: true

module Alchemy
  module Ingredients
    class LocationView < BaseView

      erb_template <<-ERB
      <article itemscope itemtype="https://data-vocabulary.org/Organization">
        <p itemprop="name"><%= location.title %></p>
        <p itemscope itemprop="address" itemscope="https://data-vocabulary.org/Address">
          <span itemprop="street-address"><%= location.address_line_1 %></span>
          <br>
          <span itemprop="postal-code"><%= location.postal_code %></span>
          <span itemprop="locality"><%= location.city %></span>
        </p>
      </article>
      ERB

      def call
        if html_options[:one_line]
          render_one_line(location)
        elsif html_options[:title_only]
          location.title.html_safe
        else
          super
        end
      end

      def render?
        @ingredient.location.present?
      end

      private

      def render_one_line(location)
        "#{location.title}, #{location.address_line_1}, #{location.postal_code} #{location.city}".html_safe
      end
    end
  end
end

TL;DR: In Alchemy 7, the template for ingredients is now the view component class. Once you wrap your head around it, it's really quite straightforward (and much easier to test than views).

[afdev82]

Thank you for the fast reply, I was reading the code to understand how it works.
It looks not so difficult to migrate.
Maybe I will send a PR to update the documentation for v7.x (the guides).
May I include your answer as documentation? I don't know how to explain it better / differently 😅