DEV Community: Piotr Pogorzelski

Breadcrumb created from URL for Craft CMS

Piotr Pogorzelski — Wed, 17 Jul 2019 17:23:25 +0000

This article was originally posted on craftsnippets.com, blog about Craft CMS. Head there for more Craft-related articles and ready to use template components.

Component overview

This template component can be dropped into any project - it works out of the box, without any modifications. Here are it's features summed up:

Component is styled using bulma classes.
It has google structured data attributes to improve your SEO.
It also has proper ARIA attributes. ARIA stands for Accessible Rich Internet Applications - it's standard which seeks to help people with disabilities navigate websites using tools like screen readers.
Breadcrumb will only show up if multiple links exist, since breadcrumb with just one link is not really useful.

Breadcrumb component itself:

{# v3 #}
{# http://craftsnippets.com/articles/breadcrumb-created-from-url-for-craft-cms #}

{# settings #}
{% set nonElementLinks = false %}

{# populate breadcrumbLinks array if no array of links was provided #}
{% if breadcrumbLinks is not defined %}
    {% set breadcrumbLinks = [] %}
    {# home #}
    {% set home = craft.app.getElements().getElementByUri('__home__', currentSite.id) %}
    {% set breadcrumbLinks = breadcrumbLinks|merge([{
        url: home.url ?? alias(currentSite.baseUrl),
        title: home.title ?? 'homepage'|t,
    }]) %}

    {# get elements #}
    {% set segments = craft.app.request.segments %}
    {% for segment in segments %}
            {% set uriPart = segments[0:loop.index]|join('/')|literal %}
            {% set element = craft.app.elements.getElementByUri(uriPart, currentSite.id) %}
            {% if element %}
                {% set breadcrumbLinks = breadcrumbLinks|merge([{
                    url: element.url,
                    title: element.title,
                }]) %}
            {% elseif nonElementLinks %}
                {% set breadcrumbLinks = breadcrumbLinks|merge([{
                    url: url(uriPart),
                    title: segment|t,
                }]) %}
            {% endif %}
    {% endfor %}
{% endif %}

{# render breadcrumb #}
{% if breadcrumbLinks|length > 1 %}
<nav class="breadcrumb" aria-label="{{'breadcrumbs'|t}}">
    <ul itemscope itemtype="http://schema.org/BreadcrumbList">
        {% for link in breadcrumbLinks %}
            <li class="{{loop.last ? 'is-active'}}" {{loop.last ? 'aria-current="page"' }} itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
                <a href="{{link.url}}" itemtype="http://schema.org/Thing" itemprop="item">
                    <span itemprop="name">{{ link.title }}</span>
                </a>
            </li>
        {% endfor %}
    </ul>
</nav>
{% endif %}

How does it work?

For each URL segment, element query using getElementByUri method is performed. This query uses URI parameter that is composed of this segment and all segments preceding it. If the query is successful, title of the returned object is used as specific breadcrumb link text value. getElementByUri will go through all elements that have URI attribute - entries, categories and even custom ones added by plugins.

First breadcrumb link is not represented by URL segment - it is homepage link. It is associated with entry with empty URI, queried by special slug __home__. title of that entry will be used as text value of link. If no such entry exists, string homepage passed through translation filter will be used instead.

Custom route links

If getElementByUri method returns nothing, it means that URL segment is not associated with entry, category or any other custom element page. Most likely it represents some custom URL route. In such a situation, you can do one of these things:

Set up an array of links yourself and pass it manually to the component as breadcrumbLinks - like this: {% include 'breadcrumb' with {breadcrumbLinks: breadcrumbLinks} %}. If component receives such array, it will not generate links itself but use these passed to it.
Set variable nonElementLinks at begining of the component to true. This will cause links not associated with elements pages to be appended to the breadcrumb. Their text values will be taken from URL segment and passed trough |t filter so you can set them up in static translations.

Breadcrumb with Seomatic

If you are already using Seomatic on your website, you can use it's built-in functionality to get data required to render links. Here's breadcrumb component adjusted for Seomatic:

{% set breadcrumbLinks = seomatic.jsonLd.get('breadcrumbList').itemListElement %}
{% if breadcrumbLinks|length > 1 %}
<nav class="breadcrumb" aria-label="{{'breadcrumbs'|t}}">
    <ul>
        {% for link in breadcrumbLinks %}
            <li class="{{loop.last ? 'is-active'}}" {{loop.last ? 'aria-current="page"'}}>
                <a href="{{ link.item['@id'] }}">
                    <span itemprop="name">{{ link.item['name'] }}</span>
                </a>
            </li>
        {% endfor %}
    </ul>
</nav>
{% endif %}

Note that this version of breadcrumb is stripped of it's structured data attributes - Seomatic renders proper JSON-LD code for breadcrumb which does the same job.

Seomatic breadcrumb also doesn't include links not related to element pages. To learn how to add them to breadcrumb, head to Seomatic docs and look for "To entirely replace the existing BreadcrumbList on a page".

Why is such breacrumb component useful?

Craft CMS allows us to build websites with URLs consisting of multiple segments. If your website has many types of categories and sections, your URL logic can get quite complicated. For example, let's consider such URL for article page:

category-list/1-level-category/2-level-category/article-page

Here are URL settings of various sections and categories needed to achieve such URL structure:

Article page section needs to have categoryField category field and such url setings: {categoryField.last.uri}/{slug}.
Categories have multiple levels, so for category group, URL settings would be: {parent.uri ?? craft.entries.section('category_list').one.uri}/{slug}.
Category list is single type section, so it only needs hardcoded entry title: category-list.

As you can see, these URL settings use element queries and conditional operators. We could reproduce all this logic within breadcrumb component in Twig. But we don't need to. Remember - Don't Repeat Yourself.

Breadcrumb plugin

As an alternative to breadcrumb template component described in this article, you can use Breadcrumb plugin. It works pretty much the same while featuring few useful configuration options, like:

customising title of first breadcrumb link directing to homepage.
Setting maximum amount of breadcrumb links
Skipping specific segments

Just like with all plugins - before installing it consider if you really need it. Keep in mind that each plugin adds additional level of complexity to your website.

Article update history

1 july 2019 - breadcrumb homepage link is now created from homepage url or currentSite.baseUrl passed through alias function - to take into account situation when site base url is set to @web.

Best developer-oriented Craft CMS plugins

Piotr Pogorzelski — Mon, 15 Jul 2019 09:00:06 +0000

This article was originally posted on craftsnippets.com. Head there for more Craft-related articles and ready to use template components.

These plugins don't add any new features to a website. Their focus is to just make developer life easier and development process more productive. After website goes into production, I usually just disable or uninstall them to reduce number of plugins that need regular updating.

CP field inspect
My personal favorite. CP field inspects links fields instances in entries, categories, globals to their settings pages. This plugin has probably saved me a few hours of clicking through control panel already.

Template comments
This plugin adds HTML comments to rendered HTML in places where {% block %} and {% include %} tags are used. These comments make rendered HTML source code more readable.

Twig profiler
Twig profiler allows you to check how long specific fragments of templates take to execute and render. After enclosing parts of the template in profile tag with a unique keyword, you will find them in Yii profiler graph.

Command palette
This plugin allows you to navigate through the control panel with just a few keystrokes. It introduces command palette, a tool based on similar functionality used in IDEs and code editors.

Inventory
Inventory provides a better alternative to standard fields list available in the settings section of the control panel. This plugin shows where specific fields are used - or if they are not used at all.

Field manager
Another alternative to standard fields list. It doesn't however show where fields are used, just if they are "orphaned" - not used at all. Field manager also allows cloning, exporting and importing fields.

Kint
Kint is debugging helper for PHP applications. It allows you to analyze your variables in widget appended to website or even browser console. This plugin lets you use Kint in Craft CMS templates.

Queue manager
This plugin makes debugging stuck queue tasks easier. It displays detailed queue job information and allows retrying or canceling the whole queue.

Seeder
Seeder generates entries filled with random data. Great for testing how templates behave when filled with various content.

CP Clear Cache
Adds "clear cache" button to main control panel menu. One click less.

Environment label
Have you ever mistaken environments and did something bad to the website in production? This won't happen again. This plugin adds big red environment label to control panel that will show up (or not) depending on environment website is in - so production and development or staging instances of the same website are clearly distinguished.

Element map
This plugin creates a list of links to elements that have a relationship with currently viewed element in control panel - like entry, category or asset.

Logs
This simple plugin lets you browse through Craft logs using the control panel. Useful for quickly checking out what's going on with website on the remote server.

Anchor links with smooth scrolling

Piotr Pogorzelski — Fri, 12 Jul 2019 20:35:21 +0000

CSS solution

Anchor links bring us to sections of a page they link to instantaneously. We can replace this "teleportation" with smooth scrolling animation, using single CSS property:

html {
  scroll-behavior: smooth;
}

Unfortunately this does not work on Safari. Truly, safari is a new IE6.

Javascript solution

Fortunately, we can achieve a smooth scrolling effect with a bit of jQuery code.

The snippet below simulates smooth anchor clicking with all its aspects. Thanks to use of history API, back and forward browser buttons work. If user starts scrolling while the animation is still running, it stops to avoid "fighting" with animation movement.

  $('a[href^="#"]').on('click', function(event) {
    var hash = '#' + $(this).attr('href').split('#')[1]
    var element = $(hash)
    if (element.length) {
      event.preventDefault();
      history.pushState(hash, undefined, hash)
      $('html, body').animate({scrollTop: element.offset().top}, 500)
    }
  });   

  window.addEventListener('popstate', function(e) {
    if(e.state && e.state.startsWith('#') && $(e.state).length){
      $('html, body').animate({scrollTop: $(e.state).offset().top}, 500)
    }
  });

  $('html, body').on("scroll mousedown wheel DOMMouseScroll mousewheel keyup touchmove", function(){
    $('html, body').stop();
  });

Testing emails sent by Craft CMS using Mailtrap

Piotr Pogorzelski — Fri, 12 Jul 2019 19:45:47 +0000

This article was originally posted on craftsnippets.com. Head there for more Craft-related articles and ready to use template components.

About mailtrap

Mailtrap is fake SMTP server that can be used to test and debug all emails sent by your website. No matter what recipient address is, Mailtrap server doesn't actually send anything - it just stores all messages to be later reviewed and analyzed.

Using Craft CMS application configuration file we can overwrite default mailer adapter that uses local Sendmail program and connect to external SMTP server like Mailtrap.

Obtaining Mailtrap credentials

First, you need to get your Mailtrap credentials that will be used to connect to server.

Register on Mailtrap website and log in. You will see a list of your inboxes - right now there is only one. Click on gear icon on the right and copy credentials from "SMTP settings" tab.

Detailed instructions with screenshots are available in this post on mailtrap blog.

Overwriting default mailer adapter

Craft CMS provides three mailer adapters:

Sendmail - it uses server sendmail functionality. It's default adapter.
SMTP - can be used to connect to an external SMTP server.
Gmail - can be used to connect to Gmail server.

There are also plugins that add their own adapters like Mailgun. To connect to Mailtrap, we will need to switch Sendmail mailer adapter to SMTP one.

First, let's define our credentials in .env file. That's where you should keep all your passwords and sensitive data.

SMTP_HOST=smtp.mailtrap.io
SMTP_PORT=2525
SMTP_USERNAME=your_username
SMTP_PASSWORD=your_password

Don't forget to change username and password to these obtained from mailtrap.

Now, open config/app.php file. If you didn't modified it earlier, it should contain link to example module - it can be safely removed.

Your mailer configuration should look like this:

<?php
return [
    'components' => [
        'mailer' => function() {
            $settings = \craft\helpers\App::mailSettings();
            $settings->transportType = \craft\mail\transportadapters\Smtp::class;
            $settings->transportSettings = [
                'useAuthentication' => true,
                'host' => getenv('SMTP_HOST'),
                'port' => getenv('SMTP_PORT'),
                'username' => getenv('SMTP_USERNAME'),
                'password' => getenv('SMTP_PASSWORD'),
            ];
            $config = \craft\helpers\App::mailerConfig($settings);
            return Craft::createObject($config);
        },
    ],
];

As you can see, we overwrote mailer component of Craft CMS app.

Now, every email sent by Craft CMS will be redirected to Mailtrap. It also accounts for emails sent by plugins. You can quickly test if everything works properly by using "forgot password" functionality.

Once you check your Mailtrap inbox you can start inspecting your emails. You can view their preview, HTML code, raw data, analyze them for potential problems. Just keep count of how many emails you send - free Mailtrap account has a monthly limit of 500 messages, but for a few bucks you can significantly raise that number.

Universal language switcher for Craft CMS

Piotr Pogorzelski — Fri, 12 Jul 2019 18:51:49 +0000

This post is part of my Craft CMS template components library. For more, you can visit craftsnippets.com

Overview

This article assumes you have a basic understanding of Craft CMS multisite functionality. To learn about it, head to documentation.

Now, let's sum up how language switcher works.

Language switcher will display links to alternative versions of the content on the website - links to other sites. Only links to sites belonging to same site group as the current site will be displayed.
If a site has "This site has its own base URL" option disabled, it will not appear in language switcher.
If you are on the page associated with element - entry, category, commerce product - language switcher will display links to other versions of this element (belonging to other sites). It will work even for elements added by plugins, assuming they have their own URL.
While looping through sites, language switcher performs few checks before outputting proper link. If the current element does not have an alternative version (it does not propagate across sites or is not enabled for specific site) or current page is not associated to any element (because it is accessed by custom route or template routing), language switcher link will direct to base URL of another site.
If current site is the only site in its site group, language switcher will not be displayed. No need for language switcher if there is nothing to switch to.
Each language switcher link consists of language name in its native form (for english "english", for german "deutsche" etc.) and country flag. Thanks to flag icon CSS library, a country flag can be appended to language link automatically.
Language switcher has proper ARIA tags that make it accessible - aria-role and aria-label. Aria label text can be provided by static translations.
Each language switcher link has hreflang parameter that lets google crawler recognize the multilingual structure of your website.
Language switcher link representing currently viewed site has is-active CSS class.

Language switcher - twig code

This language switcher works out of the box. Just include it in the proper place.

{# v2 #}
{# http://craftsnippets.com/articles/universal-language-switcher-for-craft-cms #}

{# logic #}
{% set currentElement = craft.app.urlManager.matchedElement %}
{% set sites = craft.app.getSites().getGroupById(currentSite.groupId).getSites() %}
{% set switcherLinks = [] %}

{% for site in sites if site.baseUrl is not empty %}

    {% set title = craft.app.i18n.getLocaleById(site.language).nativeName %}
    {% set url = site.getBaseUrl() %}
    {% if currentElement %}
        {% set otherLocaleElement = craft.app.getElements().getElementById(currentElement.id, currentElement.className(), site.id) %}
        {% if otherLocaleElement and otherLocaleElement.enabledForSite %}
            {% set url = otherLocaleElement.url %}
        {% endif %}
    {% endif %}

    {% set switcherLinks = switcherLinks|merge([{
        url: url, 
        title: title, 
        countryCode: site.language|split('-')|last,
        current: site.id == currentSite.id ? true : false,
        language: site.language,
    }]) %}

{% endfor %}

{# outputting html #}
{% if switcherLinks|length > 1 %}
<nav aria-label="{{'Switch language'|t}}" aria-role="navigation">
<ul>
{% for switcherLink in switcherLinks %}
    <li class="{{switcherLink.current ? 'is-active'}}">
        <a href="{{switcherLink.url}}" hreflang="{{switcherLink.language}}" lang="{{switcherLink.language}}">
        <span>{{ switcherLink.title }}</span>
        <span class="flag-icon flag-icon-{{switcherLink.countryCode}}"></span>
        </a>
    </li>
{% endfor %}
</ul>
</nav>
{% endif %}

How does it work?

Let's dive into Twig code and analyze how language switcher works. Understanding its structure will allow you to easily modify it to your needs.

First, we get element associated with currently viewed page using craft.app.urlManager.matchedElement. If not such element exists, matchedElement returns false.

Then, we loop through sites that are in the same group as a currently viewed site. if site.baseUrl is not empty ensures that sites with no public URLs are omitted.

Each site has its locale code - represented by site.language variable. For example, a site set to American locale has en-US. The first part represents language, second part represent a country. We need to extract country code from locale code to use it in CSS class of element containing country flag.

Using craft.app.i18n.getLocaleById we get locale data of specific site. We need it to display locale name in human readable form, in its native spelling.

Now, its time to get URL of link. First, we first set url variable to base URL of site within current for loop. If page is associated to element, we then overwrite url value to URL of alternative version of this element, using craft.app.getElements().getElementById.

Finally, we append all data related to the link to switcherLinks array. After looping through sites, we can loop through links and output them as HTML.

Customizing language switcher

Here are a few ideas for modifying default language switcher.

If language descriptions like "English (United states)" are too explict to you, you can display only "language" part of locale name by extracting language code from locale code:

{% set languageCode = site.language|split('-')|first %}
{% set title = craft.app.i18n.getLocaleById(languageCode).nativeName %}

You can also display country code next to its name in native language, for example: "English (EN)". It's good alternative to displaying flags:

{% set languageCode = site.language|split('-')|first %}
{% set nativeName = craft.app.i18n.getLocaleById(languageCode).nativeName %}
{% set title = nativeName ~ '(' ~ languageCode ~ ')' %}

If you don't wish to display link to currently browsed site in language switcher, you can exclude it:

{% set sites = craft.app.getSites().getGroupById(currentSite.groupId).getSites()|without(currentSite) %}

Country flags

In order to display country flags in language switcher links, you need to:

Include Flag icons CSS library in your project.
Make sure that each site locale has locale code consisting of country code and language code. So - instead of just "en", use "en-US". Country code is needed for setting proper CSS class of element with flag.

But should you really use flags for your language switcher? Well, it depends.

Some countries have multiple official languages. For example, Canada official languages are both english and french. If you display just Canadian flag, it will tell nothing about the actual language used by this version of the site.

There are also multiple countries that use the same language - like USA, UK and Australia using english, or multiple counties that use portugalese. Is your content just translated to a specific language, or tailored to a specific country?

Each multilingual site requires thinking it all through. I recommend reading THIS article on United Language Group website to expand your knowledge on this subject.

Lang attribute

Besides having proper language switcher, it's important to properly set lang attributes on your website. This attribute specifies the language of content and should be always specified in <html> element. You can do this in Craft like this:

<html lang="{{ currentSite.language }}">

Setting proper lang attribute will tell screen readers how they should pronounce the text. It can also affect text rendering in case of some fonts. It however does not tell Google about the language of your website.

If you have some content in a different language from rest of website, you can set lang attribute to element containing this content. That's why each language switcher link that contains language name in its native spelling has proper lang attribute.

Site switcher plugin

Site switcher plugin can take care of outputting URLs of alternative versions of the current element. The same thing however can be achieved purely in Twig - like in language switcher described in this article.

Therefore, I don't see the reason to use this plugin.

DEV Community: Piotr Pogorzelski

Breadcrumb created from URL for Craft CMS

Component overview

How does it work?

Custom route links

Breadcrumb with Seomatic

Why is such breacrumb component useful?

Breadcrumb plugin

Article update history

Best developer-oriented Craft CMS plugins

Anchor links with smooth scrolling

CSS solution

Javascript solution

Testing emails sent by Craft CMS using Mailtrap

About mailtrap

Obtaining Mailtrap credentials

Overwriting default mailer adapter

Further reading

Universal language switcher for Craft CMS

Overview

Language switcher - twig code

How does it work?

Customizing language switcher

Country flags

Lang attribute

Site switcher plugin

Further reading