README

A compact, visual way to lay out fields, elements, and Matrix blocks.

Requirements

This plugin requires Craft CMS 4.0 or later.

Installation

To install the plugin, follow these instructions.

Open your terminal and go to your Craft project:
```
cd /path/to/project
```

Then tell Composer to load the plugin:

composer require wbrowar/craft-little-layout

In the Control Panel, go to Settings → Plugins and click the “Install” button for Little Layout.
Create and configure new Little Layout fields for your elements.

Little Layout Overview

Little Layout is a compact field that makes it easy for content authors to adjust the layout of their content or UI and other design elements. It gives developers values that make it easy to move content around CSS grid layouts or around a set of coordinates. Little Layout fields are accessible and mobile-friendly.

Configuring Little Layout

When setting up a new Little Layout field, you will need to define how many columns and rows are available in your field. A preview of your field will appear and will get updated as you adjust your settings.

After your columns and rows are set, you can set a default value in your field preview. It works just like the field does during the author experience:

Click on a box to select it
Click on another box to draw a rectangle between the two selected points, selecting all points within the rectangle
Once a value is added, click on the "x" icon to the right to clear the field

Use the Empty Layout setting to determine if authors can clear out the layouts they have set. NOTE: setting your field to required also removes the author’s ability to clear field layouts, regardless of this setting.

Using Little Layout

The following data can be retrieved in your Twig- or GraphQL-based templates:

*Coordinates are formatted in 'x|y' format.

Accessing Little Layout Values in Twig

Use element.fieldHandle.empty like this to check to see if a Little Layout field has a value:

{% if not element.fieldHandle.empty %}
  {# Use layout fields #}
{% endif %}

Using Twig to Lay Out Elements in a CSS Grid

To lay out an element in a CSS grid layout you could do something like this to specify exact grid columns and rows:

<div style="grid-column-start: {{ element.fieldHandle.gridColumnStart }}; grid-column-end: {{ element.fieldHandle.gridColumnEnd }}; grid-row-start: {{ element.fieldHandle.gridRowStart }}; grid-row-end: {{ element.fieldHandle.gridRowEnd }};"></div>

Or you could use the shorthand grid-column and grid-row properties and provide starting and span values.

<div style="grid-column: {{ element.fieldHandle.gridColumnStart }} / span {{ element.fieldHandle.gridColumnSpan }}; grid-row: {{ element.fieldHandle.gridRowStart }} / span {{ element.fieldHandle.gridRowSpan }};"></div>

Even better, consider using CSS Custom Properties:

<div class="layout" style="--grid-column-start: {{ element.fieldHandle.gridColumnStart }}; --grid-column-span: {{ element.fieldHandle.gridColumnSpan }}; --grid-row-start: {{ element.fieldHandle.gridRowStart }}; --grid-row-span: {{ element.fieldHandle.gridRowSpan }};"></div>

With CSS that looks like this:

.layout {
   grid-column: var(--grid-column-start) / span var(--grid-column-span);
   grid-row: var(--grid-row-start) / span var(--grid-row-span);
}

If you use a CSS framework, like Tailwind CSS, you could do something like this:

<div class="col-start-[{{ element.fieldHandle.gridColumnStart }}] col-span-[{{ element.fieldHandle.gridColumnSpan }}] row-start-[{{ element.fieldHandle.gridRowStart }}] row-span-[{{ element.fieldHandle.gridRowSpan }}]"></div>

If your Twig template files are included in your Tailwind confguration’s content patterns, you may prefer to preserve full class names using logic and a lookup table:

{% set columnStartClasses = {
  1: 'col-start-1',
  2: 'col-start-2',
  3: 'col-start-3',
  4: 'col-start-4',
  5: 'col-start-5',
  6: 'col-start-6',
} %}
{% set columnSpanClasses = {
  1: 'col-span-1',
  2: 'col-span-2',
  3: 'col-span-3',
  4: 'col-span-4',
  5: 'col-span-5',
  6: 'col-span-6',
} %}
{% set rowStartClasses = {
  1: 'row-start-1',
  2: 'row-start-2',
  3: 'row-start-3',
  4: 'row-start-4',
  5: 'row-start-5',
  6: 'row-start-6',
} %}
{% set rowSpanClasses = {
  1: 'row-span-1',
  2: 'row-span-2',
  3: 'row-span-3',
  4: 'row-span-4',
  5: 'row-span-5',
  6: 'row-span-6',
} %}

{% set myAttributes = {
  class: [
    columnStartClasses[element.fieldHandle.gridColumnStart],
    columnSpanClasses[element.fieldHandle.gridColumnSpan],
    rowStartClasses[element.fieldHandle.gridRowStart],
    rowSpanClasses[element.fieldHandle.gridRowSpan],
  ],
} %}

<div {{ attr(myAttributes) }}></div>

{# Results look like this: <div class="col-start-1 col-span-3 row-start-1 row-span-2"></div> #}

Get CSS Grid values in GraphQL

The same values can be retrieved in GraphQl, like this:

{
  entries(type: "mySection") {
    ... on mySection_mySectionType_Entry {
      fieldHandle {
        empty
        gridColumnStart
        gridRowStart
        gridColumnSpan
        gridRowSpan
      }
    }
  }
}

Example: Simple Text Align Field

You can also use the values selected in a Little Layout field for other purposes. For example, you use a Little Layout field as a visual way to select between text left, center, and right alignment.

To set this up, you could do something like this:

Set up a new field with 3 columns and 1 row.
Set Empty Layout to Layouts cannot be reset (or set this field to required in the field layout designer).
Select the single box that you would like to use as a default.
Save your field and add it to your elements.

Then on the front-end, (assuming LTR reading order in this case), you can do something like this (NOTE: this example uses Twig and Tailwind, but the logic is the same in other setups):

{% set textAlignClasses = {
  1: 'text-left',
  2: 'text-center',
  3: 'text-right',
} %}

{% set myAttributes = {
  class: [
    textAlignClasses[element.fieldHandle.selectedColumns[0]],
  ],
} %}

<div {{ attr(myAttributes) }}></div>

In this case element.fieldHandle.selectedColumns gives us an array with the numbers 1, 2, or 3 as the value.

Releases

Release notes can be found at CHANGELOG.md

Supported Versions

Here is a general goal for adding and supporting features for Little Layout going forward:

New features for the plugin will be added to the current major plugin version that targets the current released version of Craft CMS.
The latest major plugin version that targets the previous released major version of Craft CMS will be supported with bug fixes intruduced in updates to that version of Craft CMS.
Previous major plugin versions will only get security-related updates—when necessary.

Brought to you by Will Browar

wbrowar / craft-little-layout

Maintainers

Details