Spina CMS Documentation

Spina CMS provides 8 built-in content parts that can be used to construct page layouts. These parts represent different types of data structures and UI components available for page building.

- `Spina::Parts::Line`
- `Spina::Parts::MultiLine`
- `Spina::Parts::Text`
- `Spina::Parts::Image`
- `Spina::Parts::ImageCollection`
- `Spina::Parts::Attachment`
- `Spina::Parts::Option`
- `Spina::Parts::Repeater`

The Spina admin UI utilizes modern browser features like import maps.

Admin UI Requirements:

• Chrome/Edge 89+
• Or any browser with basic ESM support (e.g., Safari, Firefox).

Website Frontend: Spina does not impose any restrictions on how you build the frontend for the websites you create; browser support for your public-facing site is entirely up to your implementation.

All Spina CMS API endpoints that return lists of records are paginated. The JSON response includes two additional top-level attributes, meta and links, which provide context about the current page and navigation options.

• meta: Contains metadata about the collection, including current_page, total (total records), per_page (records per page), and the base path.
• links: Contains URLs for navigating the collection, including first, prev (null if on the first page), next (null if on the last page), and last.

"meta": {
  "current_page": 1,
  "total": 75,
  "per_page": 25,
  "path": "/api/pages"
},
"links": {
  "first": "/api/pages?page=1",
  "prev": null,
  "next": "/api/pages?page=2",
  "last": "/api/pages?page=3"
}

Spina uses Tailwind 3 via the tailwindcss-rails gem. It automatically manages the Tailwind compilation process by hooking into the Rails assets:precompile task.

When assets are precompiled, Spina performs the following steps:

1. Scans paths defined in Spina.config.tailwind_content for Tailwind classes.
2. Generates a specific Tailwind configuration file at app/assets/config/spina/tailwind.config.js.
3. Compiles the CSS using the Tailwind executable.
4. Saves the resulting build to app/assets/builds/spina/tailwind.css.

This ensures that all classes used in Spina views and plugins are included in the production CSS build.

A Spina::Resource is a way to manage a distinct set of pages outside of the standard page hierarchy without writing a full plugin. Resources appear as new list items in the Spina website navigation. They are ideal for managing large, flat, or semi-structured lists of content such as:

• Blogs
• SEO landing pages
• Team member lists

Pages within a resource can be nested, but they cannot be manually ordered. Instead, they are ordered by created_at or title, which facilitates features like infinite scrolling for large datasets.

A page in Spina is composed of multiple 'page parts', which are the building blocks of your view templates. Each page part represents a specific type of content (like text, images, or structures) that can be managed in the admin interface.

By default, Spina includes several page part types:

• Spina::Line
• Spina::Text
• Spina::Image
• Spina::ImageCollection
• Spina::Structure
• Spina::Option

To use a new page part, you must follow a three-step process: register it in a theme initializer, assign it to a view template, and then render it in your view template file.

In Spina, a page is composed of multiple 'parts', which serve as the building blocks for your view templates. Each part corresponds to a specific data type (e.g., text, images, or repeaters) that an editor can fill in via the admin interface.

By default, Spina provides several part types:

• Spina::Parts::Line
• Spina::Parts::MultiLine
• Spina::Parts::Text
• Spina::Parts::Image
• Spina::Parts::ImageCollection
• Spina::Parts::Repeater
• Spina::Parts::Option

To implement a new part in your application, you must follow a three-step process: register the part in a theme initializer, assign it to a view template, and then render it in your ERB view.

To enable the Spina API, you must set an api_key within the Spina configuration initializer. It is highly recommended to store this key securely using Rails credentials rather than hardcoding it.

Note: The API is currently in beta and may not include all possible endpoints.

Spina.configure do |config|
  # ...
  config.api_key = Rails.application.credentials.spina_api_key
end

To add an image collection to your Spina CMS layout, add a new part to your config.parts array with the part_type set to Spina::Parts::ImageCollection. This allows you to manage a collection of images within that specific part.

config.parts = [
  # ...
  {
    name: "cars",
    title: "Images of cars",
    part_type: "Spina::Parts::ImageCollection"
  }
]

Navigations allow you to create multiple, distinct collections of pages. This provides flexibility beyond the default single overview of all pages, enabling you to include specific subsets of pages and manage their order per navigation.

To define navigations, use the theme.navigations= configuration key within your Spina::Theme.register block. Each navigation is defined as a hash in an array.

::Spina::Theme.register do |theme|
  # ...

  theme.navigations = [{
    name: 'main',
    label: 'Main navigation',
    auto_add_pages: true
  }, {
    name: 'mobile',
    label: 'Mobile'  
  }]

  # ...
end

Once a Line part is configured, use the content helper method in your view templates to render its value. Pass the name defined in your configuration to the helper.

<h1><%= content(:headline) %></h1>