# Essences

# Overview

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.

# Definition

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
  contents:
    - 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
  contents:
    - name: headline
      type: EssenceText
      settings:
        linkable: true

# EssenceText

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.

# Settings

• linkable Boolean

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

# Example

- name: button
  type: EssenceText
  settings:
    linkable: true

# EssenceRichtext

Used to store paragraphs of formatted text.

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

# Settings

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

• tinymce Hash

# Example

- name: text
  type: EssenceRichtext
  settings:
    tinymce:
      style_formats:
        - title: 'Subheadline'
          block: 'h3'

# EssencePicture

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.

# EssenceDate

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.

# EssenceHtml

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

# EssenceBoolean

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

# EssenceSelect

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

# Example

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

# EssenceLink

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