101 lines
4.5 KiB
HTML
Executable file
101 lines
4.5 KiB
HTML
Executable file
<h1><code ng:non-bindable=""></code>
|
|
<span class="hint"></span>
|
|
</h1>
|
|
<div><a href="http://github.com/angular/angular.js/edit/master/docs/content/guide/dev_guide.services.creating_services.ngdoc" class="improve-docs btn btn-primary">Improve this doc</a><p>While Angular offers several useful services, for any nontrivial application you'll find it useful
|
|
to write your own custom services. To do this you begin by registering a service factory function
|
|
with a module either via the <a href="api/angular.module"><code>Module#factory api</code></a> or directly
|
|
via the <a href="api/AUTO.$provide"><code>$provide</code></a> api inside of module config function.</p>
|
|
|
|
<p>All Angular services participate in <a href="guide/di">dependency injection (DI)</a> by registering
|
|
themselves with Angular's DI system (injector) under a <code>name</code> (id) as well as by declaring
|
|
dependencies which need to be provided for the factory function of the registered service. The
|
|
ability to swap dependencies for mocks/stubs/dummies in tests allows for services to be highly
|
|
testable.</p>
|
|
|
|
<h2>Registering Services</h2>
|
|
|
|
<p>To register a service, you must have a module that this service will be part of. Afterwards, you
|
|
can register the service with the module either via the <a href="api/angular.Module"><code>Module api</code></a> or
|
|
by using the <a href="api/AUTO.$provide"><code>$provide</code></a> service in the module configuration
|
|
function.The following pseudo-code shows both approaches:</p>
|
|
|
|
<p>Using the angular.Module api:
|
|
<pre class="prettyprint linenums">
|
|
var myModule = angular.module('myModule', []);
|
|
myModule.factory('serviceId', function() {
|
|
var shinyNewServiceInstance;
|
|
//factory function body that constructs shinyNewServiceInstance
|
|
return shinyNewServiceInstance;
|
|
});
|
|
</pre>
|
|
|
|
<p>Using the $provide service:
|
|
<pre class="prettyprint linenums">
|
|
angular.module('myModule', [], function($provide) {
|
|
$provide.factory('serviceId', function() {
|
|
var shinyNewServiceInstance;
|
|
//factory function body that constructs shinyNewServiceInstance
|
|
return shinyNewServiceInstance;
|
|
});
|
|
});
|
|
</pre>
|
|
|
|
<p>Note that you are not registering a service instance, but rather a factory function that will
|
|
create this instance when called.</p>
|
|
|
|
<h2>Dependencies</h2>
|
|
|
|
<p>Services can not only be depended upon, but can also have their own dependencies. These can be specified
|
|
as arguments of the factory function. <a href="guide/di">Read more</a> about dependency injection (DI)
|
|
in Angular and the use of array notation and the $inject property to make DI annotation
|
|
minification-proof.</p>
|
|
|
|
<p>Following is an example of a very simple service. This service depends on the <code>$window</code> service
|
|
(which is passed as a parameter to the factory function) and is just a function. The service simply
|
|
stores all notifications; after the third one, the service displays all of the notifications by
|
|
window alert.</p>
|
|
|
|
<pre class="prettyprint linenums">
|
|
angular.module('myModule', [], function($provide) {
|
|
$provide.factory('notify', ['$window', function(win) {
|
|
var msgs = [];
|
|
return function(msg) {
|
|
msgs.push(msg);
|
|
if (msgs.length == 3) {
|
|
win.alert(msgs.join("\n"));
|
|
msgs = [];
|
|
}
|
|
};
|
|
}]);
|
|
});
|
|
</pre>
|
|
|
|
<h2>Instantiating Angular Services</h2>
|
|
|
|
<p>All services in Angular are instantiated lazily. This means that a service will be created
|
|
only when it is needed for instantiation of a service or an application component that depends on it.
|
|
In other words, Angular won't instantiate services unless they are requested directly or
|
|
indirectly by the application.</p>
|
|
|
|
<h2>Services as singletons</h2>
|
|
|
|
<p>Lastly, it is important to realize that all Angular services are application singletons. This means
|
|
that there is only one instance of a given service per injector. Since Angular is lethally allergic
|
|
to global state, it is possible to create multiple injectors, each with its own instance of a
|
|
given service, but that is rarely needed, except in tests where this property is crucially
|
|
important.</p>
|
|
|
|
<h3>Related Topics</h3>
|
|
|
|
<ul>
|
|
<li><a href="guide/dev_guide.services.understanding_services">Understanding Angular Services</a></li>
|
|
<li><a href="guide/dev_guide.services.managing_dependencies">Managing Service Dependencies</a></li>
|
|
<li><a href="guide/dev_guide.services.injecting_controllers">Injecting Services Into Controllers</a></li>
|
|
<li><a href="guide/dev_guide.services.testing_services">Testing Angular Services</a></li>
|
|
</ul>
|
|
|
|
<h3>Related API</h3>
|
|
|
|
<ul>
|
|
<li><a href="api/ng">Angular Service API</a></li>
|
|
</ul></div>
|