Display a Knockout.js template from a UI Component

Special note

This video goes over how to set the template from a UI Component. There is an alternate method to this! Later in the course, you will learn how to set the template directly with JavaScript from a Knockout.js view model's "defaults" property.

Setting the template with JavaScript is easier, as it involves just setting a template property and a string value. That said, it's not as extensible.

Like everything else in Magento, there is a fallback hierarchy that executes to determine the setting of UI Component & Knockout view model property values. JavaScript has the highest level of precedence, meaning that it overrides other values potentially set with XML.

This means that you should strive for setting configuration & defaults properties with XML if possible, as it makes your code more extensible. Other third-party modules can then easily override the property with XML, and if they need an even higher level of precedence, that can override it with JavaScript.

If your code is 100% local and not intended to be redistributed, setting the property value with JavaScript is a lot simpler and probably preferred.

In our module’s visual mockup, the first block we need to create is a SKU Lookup block. This will be a text input field with a “Confirm SKU” button. Clicking that button will call the Magento API to confirm that the SKU exists and return the product name.

Building the SKU Lookup Block

To build the SKU Lookup block, let’s create a new <div> with an ID of “sku-lookup” within the “shipping-plan” <div> in the shipping-plan.phtml file. Inside this <div>, create a Knockout virtual element with a type of “template” and the value will be a getTemplate() function call. Close up these tags, as well as the closing Knockout tag. After saving this file, the getTemplate() will return null because the “template” property doesn’t yet exist on the UI Component.

Creating the Template Property

To create the “template” property, open up the layout XML file. Within the “sku-lookup” item, create another <item> node with the name of “config”, which will have the “xsi:type” of “array”. Inside the <config> array, create a new <item> node with the name of “template”. When the call to getTemplate() executes, this is the value that will be returned. This will have an “xsi:type” of “string”, and the value for this template will be a custom Magento string.

The custom Magento string consists of the vendor name and module name, followed by a slash and the name of the Knockout template file without any extension. In this case, the vendor and module name is “Macademy_InventoryFulfillment”, and the Knockout template file’s name is “sku-lookup”. The value after the slash is relative to the frontend/web/template directory.

Creating the Knockout Template File

Create a file named template/sku-lookup.html. Note that Knockout templates go in a “template” folder and not a “templates” folder, which stores .phtml files. For the contents of this file, create a new <h2> tag and name it “sku-lookup”. Save the file and then go back to the /inventory-fulfillment route & refresh. You should see the “SKU Lookup” header.

Loading the Knockout Template and View Model

The .phtml file kicks off loading the Knockout template, and the Knockout view model is also executed. You can now code everything in JavaScript and HTML.

Managing IDs and Classes

It’s important to note that the “id” attribute should be placed in the .phtml file and not the Knockout template because there can only be one DOM element with a unique “id”. If the “id” is within the Knockout template, then it’s intended to be loaded only once. However, Knockout templates can be loaded many times if desired. This approach allows for multiple copies of the same template to be used on one page with unique “id”s.

It’s also a good idea to wrap Knockout templates in a container element. In this case, wrap the template within a <div> with a “class” of “sku-lookup”. You can have many elements of the same class loaded on the same page, allowing you to target this specific class with CSS or custom JavaScript. This approach of having classes within Knockout templates and “id”s within .phtml files allows for extensibility to either target a specific “id” or a specific “class” if needed.