PHPackages                             vierbeuter/craft-module-field-type - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. vierbeuter/craft-module-field-type

AbandonedArchivedLibrary

vierbeuter/craft-module-field-type
==================================

PHP library for Craft CMS 3 to simplify usage of matrix blocks as content modules

16771PHP

Since May 2Pushed 6y ago3 watchersCompare

[ Source](https://github.com/Vierbeuter/craft-module-field-type)[ Packagist](https://packagist.org/packages/vierbeuter/craft-module-field-type)[ RSS](/packages/vierbeuter-craft-module-field-type/feed)WikiDiscussions develop Synced 2mo ago

READMEChangelogDependenciesVersions (3)Used By (0)

Craft Module Field Type
=======================

[](#craft-module-field-type)

A library for your Craft 3 plugin/module development.

Contents
--------

[](#contents)

- [What is this?](#what-is-this)
    - [Short version](#tell-me-in-two-sentences)
    - [Long version](#i-still-dont-get-it)
    - [TL;DR (with images)](#Id-like-to-see-some-results)
    - [Sum up](#summing-up)
- [How to use it?](#how-to-use-it)
    - [Install dependency](#composer)
    - [Prepare content modules](#php)
    - [Configure section(s)](#craft-cms)
    - [Implement templates](#twig)
- [License](#license)

What is this?
-------------

[](#what-is-this)

### Tell me in two sentences…

[](#tell-me-in-two-sentences)

This library provides an easy way of **defining matrix blocks** for matrix fields that are used **for content modules**.

Its usage reduces the amount of clicks in Craft CP by moving the location of a matrix block's field definitions from CP to PHP code.

⬆️ [back to top](#contents)

### I still don't get it…

[](#i-still-dont-get-it)

Alright, let us build a scenario to explain what this lib is for.

#### Matrix blocks instead of richtext field (WYSIWYG)

[](#matrix-blocks-instead-of-richtext-field-wysiwyg)

Let's say you have a Craft 3 installation with **several sections**. There are singles like "Page" or channels like "Use case", "Service" and "Blog article".
Now, let's assume the entries of some of these sections **don't need a classical richtext field** (e.g. a Redactor field) because richtext is too unstructured. You as a programmer have no influence on where an editor adds headlines, lists etc.

Instead, the sections need some kind of structured content blocks. There is no richtext field, but a selection of "content things" you can add block-wise like "add a summary block here" or "add an image gallery there".
Each block has only those fields the block actually needs. A teaser-like content block has a headline, an image and a link target, for example.

That for the **sections get a matrix field** where each **matrix block represents a content block**. We prefer calling those content blocks **content modules**.

#### What's a content module?

[](#whats-a-content-module)

A content module is a **self-contained content unit** within an entry. It's a part of an entry's content, it can be:

- a *stage* module (consisting of some moody image, a big headline and a short summary)
- a *listing* module (like one that consists of nice icons and copy texts)
- a *quote* module (an inspirational quote next to the author's photo and name)
- a *call-to-action* module (some detailed instructions followed by a big button)
- a *newsletter-registration* module (a short form for registration)
- a *statistics* module (with numbers and charts and something interesting like that)
- … and so on … (ask your conceptual designer for more ideas)

#### How to achieve that in Craft CMS?

[](#how-to-achieve-that-in-craft-cms)

As already said, you'd create a matrix field for that in Craft CMS and create a matrix block for each content module. Then you'd add fields to all matrix blocks (a text field, an asset selection and a textarea to the one block for *stage* modules etc.).

Especially the click-heavy addition of fields to all matrix blocks can be a hassle in the CP if there are many content modules having many fields.
It's getting worse if you don't only need a single matrix field with block definitions for all available content modules but two or more matrix fields with shared and different block definitions (to control that different sections make use of different subsets of all available content modules … e.g. a "Blog article" needs *stage* and *quote* while "Use case" should not have *quote* available and "Service" also needs *listing*).

The more matrix fields you need and the more content modules you have the more complicated it gets to configure all that in the Craft CP.

#### And that's the point where this library comes in?

[](#and-thats-the-point-where-this-library-comes-in)

Exactly.

### I'd like to see some results…

[](#id-like-to-see-some-results)

When using this library you can make this:

[![Content modules when not using this lib](./docs/matrix-block-fields-then.png)](./docs/matrix-block-fields-then.png)

become this:

[![Content modules when using this lib](./docs/matrix-block-fields-now.png)](./docs/matrix-block-fields-now.png)

where the field type is something like this:

[![Custom field type for content module field](./docs/module-field-type.png)](./docs/module-field-type.png)

and the implementation of above selected custom field type looks like this (excerpt):

```
// …
return [
    new Text(\Craft::t('yourawesomeplugin', 'Headline'), 'headline'),
    new AssetsSelect(\Craft::t('yourawesomeplugin', 'Slideshow Images'), 'images'),
    new Textarea(\Craft::t('yourawesomeplugin', 'Teaser Text'), 'text'),
];
// …
```

Basically, that's it.

### Summing up

[](#summing-up)

Let us sum up the lib's benefits:

- **fields of matrix blocks are moved** from Craft's CP to PHP resulting in a **clear definition** of which matrix blocks have which subfields in your Craft plugin/module code → no (well, "no" … let's say: less) annoying clicking through the CP
- **every change** of a module's fields is recorded **in your VCS** (Git, Mercurial etc.) while being easier tracable than it would be in Craft's `project.yaml` (since that config file can grow really large)
- **less** (or at least easier resolvable) merge **conflicts** in the `project.yaml` since the matrix block fields are defined somewhere else (in your PHP code)

Furthermore, you can define:

- **custom validation rules** for standard field types → e.g. you could validate a text-field value by applying a `number` rule or your `myproject\validators\MyCustomValidator` which checks the input value's correct spelling, but only on full-moon nights or some crazy shit … it's completely in your hands (see [code samples](#php) below)

⬆️ [back to top](#contents)

How to use it?
--------------

[](#how-to-use-it)

### Composer

[](#composer)

First of all, to make this lib available in your Craft plugin¹ you need to add it to your dependencies:

```
composer require vierbeuter/craft-module-field-type dev-develop
```

¹ When mentioning "plugins" we're talking about both Craft plugins *and* modules. From now on we omit the word "module" to not accidentally mix it up with content modules (which are realized using matrix blocks).

⬆️ [back to top](#contents)

### PHP

[](#php)

#### Create content module classes

[](#create-content-module-classes)

Add a new folder to your `src/` directory to place all your content modules in. Name it `contentmodules/` or whatever you like to name it. Create PHP class files for each content module and save them into the new directory.

You should now have a directory structure similar to the following:

```
# ./ is your project root

plugins/your-awesome-plugin
└── src
    ├── YourAwesomePlugin.php
    ├── contentmodules
    │   ├── Conclusion.php
    │   ├── ImageGallery.php
    │   ├── Quote.php
    │   ├── Stage.php
    │   ├── Teaser.php
    |   └── …
    …
```

Implement your content modules as follows:

- `plugins/your-awesome-plugin/src/contentmodules/ImageGallery.php`

```