KnockoutJS Template Customizations Need Documentation

[astorm]

Magento 2 has made a number of customizations to the KnockoutJS framework that make it behave in ways that are different from standard KnockoutJS. These include (but are not limited to)

1. Modifying the template system so it loads KnockoutJS templates from a URL (vs. the standard behavior of loading them from the page source)
2. Parsing those templates for extra nodes and tags and attributes that are not a part of standard KnockoutJS

The end result is Magento 2 KnockoutJS template have custom tags and attributes whose behavior is completely undocumented. This makes it difficult for a third party developer to understand what the core system is doing, which makes difficult for a third party developer to follow along with the de-facto best practices in the Magento core modules.

For example, if you download the collection.html KnockoutJS template (an important template in Magento's UI Components), you end up with the following

<each args="data: elems, as: 'element'">
    <render if="hasTemplate()"/>
</each>

There are no <each/> or <render/> tags in HTML. KnockoutJS does not have an <each/> or <render/> tag. These tags are custom functionality Magento have built on top of KnockoutJS's template system. The above template corresponds (roughly? I'm barely keeping up here myself ;) ) to the following standard KnockoutJS

<!-- ko foreach: {data: elems, as: 'element'} -->
    <!-- ko if: hasTemplate() --><!-- ko template: getTemplate() --><!-- /ko --><!-- /ko -->
<!-- /ko -->

At minimum, the dev docs team should

1. Document each custom tag/node (<each/>, <render/>, etc.)
2. Document each custom attribute (args,if, etc.)
3. Explain how Magento's custom KnockoutJS template engine transforms the above into standard KnockoutJS code

I don't have the above information (which is why I'm asking for it), so this will probably require an SME.

[almarchenko]

Hi @astorm, thank you for pointing out.
I've created the internal issue MAGETWO-55538 in our SMEs's backlog, and it will be one of our priorities.

[astorm]

I dropped by to open a ticket on the UI Component template syntax needing documentation, only to discover I thought the same thing back in July.

Any update on this @almarchenko ? Or is this something that's not going to get done and I should close the ticket?

[astorm]

Also, possibly relevant and of interest if this is something that will happen: http://magento-quickies.alanstorm.com/post/154733424095/design-problems-with-magentos-knockoutjs

[almarchenko]

@astorm
It's a pity, but currently, developers cannot give me any forecasts about when it can be done.