experience/meld

Easily combine arrays of strings within your Craft CMS Twig templates.

Meld

Meld is a Craft plugin. It eases the process of adding a prefix or a suffix to an array of strings within your Twig templates., _(*1)

That's pretty useful, but Meld goes further. It allows you to combine an array of prefixes with an array of suffixes., _(*2)

Let's take a look at a quick example:, _(*3)

{% set prefixes = ['Hello', ['Hola', 'Adios']] %}
{% set suffixes = ['World', ['Tierra', 'Amigo']] %}
{% set melded = prefixes|meld(suffixes) %}

<ul>
    {% for meld in melded %}
        <li>{{ meld }}</li>
    {% endfor %}
</ul>

// Result:
<ul>
    <li>HelloTierra</li>
    <li>HelloAmigo</li>
    <li>HolaWorld</li>
    <li>AdiosWorld</li>
    <li>HolaTierra</li>
    <li>HolaAmigo</li>
    <li>AdiosTierra</li>
    <li>AdiosAmigo</li>
</ul>

How it works

You can throw pretty much anything at Meld, and it will do its best to make sense of the madness., _(*4)

If either the prefix or the suffix is an array, Meld returns an array of results. Otherwise, Meld returns a single string., _(*5)

Meld will do its best to coerce each prefix and suffix into a string (assuming it isn't already). In practical terms, this means:, _(*6)

• Integers are converted to their string equivalent;
• Floats are converted to their string equivalent;
• Booleans are converted to "1" (true) or "0" (false);
• Objects which implement the __toString method are converted to their string representation;
• Everything else is converted to an empty string.

It's worth noting that even if the prefix or suffix is an empty string, Meld will still include it in the results. If you don't want this to happen, sanitise your prefixes and suffixes before passing them to Meld. Rubbish in, rubbish out., _(*7)

Requirements

Each release of Meld is automatically tested against PHP 7.1 and above. It is also manually tested on the most recent version of Craft., _(*8)

PHP 7.0 support

In theory, Meld should be compatible with PHP 7.0. In practise, it's impossible to test this., _(*9)

We use Codeception for testing (as is the Yii way), and the Codeception dependency tree includes components which only work with PHP 7.1+., _(*10)

Unfortunately there's nothing we can do about that., _(*11)

Installation

To install Meld, either search for "Meld" in the Craft Plugin Store, or add it as a Composer dependency., _(*12)

Here's how to install Meld using Composer., _(*13)

1. Open your terminal, and navigate to your Craft project:, _(*14)

   cd /path/to/project

2. Add Meld as a project dependency:, _(*15)

   composer require experience/meld

3. In the Control Panel, go to "Settings → Plugins", and click the "Install" button for Meld, _(*16)

Usage

Meld can cope with a wide variety of prefixes and suffixes, from basic strings, all the way up to arrays of objects. Refer to the "How it works" section, above, for additional information., _(*17)

Use the Meld filter in exactly the same way as any other Twig filter, with the prefix to the left of the pipe, and the suffix as the filter argument., _(*18)

For example:, _(*19)

{# Outputs a single string. #}
{{ 'Hello'|meld('World') }}

{# Returns an array of strings. #}
{% set prefixes = ['Hello', ['Hola', 'Adios']] %}
{% set suffixes = ['World', ['Tierra', 'Amigo']] %}
{% set melded = prefixes|meld(suffixes) %}