femundfilou/kirby-render-layouts

Snippet to use layouts with simple section + column structure.

1.0.2 2023-04-14 06:25 UTC

Requires

• php: >=7.1.0
• getkirby/cms: ^3.6
• getkirby/composer-installer: ^1.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.8

MIT

• Justus Kraft

• kirby-plugin

README

This plugin adds a snippet to render layout fields in structured way. By default, it uses bulma.io classes to do so.

Installation

The best way is to install it via composer.

composer require femundfilou/kirby-render-layouts

Usage

Whenever you are using a type: layouts field in your blueprint, you can use the provided snippet to render your field.

snippet('render-layouts', ['field' => $page->myLayoutFieldName()]);

This will render the following basic markup for each layout you add in the panel.

<section class="section">
  <div class="container">
    <div class="columns">
      <div class="column is-[fraction]">
        <div class="block block-type-[myblock]" data-block-type="[myblock]">
          ...
        </div>
      </div>
    </div>
  </div>
</section>

Configuration

You can override the default configuration inside your config.php as well as on each snippet itself.

Override in config.php

return [
  'femundfilou.render-layouts.defaults' => [
    'columns' => 12, // Defines the max columns count, used to calculate each columns fraction.
    'sectionClass' => 'section', // Default class used for section
    'containerClass' => 'container', // Default class used for container
    'columnsClass' => 'columns', // Default class used for columns
    'columnClass' => 'column', // Default class used for column
    'blockClass' => 'block',  // Default class uses for block
    'columnWidthClass' => function(int $columnSpan) {
        // Return a string which is used on each indidual column as a width class
        return  'is-' . $columnSpan;
    }
  ],
];

Override in snippet

snippet('render-layouts', ['field' => $page->myLayoutFieldName(), 'columnsClass' => 'grid']);

which will result in the following markup on this page.

<section class="section">
  <div class="container">
    <div class="grid">
      <div class="column is-[fraction]">
        <div class="block block-type-[myblock]" data-block-type="[myblock]">
          ...
        </div>
      </div>
    </div>
  </div>
</section>

Custom attributes & layout settings

To further customize each layout, this plugin provides an easy way to use fields defined as layout settings.

Predefined fields

There are three reserved field names you can use to add classes to the different wrappers. Simply use them inside your layout settings fields like this:

mylayoutfield:
  label: Layout
  type: layout
  layouts:
    - "1/1"
    - "1/2, 1/2"
  settings:
    fields:
      sectionClass:
        label: Section
        type: select
        options:
          'my-section-class' : 'Example'
        ...
      containerClass:
        ...
      columnsClass:
        ...

Use your own fields and attributes

Beside the predefined fields, you can use any of your own fields to add attributes to the section. First add the fields to your layout field, e.g.

mylayoutfield:
  label: Layout
  type: layout
  layouts:
    - "1/1"
    - "1/2, 1/2"
  settings:
    fields:
      spacingclass:
        label: Spacing
        type: select
        options:
          '' : Default
          'is-medium': Medium
          'is-large': Large
      background:
        label: Background color
        type: toggles
        default: ''
        options:
          'transparent' : No background
          '#000' : Black
          '#fff' : White

Then define the fields you want to use inside your config.php. In the femundfilou.render-layouts.fields array define the field name that should be used as key and the attribute or a function returning an associative array as value.

return [
'femundfilou.render-layouts.fields' => [
    // Provide an field name and attribute
    'spacingclass' => 'class'
    // Or use a function to go crazy. You event get access to the current layout.
    'background' => function($layout) {
      // Return attribute and value
      return ['style' => '--background-color: ' . $layout->background(). ';'];
    },
  }
]

This will result in the following markup.

<section class="section is-medium" style="--background-color: #000;">
  <div class="container">
    <div class="columns">
      <div class="column is-[fraction]">
        <div class="block block-type-[myblock]" data-block-type="[myblock]">
          ...
        </div>
      </div>
    </div>
  </div>
</section>