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:

mountKatalyst::Content::Engine,at: "content"

Add the Gem's migrations to your application:

rakekatalyst_content:install:migrations

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

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

Import the editor styles as css:

/** In your admin/editor */@importurl("/katalyst/content/editor.css");
/** In your frontend */@importurl("/katalyst/content/frontend.css");

Or, if you're using dartsass-rails:

// app/assets/stylesheets/admin.scss@use"katalyst/content/editor";
// app/assets/stylesheets/application.scss@use"katalyst/content/frontend";

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:

classCreatePageVersions < ActiveRecord::Migration[7.0]defchangecreate_table:page_versionsdo |t|
t.references:parent,foreign_key: {to_table: :pages},null: falset.json:nodest.timestampsendchange_table:pagesdo |t|
t.references:published_version,foreign_key: {to_table: :page_versions}t.references:draft_version,foreign_key: {to_table: :page_versions}endendend

If you don't have a pages model yet, add it before the page_versions change:

classCreatePages < ActiveRecord::Migration[7.0]defchangecreate_table:pagesdo |t|
t.string:titlet.string:slugt.boolean:show_title,default: true,null: falset.timestampsendadd_index:pages,:slug,unique: truecreate_table:page_versionsdo |t|
t.references:parent,foreign_key: {to_table: :pages},null: falset.json:nodest.timestampsendchange_table:pagesdo |t|
t.references:published_version,foreign_key: {to_table: :page_versions}t.references:draft_version,foreign_key: {to_table: :page_versions}endendend

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

classPage < ApplicationRecordincludeKatalyst::Content::ContainerclassVersion < ApplicationRecordincludeKatalyst::Content::Versionendend

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

FactoryBot.definedofactory:pagedotitle{Faker::Beer.unique.name}slug{title.parameterize}after(:build)do |page,_context|
page.items.each{ |item| item.container=page}endafter(:create)do |page,_context|
page.items_attributes=page.items.map.with_index{ |item,index| {id: item.id,index: index,depth: 0}}page.publish!endendend

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

classAdmin::PagesController < Admin::BaseControllerbefore_action:set_page,only: %i[showupdate]defshow;enddefupdate@page.attributes=page_paramsunless@page.valid?returnrespond_todo |format|
format.turbo_stream{render@editor.errors,status: :unprocessable_entity}endendcaseparams[:commit]when"publish"@page.save!@page.publish!when"save"@page.save!when"revert"@page.revert!endredirect_to[:admin,@page],status: :see_otherendprivatedefset_page@page=Page.find(params[:id])@editor=Katalyst::Content::EditorComponent.new(container: @page)enddefpage_paramsparams.require(:page).permit(items_attributes: %i[idindexdepth])endend

And the view:

<%# app/views/admin/pages/show.html.erb %><%= render @editor.status_bar %><%= render @editor %>

New items dialog customisation

The new items dialog can be customised by providing content to the ViewComponent slot:

<%# app/views/admin/pages/show.html.erb %><%= render @editor.status_bar %><%= render @editor do |editor_component| %><% editor_component.with_new_items do |component| %><h3>Layouts</h3><ulrole="list" class="items-list"><%=component.item(:section)%><%=component.item(:group)%><%=component.item(:column)%><%=component.item(:aside)%></ul><h3>Content</h3><ulrole="list" class="items-list"><%=component.item(:content)%><%=component.item(:figure)%><%=component.item(:table)%></ul><%end%><%end%>

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.