How to use Lato CMS

lato_cms adds content management to a Lato admin panel. Use it when admins need to create pages and edit structured content without changing application code. Lato CMS works with Lato Spaces, so pages can be scoped to the selected group.

Installation

Add Lato CMS to the application Gemfile:

gem "lato"
gem "lato_spaces"
gem "lato_cms"

Install the engine and run migrations:

bundle
rails lato_cms:install:application
rails lato_cms:install:migrations
rails db:migrate

Mount the engine in config/routes.rb:

Rails.application.routes.draw do
  mount LatoCms::Engine => "/lato-cms"

  # ...
end

Import styles in app/assets/stylesheets/application.scss:

@import "lato_cms/application";

Import JavaScript in app/javascript/application.js:

import "lato_cms/application"

Permissions

Users must be logged into Lato, must have a selected Lato Spaces group, and must have Lato CMS admin permission enabled.

user = Lato::User.find_by(email: "admin@example.com")
user.update!(lato_cms_admin: true)

Configuration

Configure available locales and template directory:

LatoCms.configure do |config|
  config.locales = [:en, :it]
  config.templates_path = "config/lato_cms"
end

Templates and components

Templates define which content blocks are available on a page. Components define the fields inside those blocks. Both are YAML files stored in the application. Template components are enabled by default, and each page can turn optional components on or off from the admin panel.

config/lato_cms/
  templates/
    homepage.yml
    blog_post.yml
  components/
    hero.yml
    content.yml

Generate new files with Rails tasks:

rails "lato_cms:generate:template[blog_post]"
rails "lato_cms:generate:component[hero,title:string,subtitle:textarea,image:file]"

Template example

# config/lato_cms/templates/homepage.yml
id: homepage
name: Homepage
components:
  hero_section:
    component_id: hero
    name: Hero Section
    required: true
  content_section:
    component_id: content

Optional and required components

Components listed in a template are optional unless required: true is set. Optional components show an enabled switch in the page editor. Admins can disable them for a specific page without removing the component from the template.

# config/lato_cms/templates/homepage.yml
id: homepage
name: Homepage
components:
  hero_section:
    component_id: hero
    name: Hero Section
    required: true
  banner_section:
    component_id: banner
    name: Promotional Banner
  content_section:
    component_id: content
    name: Content

In this example hero_section is always active and cannot be disabled. banner_section and content_section can be enabled or disabled per page. Disabled components are hidden in the editor, cannot be saved, and are not exposed when page fields are returned by the API.

Component example

# config/lato_cms/components/hero.yml
id: hero
name: Hero
fields:
  title:
    name: Title
    type: string
    required: true
  subtitle:
    name: Subtitle
    type: textarea
  image:
    name: Image
    type: file
    settings:
      accept: "image/*"

Supported field types

Using CMS content in the application

Use Lato CMS pages as structured content records for public or private pages. Field values are available in their parsed form, so numbers, booleans, dates, JSON values, multi-select values, and files can be consumed directly by application views or serializers.

page = LatoCms::Page.find_by(permalink: "/homepage")
title = page.fields.find_by(field_id: "title")&.parsed_value
image = page.fields.find_by(field_id: "image")&.files&.first