KnockoutJS: Custom Binding Documentation

[astorm]

Magento 2's KnockoutJs implementation includes a number of "custom bindings". There are 12 in the 2.0.x branch.

    './bind/scope',
    './bind/staticChecked',
    './bind/datepicker',
    './bind/outer_click',
    './bind/keyboard',
    './bind/optgroup',
    './bind/fadeVisible',
    './bind/mage-init',
    './bind/after-render',
    './bind/i18n',
    './bind/collapsible',
    './bind/autoselect',

Documenting what each of these does would be extremely valuable to javascript and theme developers working in the Magento 2 system.

[almarchenko]

Hi @astorm, thank you for the feedback!
I created an internal issue for this MAGETWO-54468, but it will take at least couple of weeks, because there are other issues in backlog.

[tanberry]

Hi @astorm, we have a "chapter" about the custom bindings planned for the new UI Components guide. @almarchenko is continuing the Doc Sprint work on this guide, with the core developers... below is a screenshot of the outline for the bindings we want to document:

We plan to post the outline for the entire book; feedback welcome.

[astorm]

Looks like a good start for covering the components.

Although "in 2.1 make sure they use our new templates" is a little confusing. It's not clear what templates they're talking about -- the .html files loaded over HTTP? Or something more? (Regardless, as a side note, documentation of how those .html templates work and where that syntax comes from would be useful)

Also -- the xhtml template mentions are a little confusing here as well. It's my understanding that the xhtml templates are used specifically with UI components (not generic Knockout), and are used to output the initial bit of HTML + Javascript that kicks off registering KnockoutJS view models. Are these the XHTML templates that are referenced above, or are these something else?

So, the plans for components looks solid, but the context those components sits in is a little fuzzy.

Hope that helps!

[tanberry]

Thanks @astorm for the feedback. As part of a concerted effort we did a Doc Sprint with the core devs... and as the very first step we defined a comprehensive outline of everything that should be documented about UI Components. Above I meant to post just the section on the custom bindings, but the screen capture also shows some topics above the bindings (in orange) that we know we need to cover. (So they are defined in the Outline, but not yet written.)

I should state that the outline is a raw capture of the topics and types of content that we decided we needed to document, and doesn't reflect finished titles so much as the "what" we need to doc. And some were entered very quickly in an errrr... dynamic setting where 5 or 6 people were collaborating on what exactly needed to be covered. Both the mention of the "new templates" and the use of xhtml for the Form and Grid UI components will be covered as we continue the Doc Sprint work with the core devs. I wish it could go faster, but DevDoc is very grateful that we are getting this support from the devs who actually created UI Comps! ;-) Developers writing Docs is a beautiful thing.

We have it in the queue to publish the entire Outline; it wold be great if you would provide further feedback, and see if there are any gaps in our plan. ;-)

[almarchenko]

Internal issue MAGETWO-55289

[almarchenko]

@astorm It happened)
We published the description of Magento custom Knockout.js bindings.
http://devdocs.magento.com/guides/v2.1/ui_comp_guide/concepts/knockout-bindings.html

Thank you for creating the request!
I'm closing the issue if you do not have additional comments.

[astorm]

Whaaaaaaaaaaat? Yay!

[andreicostin]

@almarchenko Thanks a lot for adding the documentation for these custom bindings. Would it be possible to add documentation on how to properly add our own custom bindings without touching Magento's core?