AtomPromise is little different then regular JavaScript promises, and it is made different to fit in the binding framework correctly.
By definition, promise is asynchronous, however it looks like items property is assigned to json retrieved from url. Yes we made it look like it, so that its easy to program, however we are not assigning items yet, we are only assigning promise (AtomPromise). Atoms.js property system recognizes value of type AtomPromise and it queues the assignment from the promise result until the result is retrived by the promise.
In traditional JavaScripts, wiring up promises are so difficult and it leads to very ugly code, in order to make everything looks very simple, we have redesigned the whole property system to incorporate asynchronous assignments via promises.
It is easy to create your own custom AtomPromise, where you can easily wire asynchronous functionality that fits into Atoms.js easily.
In case of failure of promise, simple alert is displayed, and you can control by calling showError method on promise.
AtomPromise.json expects URL as input and it returns an AJAX Promise which enables busy dialog while in progress and also displays an error if it fails. Next parameter q is an object literal that will be encoded as query string that must be passed to source URL. Options object is simply forwarded to jQuery.ajax method.
So, Page.php?a=1&b=2 should be passed as AtomPromise.json( 'Page.php' , { a: 1, b: 2 } ), this helps in proper encoding and it is readable. And individual values are bindable, so instead of 1 and 2, we could have any scope parameters bound here.
By default, HTTP POST are encoded as formModel=JSON in HTML form encoded way to support previous ASP.NET Web Server. And on server side, you could use Request.Form["formModel"] to retrieve JSON equivalent, and you can then deserialize JSON into Dictionary in .NET.
This is done to preserve the null and empty values of string. Sending Form Key=Value pairs does not send hierarchical data and it does not send empty string values correctly.
To have your own serialization method, in case of PHP or any other framework, you have to use following different code snippets.
<script type="text/javascript">
AtomConfig.ajax.jsonPostEncode = function (data, options){
options.contentType = 'application/x-www-form-urlencoded';
return { formModel: JSON.stringify(data) };
};
</script>
<script type="text/javascript">
AtomConfig.ajax.jsonPostEncode = function (data, options){
options.contentType = 'application/json';
return JSON.stringify(data);
};
</script>
This returns a promise with simple HTTP Get operation, the return value is a string.
In case if you want to send a custom ajax with your own headers, you can use this method. But we recommend using json and get methods as they can do everything needed. However the inbuilt post functionality of Forms and Buttons are wired through json/get methods. They internally call this method as well. You can use this for debugging.
Most likely, we retrieve a list of items and we want to display them in a drop down menu, but we do not have any selection yet. Or we want to display an unselected or empty item in the list, which may not exist in the database. For this situation, insertItem comes handy, it inserts an empty item in the array retrieved after the ajax operation. This method only works with json method and arrayPath designates path of an array inside the result. If result itself is an array, you can omit arrayPath.
Data Controls such as AtomItemsControl allows refreshing of items by setting action set as control itself. However, in case of one time binding, promises will not be persisted. In this case control has no way to refresh its data. So you can set persist as true, so control will persist the promise in its local cache and when refresh method is invoked via action set, promise will be executed once again.
By default caching is disabled on json method, however, to enable caching and cache the result for multiple instances, you can use cachedJson method. This not only enables HTTP cache, but it also stores json results for next operations. Please note, results of cachedJson is cached as a local javascript object in current page's life cycle. For the same url, cachedJson will not invoke jQuery.ajax, instead returns earlier results. Everything vanishes along with page, so next time, promise will fetch data from jQuery.ajax, however it is subjected to HTTP caching by headers.
By default, AtomPromise will display an alert with an error message in case of failure. You can set it to false to stop showing alert.
While AJAX call is in progress, busy dialog will lock the screen, if you want to turn it off, you can set it to false.