triniti/canvas

This package is abandoned and no longer maintained. The author suggests using the triniti/core package instead.

Php library that provides implementations for triniti:canvas schemas.

v1.0.1 2019-10-29 00:49 UTC

This package is auto-updated.

Last update: 2021-06-16 23:17:24 UTC


README

Build Status Code Climate Test Coverage

Php library that provides implementations for triniti:canvas schemas. Using this library assumes that you've already created and compiled your own pbj classes using the Pbjc and are making use of the "triniti:canvas:mixin:*" mixins from triniti/schemas.

Symfony Integration

Enabling these services in a Symfony app is done by importing classes and letting Symfony autoconfigure and autowire them.

config/packages/canvas.yml:

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  Triniti\Canvas\:
    resource: '%kernel.project_dir%/vendor/triniti/canvas/src/**/*'

Twig Extension

This library provides an extension which currently has one function called canvas_render_blocks. This function takes an array of blocks (messages having mixin triniti:canvas:mixin:block) and an array of options which are used to create a render context (an instance of triniti:common::render-context).

The Twig extension is automatically available if using Symfony autowiring.

Example:

Assume that we have a acme:canvas:node:page instance named page and it has a field called blocks.

# page.html.twig

<html>
  <title>{{ page.get('seo_title') }}</title>
</html>
<body>
  <h1>{{ page.get('title') }}</h1>

  <div class="contents">
    {{ canvas_render_blocks(page.get('blocks', []), {
      container: page,
      section: 'main',
      booleans: {
        enable_ads: true,
        dnt: false,
        autoplay_videos: false,
      },
      strings: {
        custom1: 'val1',
        custom2: 'val2',
        customN: 'val3',
      },
    }) }}
  </div>
</body>
</html>

This function will render all blocks using Twig by resolving the context and the block type to a Twig template. The filename requested must be in the Twig namespaced path @canvas_blocks. All segments are optional except the platform, which defaults to "web".

First template found is used:

  • @canvas_blocks/{$platform}/{$section}/{$blockName}/{$blockName}.{$deviceView}.twig
  • @canvas_blocks/{$platform}/{$section}/{$blockName}/{$blockName}.twig
  • @canvas_blocks/{$platform}/{$blockName}/{$blockName}.{$deviceView}.twig
  • @canvas_blocks/{$platform}/{$blockName}/{$blockName}.twig
  • @canvas_blocks/{$platform}/missing_block.twig

Example output:

e.g. @canvas_blocks/web/blogroll/youtube_video_block/youtube_video_block.smartphone.twig

The payload provided to the template:

$twig->render($name, [
    'pbj'           => $block,         // instance of triniti:canvas:mixin:block
    'pbj_name'      => $blockName,     // e.g. quote_block
    'prev_pbj'      => $prevBlock,     // previous block instance or null
    'prev_pbj_name' => $prevBlockName, // previous block name (e.g. youtube_video_block) or null
    'next_pbj'      => $nextBlock,     // next block instance or null
    'next_pbj_name' => $nextBlockName, // next block name (e.g. youtube_video_block) or null
    'rendered'      => $rendered,      // a map of the already rendered block names
                                       // slug-case and snake_case. e.g. ['page-break-block' => true, 'text-block' => true]
    'context'       => $context,       // instance of triniti:canvas:block:render-context
    'idx'           => $idx,           // array index starting from 1
    'is_first'      => $isFirst,       // bool, true if first block
    'is_last'       => $isLast,        // bool, true if last block
    'total_blocks'  => $total,         // int, total number of blocks being rendered
]);