194 lines
7.3 KiB
HTML
194 lines
7.3 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>doc</title>
|
|
<style>
|
|
/*github.com style (c) Vasily Polovnyov <vast@whiteants.net>*/
|
|
pre code {
|
|
display: block; padding: 0.5em;
|
|
color: #333;
|
|
background: #f8f8ff
|
|
}
|
|
pre .comment,
|
|
pre .template_comment,
|
|
pre .diff .header,
|
|
pre .javadoc {
|
|
color: #998;
|
|
font-style: italic
|
|
}
|
|
pre .keyword,
|
|
pre .css .rule .keyword,
|
|
pre .winutils,
|
|
pre .javascript .title,
|
|
pre .nginx .title,
|
|
pre .subst,
|
|
pre .request,
|
|
pre .status {
|
|
color: #333;
|
|
font-weight: bold
|
|
}
|
|
pre .number,
|
|
pre .hexcolor,
|
|
pre .ruby .constant {
|
|
color: #099;
|
|
}
|
|
pre .string,
|
|
pre .tag .value,
|
|
pre .phpdoc,
|
|
pre .tex .formula {
|
|
color: #d14
|
|
}
|
|
pre .title,
|
|
pre .id {
|
|
color: #900;
|
|
font-weight: bold
|
|
}
|
|
pre .javascript .title,
|
|
pre .lisp .title,
|
|
pre .clojure .title,
|
|
pre .subst {
|
|
font-weight: normal
|
|
}
|
|
pre .class .title,
|
|
pre .haskell .type,
|
|
pre .vhdl .literal,
|
|
pre .tex .command {
|
|
color: #458;
|
|
font-weight: bold
|
|
}
|
|
pre .tag,
|
|
pre .tag .title,
|
|
pre .rules .property,
|
|
pre .django .tag .keyword {
|
|
color: #000080;
|
|
font-weight: normal
|
|
}
|
|
pre .attribute,
|
|
pre .variable,
|
|
pre .lisp .body {
|
|
color: #008080
|
|
}
|
|
pre .regexp {
|
|
color: #009926
|
|
}
|
|
pre .class {
|
|
color: #458;
|
|
font-weight: bold
|
|
}
|
|
pre .symbol,
|
|
pre .ruby .symbol .string,
|
|
pre .lisp .keyword,
|
|
pre .tex .special,
|
|
pre .prompt {
|
|
color: #990073
|
|
}
|
|
pre .built_in,
|
|
pre .lisp .title,
|
|
pre .clojure .built_in {
|
|
color: #0086b3
|
|
}
|
|
pre .preprocessor,
|
|
pre .pi,
|
|
pre .doctype,
|
|
pre .shebang,
|
|
pre .cdata {
|
|
color: #999;
|
|
font-weight: bold
|
|
}
|
|
pre .deletion {
|
|
background: #fdd
|
|
}
|
|
pre .addition {
|
|
background: #dfd
|
|
}
|
|
pre .diff .change {
|
|
background: #0086b3
|
|
}
|
|
pre .chunk {
|
|
color: #aaa
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h1>Using AngularJS Promises and Umbraco Resources</h1>
|
|
<h2>Promises in Umbraco Resources</h2>
|
|
<p>All Umbraco resource methods utilize a helper method:</p>
|
|
<pre><code>umbRequestHelper.resourcePromise</code></pre>
|
|
<p>This method accepts 2 arguments:</p>
|
|
<ul>
|
|
<li>The angular HttpPromise which is created with a call to $http.get (post, etc..)</li>
|
|
<li>The error message that is bubbled to the UI when the http call fails</li>
|
|
</ul>
|
|
<p>Here's an example of the usage in an Umbraco resource. This example is the method of the treeResource that fetches data to display the menu for a tree node:</p>
|
|
<pre><code>/** Loads in the data to display the nodes menu */
|
|
loadMenu: function (node) {
|
|
|
|
return umbRequestHelper.resourcePromise(
|
|
$http.get(getTreeMenuUrl(node)),
|
|
"Failed to retreive data for a node's menu " + node.id);
|
|
}</code></pre>
|
|
<p>HTTP error handling is performed automatically inside of the <code>umbRequestHelper.resourcePromise</code> and inside of Umbraco's response interceptors.</p>
|
|
<h2>Consuming Umbraco resources</h2>
|
|
<p>When consuming Umbraco resources, a normal angular promise will be returned based on the above <code>umbRequestHelper.resourcePromise</code>. The success callback will always receive the RAW json data from the server and the error callback will always receive an object containing these properties:</p>
|
|
<ul>
|
|
<li>erroMsg = the error message that can be used to show in the UI</li>
|
|
<li>data = the original data object used to create the promise</li>
|
|
</ul>
|
|
<p>Error handling will be done automatically in the Umbraco resource. Http error handling should not be done during the consumption of an Umbraco resource.</p>
|
|
<h3>Simple example</h3>
|
|
<p>An simple example of consuming an Umbraco resource:</p>
|
|
<pre><code>treeResource.loadMenu(treeItem.node)
|
|
.then(function(data) {
|
|
scope.menu = data;
|
|
});</code></pre>
|
|
<h3>Transforming result data</h3>
|
|
<p>Sometimes the consumption of an Umbraco resource needs to return a promise itself. This is required in some circumstances such as:</p>
|
|
<p>The data from a result of an http resource might need to be transformed into something usable in the UI so a Service may need to call a resource, transform the result and continue to return it's own promise (since everything happens async).</p>
|
|
<p>This is actually very simple to do, the Service (or whatever is consuming the resource) just returns the result of their 'then' call. Example - this example is the <code>getActions</code> method of the <code>treeService</code> that consumes the treeResource, transforms the result and continues to return it's own promise:</p>
|
|
<pre><code>getActions: function(treeItem, section) {
|
|
|
|
return treeResource.loadMenu(treeItem.node)
|
|
.then(function(data) {
|
|
//need to convert the icons to new ones
|
|
for (var i = 0; i < data.length; i++) {
|
|
data[i].cssclass = iconHelper.convertFromLegacyIcon(data[i].cssclass);
|
|
}
|
|
return data;
|
|
});
|
|
} </code></pre>
|
|
<p>Notice that this is just returning the call to 'then' which will return a promise that resolves the data from it's return statement.</p>
|
|
<h3>Error hanlding</h3>
|
|
<p>Ok, what about error handling ? This is really simple as well, we just add an additional method to the .then call. A simple example:</p>
|
|
<pre><code>treeResource.loadMenu(treeItem.node)
|
|
.then(function(data) {
|
|
scope.menu = data;
|
|
}, function(err) {
|
|
//display the error
|
|
notificationsService.error(err.errorMsg);
|
|
});</code></pre>
|
|
<h3>Error handling when transforming result data</h3>
|
|
<p>This is one of those things that is important to note! If you need to return a custom promise based on the result of an Umbraco resource (like the example above in Transforming result data) then you will need to 'throw' an error if you want to 'bubble' the error to the handler of your custom promise.</p>
|
|
<p>The good news is, this is very simple to do, example:</p>
|
|
<pre><code>getActions: function(treeItem, section) {
|
|
|
|
return treeResource.loadMenu(treeItem.node)
|
|
.then(function(data) {
|
|
//need to convert the icons to new ones
|
|
for (var i = 0; i < data.length; i++) {
|
|
data[i].cssclass = iconHelper.convertFromLegacyIcon(data[i].cssclass);
|
|
}
|
|
return data;
|
|
}, function(err) {
|
|
//display the error
|
|
notificationsService.error(err.errorMsg);
|
|
|
|
//since we want the handler of this promise to be notified of this error
|
|
// we just need to rethrow it:
|
|
throw err;
|
|
});
|
|
}</code></pre>
|
|
<p>The next thing that is important to note is that <strong>you don't have to do anything</strong> if you don't want to do anything with the error but still want the error bubbled up to your promises handlers. So for example, if you are expecting the handler of this promise to handle the error and display something in the UI, just leave out the function(err) callback which would look exactly the same as the example for 'Transforming result data'</p>
|
|
|
|
</body>
|
|
</html>
|