How to Use UnderscoreJS as a Templating Engine

Underscore JS is a compact, yet wonderful JS library that “provides a whole mess of useful functional programming helpers without extending any built-in objects“. The best part is, Underscore JS comes out-of-the-box, with Magento 2.x. In this tutorial, we’re going to see how we can use Underscore JS as a templating engine, within Magento 2.

It is advisable to understand what jQuery widgets are and how to instantiate widgets the Magento way first before continuing with this tutorial.

Task

Display products in a template being fetched dynamically, using AJAX.

Solution

Define our block file

<?php
/**
 *
 * @package     magento2
 * @author      Codilar Technologies
 * @license     https://opensource.org/licenses/OSL-3.0 Open Software License v. 3.0 (OSL-3.0)
 * @link        https://www.codilar.com/
 */

namespace Codilar\HelloWorld\Block;

class Underscore extends Template
{
    /**
     * @return string
     */
    public function getUnderscoreTemplate() {
        return "Codilar_HelloWorld/template/underscore.html";
    }
}

In our template file, define our widget

<?php
/* @var \Codilar\BoughtBefore\Block\Underscore $block */
?>
<div class="template_container"></div>

<script type="text/x-magento-init">
    {
        ".template_container" : {
            "myProductWidget" : {
                "template" : "<?= $block->getUnderscoreTemplate() ?>"
            }
        }
    }
</script>

Next, we define our JS file in the requirejs-config

var config = {
    map: {
        '*': {
            'myProductWidget':  'Codilar_HelloWorld/js/widget'
        }
    }
};

And finally, we define our JS file containing the widget

require([
    'jquery',
    'underscore',
    'mage/url'
], function ($, _, urlBuilder) {
    var widget = {
        /* default values. Can be overridden when initializing the widget */
        options: {
            template: ""
        },
        _create: function () {
            this._initTemplate();
        },
        _initTemplate: function () {
            require("text!"+this.options.template, function (template) {
                this.showProducts(_.template(template));
            }.bind(this));
        },
        showProducts: function (template) {
            var self = this;
            $.ajax({
                url: urlBuilder.build("underscore/products/get"),
                method: "GET",
                success: function (products) {
                    self.element.html(template(products));
                }
            });}
    };

    return $.widget('codilar.myProductWidget', widget);
});

And then in our app/code/codilar/HelloWorld/view/frontend/web/template/underscore.html file, we write the actual underscore template

<% if (products.length > 0 ) { %>
    <% products.forEach (function (product) { %>
        <a href="<%= product.url %>"><%= product.name %></a>
    <% }); %>
<% } %>

For documentation on how to build Underscore templates, check this link out

NOTE: The app/code/Codilar/HelloWorld/Controller/Products/Get.php controller must be created on your own for this tutorial to work. Do have a look at the Hello World module to understand how to make routes and Controllers.

Well that’s all. Thank’s a lot for sticking through. Do let us know in the comment section below about what you want our next Magento tutorial blog to be about.

Previous Tutorials

What is x-magento-init?

What is KnockoutJS and how is it relevant in Magento 2?