<%= lato_page_head "Documentation" %>

How to use Lato Spaces

lato_spaces adds workspaces or groups to a Lato application. Use it when users must work inside one selected group and application data must be separated by group.

Installation

Add Lato Spaces to the application Gemfile:

gem "lato"
gem "lato_spaces"

Install the engine and run migrations:

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

Mount the engine in config/routes.rb:

Rails.application.routes.draw do
  mount LatoSpaces::Engine => "/lato-spaces"

  # ...
end

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

@import "lato_spaces/application";

Import JavaScript in app/javascript/application.js:

import "lato_spaces/application"

Permissions

Users must be logged into Lato. Admin users can manage all groups. Non-admin users can only access groups where they are members, based on configuration.

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

Configuration

Configure group behavior in an initializer:

LatoSpaces.configure do |config|
  config.setgroup_redirect_path = :dashboard_path
  config.setgroup_auto_after_login = false
  config.setgroup_auto_after_login_if_single = true
  config.permit_group_creation = false
  config.permit_group_management = false
  config.permit_group_preferred = false
end

Option	Use for
`setgroup_redirect_path`	Redirect users after they select a group.
`setgroup_auto_after_login`	Select a group automatically when possible.
`permit_group_creation`	Allow non-admin users to create groups.
`permit_group_management`	Allow non-admin users to manage their groups and members.
`permit_group_preferred`	Allow users to mark a preferred group.

What users can do

See available groups.
Select the active group for the current session.
Work only with data that belongs to the selected group.
Invite other users to a group when management is allowed.
Choose a preferred group when enabled.

Protecting application pages

Include the group helper in controllers that require a selected group, then require both Lato authentication and group selection.

class ApplicationController < Lato::ApplicationController
  include LatoSpaces::Groupable
end

class ProjectsController < ApplicationController
  before_action :authenticate_session
  before_action :authenticate_group

  def index
    @projects = Project.for_lato_spaces_group(@session.get(:spaces_group_id))
  end
end

Associating application data with groups

Add Lato Spaces associations to application records that must belong to one or more groups.

class Project < ApplicationRecord
  include LatoSpaces::Associable
end

When records must always belong to exactly one group, add the stricter concerns:

class Project < ApplicationRecord
  include LatoSpaces::Associable
  include LatoSpaces::AssociableRequired
  include LatoSpaces::AssociableUnique
end

Create records with the current selected group:

Project.create!(
  name: "Project 1",
  lato_spaces_group_id: @session.get(:spaces_group_id)
)

Customizing group forms

The install task copies overridable partials into the host application. Edit those partials to add custom fields or extra information to group and membership pages. If custom fields are added, also permit them in Lato Spaces configuration.