Essences

Essences store the actual content of your site.

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 normal Rails models, so it is pretty easy to add your own.

1 Hints, Default Values and Element Titles

When defining elements, you can assign hints and default values to every essence like this:


# config/alchemy/elements.yml
- name: article
    contents:
    - name: headline
      type: EssenceText
      hint: "This is the headline."
    - name: copy
      type: EssenceRichtext
      default: "Lorem ipsum"
      as_element_title: true
  • hint String
    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 key instead of a complete sentence. 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.

2 EssenceText

Stores a String (max. 255 Chars.).

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. So it’s XSS save.

2.1 Settings

  • linkable Boolean
    If set to true, the user can link that essence.

2.2 Example


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

3 EssenceRichtext

Used to store long text.

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

3.1 Settings

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

  • tinymce

3.2 Example


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

See the TinyMCE customization guide for all available options

4 EssencePicture

Used to store references to pictures the user assigned through the library.

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

The view renders the assigned picture, resizes it, crops it and caches the result.

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

5 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.

6 EssenceHtml

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!

7 EssenceBoolean

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

8 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.

Pretty handy together with the page_selector helper.

8.1 Example


# app/views/alchemy/elements/_my_element_editor.html.erb
...
  el.render :width, :select_values => ["200", "300", "400"]
...

Stores a url in the database. Useful for linking things, where the user should not set the linked value itself. (Like in the EssenceText with linkable: true option)

It is easy to add your own essence types to Alchemy. Read more about it in this guide

10 Configure essences

To configure the settings of an essence you have to pass it into its settings in the elements.yml

10.1 Example


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