Error when instantiating WinJS.UI.ListView with template from code

In the process of creating a custom WinJS control which contains a WinJS.UI.ListView, I was attempting to allow a user to pass a selector for the template.

However, no matter if I have the template "pre-created" in the HTML page like you would expect:

<div data-win-control="WinJS.Binding.Template"> <!-- ... --> </div>

Nor if I query for the element and create the template from code like:

var template = new WinJS.Binding.Template(document.querySelector(selector));

When I get to instantiating the ListView and pass in the template element itself (or its winControl property) to the ListView's itemTemplate option, as such:

new WinJS.UI.ListView(elem,  { itemTemplate: template.winControl });

I receive the following error:

Exception is about to be caught by JavaScript library code at line 11562, column 21 in ms-appx://microsoft.winjs.2.0/js/base.js

0x800a01b6 - JavaScript runtime error: Object doesn't support property or method '_renderItemImpl'

I attempted to trace it back a bit but am getting lost in base.js. Hoping someone else has run into this.

Note: I've included my workaround as an answer.

Solution

The only workaround I've been able to get to work is to instantiate the template in code, then pass a function to the itemTemplate option when instantiating the ListView. The documentation on what is expected here is sparse, but all of the demos where the ListView is instantiated via code use a templating function so I presume this is the only way to achieve this sadly.

new WinJS.UI.ListView(elem,  {
    itemTemplate: function (promise) {
        return promise.then(function (item) {
            return resultsTemplate.render(item.data);
        });
    }
});