Essences store the actual content of your site. They are stored as instances of Alchemy::Content on each Alchemy::Element instance.

Alchemy comes with a lot of predefined essences for the regular needs of a website project. Combine them like a chemestry kit into elements.

Essences are Rails models. It is pretty easy to add your own essence class as well.


Essences are defined as contents on an element definition.

Global content settings

When defining contents, you need to provide a name and essence type. You can set hints and default values as well.

# config/alchemy/elements.yml
- name: article
    - name: headline
      type: EssenceText
      hint: This is the headline
    - name: copy
      type: EssenceRichtext
      default: Lorem ipsum dolor
      as_element_title: true
  • name String required

    A lowercased unique (per element) name of the content. Separated words needs to be underscored.

  • type String required

    An essence type this content is from. Alchemy has lots of built in essences for simple text, rich text, images, booleans and more.

  • hint String|Symbol|Boolean

    A hint for the user in the admin frontend that describes what the essence is used for. The hint is translatable if you provide an I18n translation Symbol instead of a String. You may also set it to true to default to the I18n key alchemy.content_hints.your-content-name.

  • default String

    The default text to prefill newly created elements. You may also use a symbol to set it to the I18n key alchemy.default_content_texts.your-symbol-name

  • as_element_title Boolean

    For the displayed element title, the first content essence is used. Use this setting to override this behaviour and show other content as element title.

Individual essence settings

Each essence type can have its own type of settings.

To configure these settings you have to pass them into its settings key in the elements.yml.


- name: my_element
    - name: headline
      type: EssenceText
        linkable: true


Stores plain text of 255 chars max.

Use this for a headline, or a product name. The editor is renderd as a single lined input field. The view output will be sanitized and HTML escaped.


  • linkable Boolean

    If set to true, the user can add a link to the text.


- name: button
  type: EssenceText
    linkable: true


Used to store paragraphs of formatted text.

The editor is rendered as a textarea with embedded Tinymce Editor.


You can customize the Tinymce editor of a single element instance.

  • tinymce Hash


- name: text
  type: EssenceRichtext
        - title: 'Subheadline'
          block: 'h3'


See the Tinymce customization guide for all available options


Store references to pictures the editor assigns from the library.

The editor partial is rendered as a picture editor with a lot of options (i.e. image cropper).

The view partial renders the assigned picture, resizes it and crops it if needed.


See the rendering images guide for further information on the powerful image rendering engine of Alchemy.


Use this to store a DateTime value. Renders a datepicker in the editor partial.

The view output is passed through Rails' I18n Library, so it is fully localizable.


Useful to store HTML code (i.e. a embed, or tracking code).


The view renders the raw, not sanitized or escaped output. So be careful!


Stores a Boolean value in the database. Renders a checkbox in the editor partial.


Renders a select box in the editor partial and stores the value as String.

Useful for letting your user select from a limited set of choices.

  • select_values Array


- name: width
  type: EssenceSelect
    select_values: ['200', '300', '400']

Stores a url in the database. Useful for linking things, where the editor should not set the linked text itself.


If you want that the linked text is editable by the editor use the EssenceText with linkable: true option instead.

Last Updated: 10/27/2018, 10:25:19 PM