Reference Guide

Matrix System Context Layer (matrix--)

matrix is an optional system-level marker (only if you have multiple base templates). It represents the overarching structure or template layout for a web page.

Matrix as a Simulation Framework

Copy link to this section

An Analogy: The Matrix in Blocktail acts as a simulation that hosts multiple timelines or alternate realities, with key principles:

  • Coexistence of Contexts: Different contexts can exist simultaneously within the Matrix
  • Adaptive Blocks: Blocks can adapt their appearance and behavior based on the system context provided by the Matrix

Implementation Guide

Copy link to this section

Basic Structure

Copy link to this section

A Matrix is typically implemented on the <body> tag:

<body class="matrix--main_template">
  <!-- Page content -->
</body>

CMS Integration

Copy link to this section

Matrix in Blocktail acknowledges and embraces the constraints of predefined templates, especially in Content Management Systems (CMS). It treats the overall structure of a page as a simulation, providing a consistent framework for layout and styling across different sections.

CMS Template Awareness

Blocktail's Matrix encourages developers to recognize and embrace the unique characteristics of CMS templates:

<!-- Template-Specific Matrix -->
<body class="matrix--single_product">
  <!-- Content for a single product page -->
</body>

<!-- Reusable Matrix -->
<body class="matrix--product">
  <!-- Content that can be used across product templates -->
</body>

<!-- Server-Side Integration -->
<body class="matrix--single_product <?php echo get_body_class(); ?>">
  <!-- Content adapting to both Blocktail and CMS classes -->
</body>

Benefits in Development

Copy link to this section

Consistency Across Templates:

  • Ensures consistent layouts and styling
  • Reduces redundant CSS declarations
  • Maintains predictable structure

Improved Maintainability:

  • Centralizes layout and styling logic
  • Reduces code duplication
  • Simplifies template management

Enhanced Flexibility:

  • Allows for adaptable designs across templates
  • Supports dynamic content structures
  • Enables responsive layouts

Clearer Structure:

  • Provides clear, top-level organization
  • Creates predictable layout patterns
  • Improves developer understanding

Interaction with Other Blocktail Concepts

Copy link to this section

Matrix and Contexts

Copy link to this section
<body class="matrix--shop">
  <main class="context--catalog">
    <!-- Catalog-specific content -->
  </main>
  <aside class="context--featured">
    <!-- Featured content -->
  </aside>
</body>

Matrix and Blocks

Copy link to this section
<body class="matrix--shop">
  <article class="product_card">
    <!-- Product content adapts to shop matrix -->
  </article>
</body>

Matrix with Multiple Systems

Copy link to this section
<body class="matrix--shop matrix--authenticated">
  <!-- Content adapts to both shop and authenticated states -->
</body>

Pattern Validation

Copy link to this section

Valid Patterns

Copy link to this section
✓ class="matrix--shop"                  <!-- Single matrix -->
✓ class="matrix--shop matrix--mobile"   <!-- Multiple matrices -->
✓ class="matrix--admin_dashboard"       <!-- Compound name -->

Invalid Patterns

Copy link to this section
✗ class="matrix-shop"                   <!-- Single dash -->
✗ class="shop_matrix"                   <!-- Wrong prefix position -->
✗ class="matrix--shop-mobile"           <!-- Using hyphens instead of underscore -->

Key Takeaways

Copy link to this section
  • Matrix defines template boundaries
  • Applied at template level (typically <body>)
  • Uses matrix-- prefix
  • Can combine multiple matrices
  • Provides us with a foundation for contexts and blocks
  • Integrates well with CMS environments

matrix imposes no significant performance overhead—it’s purely a semantic marker to keep your top-level layout organized.

Code licensed MIT, docs CC BY 4.0.