Getting Started

Add ICMS to the Gemfile:

# At the moment the gems are hosted only on Intesys servers for internal use.
source 'http://[user]:[password]@gems.intesys.it' do
  gem 'icms'
  gem 'icms_backend'
  gem 'icms_content'
  gem 'icms_navigable'
end

# icms_content depends on a couple of gems for I18n
gem 'globalize', '~> 5.1.0'
gem 'i18n-active_record', source: 'https://rubygems.org/', require: 'i18n/active_record'

Install the gems:

bundle install

ICMS comes with a number of generators to help setup a new application quickly. Some are optional but at the very least the configuration and install generators have to be run in order to create a configuration file with the most common framework settings and to install a few required files in the application itself:

rails g icms_backend:configuration         # Generate ICMS configuration file.
rails g icms_backend:authentication:devise # Optionally setup Devise for back end authentication.
rails g icms_backend:install               # Install needed files in app.

Run the migrations (ICMS requires Postgres):

rails db:migrate

Restart the Rails server and go to /admin. ICMS Backend will respond but there is nothing to manage yet, except for the Asset Manager that lets you organize all types of files.

In order for ICMS to be useful you need to tell the framework which of your models you want to manage and what functionality you want to add to them. This can be done by calling the icms method in your model, passing a block with calls to each plugin that you want to add. This might look something like:

icms do
  assetable
  audit
  authorizable
  metadata
  multilanguage :title, :content, translation_table: true,
  fallback_for_empty_translations: true
  navigable multisite: true
  publishable
  sortable
  visibility
end

If you haven't already created your model you can use the provided generator which makes it easy to add translated fields and also adds the icms method call above:

rails g icms_content:model Post
# Choose to add "title" and "content" as translated fields
rails g icms_content:model Comment post_id:integer content:text
rails db:migrate

Now we can run the dashboard generator in order to connect the models to the administration interface. We also need to run the manifest generator which creates a file that tells ICMS Backend which dashboards to display:

rails g icms_backend:dashboard Post
rails g icms_backend:dashboard Comment
rails g icms_backend:manifest

When you restart the server and point /admin you should now be able to manage your models!

Now it's easy to add new posts but with only a title and content they are quite basic so let's add a main photo that we can use whenever we link to the post and a photo gallery that might look nice when presenting the full post:

# app/models/post.rb
icms do
  assetable
end

has_photo :cover, accepted: [:jpg], folder: 'Posts'
has_photos :gallery, folder: 'Posts'

We need to update the dashboard with these modifications and the easiest way is simply by running the generator again:

rails g icms_backend:dashboard Post

Now, when we create or edit a post, we can choose photos from the Asset Manager.

Notes / Common Problems

If you decided to add translated fields to your model you will see every available locale in the locale switcher of the resource. In a default Rails installation this can be a long list and you may want to create an initializer with something along these lines:

# config/initializers/locale.rb
I18n.available_locales = [:en, :it]
I18n.default_locale = :en

The dashboard generator creates a dashboard that reflects the current state of the model. In the example above we have a Comment model that belongs to a Post model but until we add the belongs\_to :post declaration in Comment the generated dashboard doesn't know that you want a relation and simply displays a text box. You can run the generator again and overwrite the old file when you make modifications like this.