Describe BEMTREE #594 changes in documentation

[apsavin]

We need to describe BEMTREE #594 changes in documentation (PR #644). It breaks backward compatibility, so we absolutely need to add this changes into CHANGELOG.md.

[veged]

could you please summarise changes here so our documentation gurus can find them all in one place (right now only people who strong involved in process can understand what was changed)

[apsavin]

Problem: there was no way to handle errors into BEMTREE, because BEMTREE ignored errors. In order ot fix that, we decided to:

1. Improve BEMContext#doAsync function to provide convinient way to handle errors on blocks level. Before: this.doAsync(...).then(...); After: this.doAsync(..., onSuccess) If you want to handle errors on block level: this.doAsync(..., onSuccess, onError); You can define context of onSuccess and onError either: this.doAsync(..., onSuccess, onError, context); By default, context===this //true If you have some function that you use to do async stuff and that function returns promise, then instead of this.doAsync(function(){return doRequest()}, onSuccess, onError); you can write now something like this: this.doAsync(doRequest(), onSuccess, onError);
2. I think, that we should force users to handle errrors clearly, but other developers decided that we should provide possibility to ignore errors by default for backward compatability. So we have a bit weird interface of BEMTREE now. Before: BEMTREE.apply(...).then(function(bemjson){BEMHTML.apply(bemjson);}); After: A. if you have strange wish to ignore error by default (like BEMTREE behaves now): BEMTREE.apply(...).then(function(returnedValue){BEMHTML.apply(returnedValue[0]);}); B. If you want to handle errors, then things becomes more complex for you and you need to write something like this: BEMTREE.apply(...).then(function(returnedValue){return Vow.all(returnedValue[1]).then(function(){return returnedValue[0]});}).then(function(bemjson){BEMHTML.apply(bemjson);}, function(){//handle errors here});

[veged]

@tadatuta is it relevant since new bem-xjst?

[apsavin]

@veged I hope that we will have only one - sync - version of bemtree. If so, it's not relevant.

[qfox]

Let's close then?

[apsavin]

@narqo I think we should reopen this or close https://github.com/bem/bem-xjst/issues/155

[narqo]

I'm not sure about it. There won't be anything related to xjst base templates in bem-core 3.0.0+ (see #1288). And I don't see any particular reason to do anything about it here.

[apsavin]

Mmm, ok.