DOCSEARCHbyAlgolia
Submit Docs

Trailblazer Documentation

website·Indexed 34 days ago

https://trailblazer.to/2.1/docs/trailblazer/index.html

A set of Ruby gems and architectural guides for building web applications. It features a focus on decoupling business logic through the Trailblazer::Operation class, view models via the Cells gem, and data mapping with Representable and Reform. The documentation covers high-level architecture, persistence handling, validations, policies, and integration with frameworks like Rails, Sinatra, and Grape.

Tokens
114.8K
Snippets
802
Records
876
Agent score
56%

What's inside Trailblazer

  1. Overview of Cells View Models

    The cells gem provides View Models, which are objects representing fragments of a UI (ranging from a full page to a single link). They act like small Rails controllers without HTTP coupling, encapsulating presentation and rendering logic to improve performance and enforce interfaces over standard ActionView partials and helpers.

  2. Overview of Trailblazer architectural abstractions

    Trailblazer is a collection of Ruby gems providing high-level architectural layers to help structure growing applications. These layers are stand-alone and can be used independently of the full stack. Key abstractions include:

    • Form objects (Reform): Move validation and processing logic out of models into dedicated renderable objects.
    • Service objects (Operation): Orchestrate business code and domain layers for a testable architecture.
    • View components (Cells): Provide better encapsulation within HTML views.
    • Representers (Representable): Parse incoming JSON/XML and serialize outgoing data.

    Note: Trailblazer does not provide SQL abstractions or routing, as these are typically handled by frameworks like Rails or Hanami.

  3. Overview of Trailblazer::Endpoint

    Trailblazer::Endpoint provides a pattern-matching mechanism to handle the outcomes of an operation. Instead of using complex if/else trees to check the state of a result object, it uses a matcher (powered by the dry-matcher gem) to trigger specific handlers based on predefined scenarios.

  4. Overview of Trailblazer Activities

    An activity is a collection of connected tasks with one start event and one or more end events. It serves as the primary mechanism for organizing control flow in Trailblazer, utilizing BPMN (Business Process Model and Notation) concepts. While Trailblazer::Operation provides a railway-oriented DSL (left/right tracks), it internally maintains an Activity instance. The activity gem allows for the definition of more complex graphs where tasks are vertices and signals are edges.

  5. Overview of Reform form objects

    Reform provides form objects that move validations out of model classes and into dedicated form classes. It is framework-agnostic and works with any Ruby object (PORO) or ORM, provided the model has reader and writer methods for the defined properties. Reform acts as an intermediate layer for deserialization and validation before data is written to the persistence layer. It enhances security by ignoring any input not explicitly defined as a property.

  6. Overview of Trailblazer Architecture Abstractions

    Trailblazer extends the basic MVC pattern with a set of optional abstractions designed to organize code by concept rather than technology. This modular structure simplifies refactoring and allows for more efficient unit testing by decoupling business logic from the delivery mechanism (e.g., controllers).

  7. Overview of Cells View Models

    Cells are standalone objects that represent fragments of a UI and can render templates. They act as small controllers without HTTP coupling, encapsulating presentation and rendering logic to replace complex Rails helpers or partials. Cells are generally faster than ActionView and enforce better encapsulation of UI fragments.

  8. Overview of the Trailblazer framework

    Trailblazer is a framework-agnostic set of Ruby gems designed to improve application code structure by providing abstractions for business logic. It is intended to reduce technical debt in complex applications by moving logic out of controllers and models (Lean MVC) and into dedicated layers. It is compatible with Ruby 2.1+ and works with frameworks such as Rails, Hanami, Roda, Grape, and Sinatra.

  9. Understand Reform's Data Flow (Populators and Virtual Graphs)

    Reform uses a specific pipeline to move data from a document to a model:

    1. Deserialization: Uses a 'representer' to parse input.
    2. Populators: Code snippets in the form class that help the representer find existing models or create new ones for nested fragments.
    3. Virtual Object Graph: After validate, data exists in a virtual graph (the form object), not the model. This allows complex business validations without mutating the database.
    4. Sync/Save: Data is only written to the model's public setters when #sync or #save is explicitly called.

  10. Organize Trailblazer files using Concepts

    Trailblazer uses 'concepts' to group files by feature rather than by technology. A concept (e.g., comment) contains its related contracts, cells, operations, and views.
    app
├── concepts
│   ├── comment
│   │   ├── contract
│   │   │   ├── create.rb
│   │   │   └── update.rb
│   │   ├── cell
│   │   │   └── new.rb
│   │   ├── operation
│   │   │   ├── create.rb
│   │   │   └── update.rb
│   │   └── view
│   │       ├── new.haml
│   │       └── show.haml

  11. Use Reform 2.2 in non-Rails frameworks

    Reform 2.2 has been stripped of all remaining Rails-specific code, allowing it to be used in other frameworks without requiring ActiveModel. For users who still require Rails-specific functionality, the reform-rails gem must be installed.

  12. Implement data validation using Reform Contracts

    A contract in Trailblazer is an abstraction used to handle the validation of arbitrary data or object state. When using Reform, contracts are defined as classes inheriting from Reform::Form. They allow for deserializing and validating deeply nested hashes and writing that data to a persistence layer (like ActiveRecord) once valid.
    # app/concepts/song/contract/create.rb
module Song::Contract
  class Create < Reform::Form
    property :title
    property :length

    validates :title,  length: 2..33
    validates :length, numericality: true
  end
end