How to use Lato Users

lato_users adds a user management section to a Lato admin panel. Use it when the application needs admins to create users, edit user data, manage invitations, and handle account verification from the back office.

Installation

Add Lato Users to the application Gemfile:

gem "lato"
gem "lato_users"

Install the engine and run migrations:

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

Mount the engine in config/routes.rb:

Rails.application.routes.draw do
  mount LatoUsers::Engine => "/lato-users"

  # ...
end

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

@import "lato_users/application";

Import JavaScript in app/javascript/application.js:

import "lato_users/application"

Permissions

Users must be logged into Lato and must have Lato Users admin permission enabled. Grant permission from application seeds or from an existing admin account.

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

Admin permissions in the user form

The user form loads the available admin permissions automatically. Each Lato engine (for example lato_users, lato_spaces, lato_cms) adds its own permission column to the shared Lato::User table, and the form discovers them by naming convention:

• lato_*_admin — a boolean column, rendered as a checkbox (on/off permission).
• lato_*_admin_role — an integer column, rendered as a select (a role with multiple levels).

No configuration is required in lato_users: install an engine that adds one of these columns and its control appears in the form, gets permitted on create/update, and its label is taken from the Lato::User attribute translations.

Role permissions (enum)

For a role column, the owning engine provides the selectable options (label and value) by defining a Lato::User.<column>_options class method that returns [[label, value], ...]. lato_users calls it to build the select. For instance, lato_cms exposes its roles through Lato::User.lato_cms_admin_role_options, so the CMS role appears as a dropdown with the roles configured by that engine.

You can define your own role permission the same way, either from an engine or directly in the application. The example below adds a lato_shop_admin_role with three levels.

1. Add the integer column to the shared lato_users table:

# db/migrate/xxxxxxxxxxxxxx_add_shop_admin_role_to_lato_user.rb
class AddShopAdminRoleToLatoUser < ActiveRecord::Migration[8.1]
  def change
    add_column :lato_users, :lato_shop_admin_role, :integer, default: 0, null: false
  end
end

2. Expose the options by reopening Lato::User and defining lato_shop_admin_role_options. Wrap it in to_prepare so it survives code reloading in development. The method must return an array of [label, value] pairs, and the values must match the integers stored in the column:

# config/initializers/lato_shop_roles.rb
Rails.application.config.to_prepare do
  Lato::User.class_eval do
    def self.lato_shop_admin_role_options
      [
        [I18n.t("shop.roles.none"),    0],
        [I18n.t("shop.roles.manager"), 1],
        [I18n.t("shop.roles.owner"),   2]
      ]
    end
  end
end

3. Add the labels to a locale file. The option labels come from the keys used above, and the field label of the select comes from the Lato::User attribute translation:

# config/locales/en.yml
en:
  shop:
    roles:
      none: No access
      manager: Manager
      owner: Owner
  activerecord:
    attributes:
      lato/user:
        lato_shop_admin_role: Shop role

That is all. After running the migration the new role appears automatically as a select in the user form, gets permitted on create and update, and its value is saved on the user record. No change to lato_users is required. Reading the role back is a plain integer comparison:

user.lato_shop_admin_role         # => 0, 1 or 2
user.lato_shop_admin_role >= 1    # true when the user is at least a manager

What admins can do

• View all application users.
• Create new users.
• Edit user email, name, password, and available Lato admin permissions.
• Verify or revoke email verification.
• Send a new verification email.
• Generate a new password for a user.
• Delete users when allowed by the application data constraints.
• Create and delete invitations.

Recommended setup

Create at least one administrator in seeds and enable lato_users_admin. This guarantees access to the user management panel after first deployment.

admin = Lato::User.find_or_create_by!(email: "admin@example.com") do |user|
  user.first_name = "Admin"
  user.last_name = "User"
  user.password = "Password1!"
  user.password_confirmation = "Password1!"
  user.email_verified_at = Time.current
end

admin.update!(lato_users_admin: true)

Invitations

Use invitations when users should not self-register. Admins can create invitations from the Lato Users panel. Invited people receive an email and complete account creation from the invitation link.