Creating own Ingredients
Alchemys powerful content storage technology is build around ingredients. They are ActiveRecord models that have an editor and a presentation view partial.
Alchemy has lots of build in ingredients. But you can create your own ingredient and even associate them with your existing models. This guide shows how.
- Use the generator to create a new ingredient
- Associate an ingredient to your model
Using The Ingredient Generator
The ingredient generator is a wrapper around the Rails model generator. It generates the ingredient model for you.
bin/rails g alchemy:ingredient MyIngredient
Ingredients are created under the
This is what the generated model looks like:
# app/models/alchemy/ingredients/my_ingredient.rb module Alchemy module Ingredients class MyIngredient < Alchemy::Ingredient # Set additional attributes that get stored in the `data` JSON column # store_accessor :data, :some, :attribute # Set a related_object alias for convenience # related_object_alias :some_association_name, class_name: "Some::Klass" end end end
Alchemy stores the main value in the
If you want to store additional values in another column, please add it as attribute to the
store_accessor. Rails will create accessor methods for you.
The ingredient views
Every ingredient has to have two views:
- One for presenting
- One for editing
The view partial
The view partial is used by the
render_elements helper to present the ingredient to the user.
It is yours. Adjust it to your needs. You can access the value with the
ingredient method of the
content object instance.
<!-- app/views/alchemy/ingredients/_my_ingredient_view.html.erb --> <h1><%= my_ingredient_view.ingredient %></h1>
The editor partial
The editor partial is basically a set of form fields holding values of your ingredient. It is rendered inside the element editor view form object.
This is just what the generator creates for you:
<!-- app/views/alchemy/ingredients/_my_ingredient_editor.html.erb --> <%= content_tag :div, class: my_ingredient_editor.css_classes, data: my_ingredient_editor.data_attributes do %> <%= element_form.fields_for(:ingredients, my_ingredient_editor.ingredient) do |f| %> <%= ingredient_label(my_ingredient_editor) %> <%= f.text_field :value %> <% end %> <% end %>
But this is yours. Feel free to adjust it to your needs. Just make shure that you provide form fields that Alchemy can use to update your object in the database.
You can associate every ActiveRecord based model with an ingredient. In this example we want to connect an existing
Person model to an element, so we can associate it with an Alchemy page.
Just use the
related_object_alias method to tell Alchemy the foreign key to use for the association.
Set the foreign key
# app/models/alchemy/ingredients/person.rb module Alchemy module Ingredients class Person < Alchemy::Ingredient related_object_alias :person, class_name: "My::Person" end end end
Accessing your model instance
That's it. Everything else is handled by Alchemy. You can now access the associated
My::Person model with the
<!-- app/views/alchemy/ingredients/_person_view.html.erb --> <%= person_view.person.firstname %>
Now you can use your new ingredient in any element you want as shown in the Elements guide.