Katalyst::Content

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

Installation

Install the gem as usual

ruby gem "katalyst-content"

Mount the engine in your routes.rb file:

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

Add the Gem’s migrations to your application:

ruby 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.

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

sass @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:

```ruby 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:

```ruby 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:

```ruby 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.

```ruby 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:

erb <%# 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.