DOCSEARCHbyAlgolia
Submit Docs

MaglevCMS Documentation

repository·main·Indexed 18 days ago

https://github.com/maglevhq/maglev-core

A visual page builder for Ruby on Rails (7.2+ and 8.x) that integrates directly into applications using Hotwire, Stimulus, and ViewComponent. It features a custom FormBuilder with specialized input helpers (TextField, ImageField, CheckBox, Textarea, Combobox, Select), a Maglev Client for editor-to-site communication, and a self-contained Tiptap bundle for rich text editing in Importmap environments.

Tokens
7.6K
Snippets
27
Records
37
Agent score
63%

What's inside MaglevCMS

  1. Overview of MaglevCMS

    main

    MaglevCMS is a visual page builder designed for Ruby on Rails (versions 7.2+ and 8.x). It allows marketing and content teams to edit pages directly in the browser while keeping all data and logic within your existing Rails application, avoiding the need for a separate headless CMS or external host.

    Key technical characteristics:

    • Architecture: Built using Hotwire, Stimulus, and ViewComponent.
    • Asset Management: Assets are shipped with the engine via importmap and vendored JS. You do not need Node, Webpack, or Vite for production use.
    • Frontend Flexibility: While the editor has specific requirements, your application's sections, themes, and layouts can use standard Rails templates (ERB, Haml, or Slim) and any CSS framework (Tailwind, Bootstrap, etc.).

  2. Overview of Maglev UIKit

    main

    Maglev UIKit is a shared library of ViewComponents and Stimulus controllers used to build the Maglev editor (including layouts, sections, settings, and inline controls). It provides the foundational UI patterns used throughout the Maglev CMS, such as buttons, forms, toolbars, modals, breadcrumbs, and device toggles.

    The UIKit is designed to allow developers to:

    • Design and review UI components in isolation without running a full Maglev site.
    • Regression-check styling and behavior for shared components.
    • Onboard contributors to the editor chrome without requiring the full CMS environment.

  3. Understand the Maglev v3 Draft and Published Page Workflow

    main

    Maglev v3 implements an explicit content lifecycle to separate editorial work from public delivery. This model ensures that ongoing edits do not immediately affect the live site.

    The Lifecycle States

    • draft: The editable working version. All editor actions, autosaves, and manual saves target this state.
    • published: The public version visible to visitors. Public-facing endpoints resolve only to this state.

    Core Operational Contract

    • Write to draft: All editing and administrative updates occur in the draft state.
    • Read from published: Public requests and visitor-facing endpoints resolve only to the published state.
    • Publishing: A deliberate, atomic operation that promotes draft content to the published state.

  4. Understand the Maglev v3 Editor Architecture

    main

    Maglev v3 has moved from a VueJS-based SPA to a Rails-native architecture. This architecture prioritizes server-side rendering and follows standard Rails conventions to simplify integration and customization.

    Core Stack:

    • Server-side rendering: The server is the source of truth; most UI is generated as HTML on the server.
    • ViewComponent: Used for composing reusable UI building blocks (side panels, toolbars, form controls).
    • Stimulus: Handles client-side interactions (toggling menus, wiring actions to requests, managing lightweight local state).
    • importmap: Used for JavaScript module loading, eliminating the need for JS precompilation or bundling steps.

  5. Build and run Lookbook Host with Docker

    main

    To ensure the Docker container includes the necessary preview files from spec/components/previews, you must run the build command from the repository root using the specific Dockerfile located in lookbook_host/.

    1. Build the image: docker build -f lookbook_host/Dockerfile -t maglev-lookbook .

    2. Run the container: docker run --rm -p 3000:3000 -e SECRET_KEY_BASE="$(openssl rand -hex 32)" maglev-lookbook

    docker build -f lookbook_host/Dockerfile -t maglev-lookbook .
docker run --rm -p 3000:3000 \
  -e SECRET_KEY_BASE="$(openssl rand -hex 32)" \
  maglev-lookbook

  6. Migrate custom editor UI from v2 to v3

    main

    If you are upgrading from Maglev v2, you must transition from VueJS-based customizations to Rails-native patterns:

    1. UI Components: Re-implement custom Vue components as ViewComponent classes and templates.
    2. Interactions: Re-implement client-side logic (previously managed in Vue) using Stimulus controllers.
    3. State Management: Remove any logic that assumes a Single Page Application (SPA) managed client-side state; instead, rely on server-driven state and standard Rails request/response cycles.

  7. Deploy Lookbook Host using Kamal

    main

    When deploying the Lookbook Host app via Kamal, observe the following requirements:

    • Build Context: The build context must be set to the repository root.
    • Dockerfile Path: Specify the Dockerfile as lookbook_host/Dockerfile.
    • Security: Set a strong SECRET_KEY_BASE for the deployment target.
    • Access Control: The application is public by default. If you require restricted access, you must implement a proxy solution such as an IP allowlist, SSO, or Cloudflare Access.

  8. Manage page visibility and publishing behavior

    main

    When working with the Maglev v3 lifecycle, be aware of the following behaviors regarding page availability and publishing:

    URL Flavors

    • preview: Used to render draft content for authorized users.
    • live: Used to serve published content to visitors.

    Visibility Rules

    • Unpublished pages: If a page has not been published, it will return a 404 error on the public side.
    • Unpublishing: Once a page has been published, it cannot be unpublished in the current version.
    • Rollback: While there is no formal publish history or rollback feature yet, you can discard current draft changes to return the draft to the latest published version.

    Publishing Scope

    • Per-page operation: Publishing is performed on a per-page basis.
    • Side effects: Publishing a specific page also automatically publishes the content of any site-scoped sections used by that page.

  9. Run the Lookbook Host App locally

    main

    The lookbook_host/ directory contains a minimal Rails host app used to publish Maglev Lookbook previews. It is designed to point directly to spec/components/previews in the engine repository to ensure previews are a single source of truth without file duplication.

    To run the host app locally, navigate to the lookbook_host directory, install dependencies, and start the server. The app uses the NullDB adapter, so no database setup (like db:create or db:migrate) is required. However, the app relies on db/schema.rb to understand model column definitions; if you encounter missing-column errors after Maglev migrations, you must refresh this file.

    Access the previews at http://localhost:3000/.

    cd lookbook_host
bundle install
./bin/rails server

  11. Use the Tiptap Bundle in your application

    main

    The Tiptap Bundle provides a single, self-contained ES module (tiptap.bundle.js) that includes Tiptap core and a selection of common extensions. This is ideal for environments like Rails with Importmap where you cannot easily resolve the deep dependency tree of ProseMirror packages.

    Integration Steps

    1. Build the bundle using the build commands (see Build the bundle).
    2. Copy the resulting dist/tiptap.bundle.js into your project's asset directory (e.g., app/assets/javascripts/vendor/ in a Rails project).
    3. Import the required classes directly from the bundle file using ES module syntax.
    <script type="module">
  import {
    Editor,
    Bold,
    Italic,
    Paragraph,
    // ... your needed extensions
  } from './tiptap.bundle.js'

  const editor = new Editor({
    element: document.querySelector('#editor'),
    extensions: [
      Paragraph,
      Bold,
      Italic,
    ],
    content: '<p>Hello Tiptap!</p>',
  })
</script>

  12. Use `./bin/rails` instead of `bundle exec rails`

    main

    When running Rails tasks within the lookbook_host directory, always use ./bin/rails (or ruby bin/rails) rather than the bare bundle exec rails command.

    Rails' CLI searches upward for a bin/rails executable. If you use bundle exec rails from the repository root or if the local bin/rails is bypassed, the system might pick up the engine stub's Rakefile (e.g., maglev-mit/bin/rails), which loads the wrong application context and causes errors.

    # Correct way to run rails tasks in lookbook_host
./bin/rails server