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