Katalyst::Content

Katalyst Content provides tools for creating and publishing content on Rails applications.

Installation

Install the gem as usual

gem "katalyst-content"

Mount the engine in your routes.rb file:

mount Katalyst::Content::Engine, at: "content"

Add the Gem's migrations to your application:

rake katalyst_content:install:migrations

Add the Gem's javascript and CSS to your build pipeline. This assumes that you're using rails-dartsass and importmaps to manage your assets.

// app/javascript/controllers/application.js
import { application } from "controllers/application";
import content from "@katalyst/content";
application.load(content);

@use "katalyst/content";

Usage

Content can be added to multiple models in your application. These examples assume a Page model.

Assuming your model already exists, create a table for versions and add published and draft version columns to your model. For example, if you have a pages model:

class CreatePageVersions < ActiveRecord::Migration[7.0]
  def change
    create_table :page_versions do |t|
      t.references :parent, foreign_key: { to_table: :pages }, null: false
      t.json :nodes

      t.timestamps
    end

    change_table :pages do |t|
      t.references :published_version, foreign_key: { to_table: :page_versions }
      t.references :draft_version, foreign_key: { to_table: :page_versions }
    end
  end
end

Next, include the Katalyst::Content concerns into your model, and add a nested model for storing content version information:

class Page < ApplicationRecord
  include Katalyst::Content::Container

  class Version < ApplicationRecord
    include Katalyst::Content::Version
  end
end

You may also want to configure your factory to add container information to items:

FactoryBot.define do
  factory :page do
    title { Faker::Beer.unique.name }
    slug { title.parameterize }

    after(:build) do |page, _context|
      page.items.each { |item| item.container = page }
    end

    after(:create) do |page, _context|
      page.items_attributes = page.items.map.with_index { |item, index| { id: item.id, index: index, depth: 0 } }
      page.publish!
    end
  end
end

Create a controller for editing content. This example assumes you're rendering the editor on the 'show' route of an admin controller.

class Admin::PagesController < Admin::BaseController
  before_action :set_page, only: %i[show update]
  
  def show; end

  def update
    @page.attributes = page_params

    unless @page.valid?
      return respond_to do |format|
        format.turbo_stream { render @editor.errors, status: :unprocessable_entity }
      end
    end

    case params[:commit]
    when "publish"
      @page.save!
      @page.publish!
    when "save"
      @page.save!
    when "revert"
      @page.revert!
    end

    redirect_to [:admin, @page], status: :see_other
  end
  
  private
  
  def set_page
    @page = Page.find(params[:id])
    @editor = Katalyst::Content::EditorComponent.new(container: @page)
  end

  def page_params
    params.require(:page).permit(items_attributes: %i[id index depth])
  end
end

And the view:

<%# app/views/admin/pages/show.html.erb %>
<%= render @editor.status_bar %>
<%= render @editor %>
<%# We suggest you render new items in a sidebar %>
<%= render @editor.new_items %>

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake to run the tests.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number and run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/katalyst/content.

License

The gem is available as open source under the terms of the MIT License.