knowhow-server
Version:
A personal workflow engine that can manage and use any network connected host
267 lines (253 loc) • 18.2 kB
HTML
<a href="http://github.com/angular/angular.js/tree/v1.2.9/src/auto/injector.js#L291" class="view-source btn btn-action"><i class="icon-zoom-in"> </i> View source</a><a href="http://github.com/angular/angular.js/edit/master/src/auto/injector.js" class="improve-docs btn btn-primary"><i class="icon-edit"> </i> Improve this doc</a><h1><code ng:non-bindable="">$provide</code>
<div><span class="hint">service in module <code ng:non-bindable="">AUTO</code>
</span>
</div>
</h1>
<div><h2 id="description">Description</h2>
<div class="description"><div class="auto-provide-page"><p>The <a href="api/AUTO.$provide"><code>$provide</code></a> service has a number of methods for registering components
with the <a href="api/AUTO.$injector"><code>$injector</code></a>. Many of these functions are also exposed on
<a href="api/angular.Module"><code>angular.Module</code></a>.</p>
<p>An Angular <strong>service</strong> is a singleton object created by a <strong>service factory</strong>. These <strong>service
factories</strong> are functions which, in turn, are created by a <strong>service provider</strong>.
The <strong>service providers</strong> are constructor functions. When instantiated they must contain a
property called <code>$get</code>, which holds the <strong>service factory</strong> function.</p>
<p>When you request a service, the <a href="api/AUTO.$injector"><code>$injector</code></a> is responsible for finding the
correct <strong>service provider</strong>, instantiating it and then calling its <code>$get</code> <strong>service factory</strong>
function to get the instance of the <strong>service</strong>.</p>
<p>Often services have no configuration options and there is no need to add methods to the service
provider. The provider will be no more than a constructor function with a <code>$get</code> property. For
these cases the <a href="api/AUTO.$provide"><code>$provide</code></a> service has additional helper methods to register
services without specifying a provider.</p>
<ul>
<li><a href="api/AUTO.$provide#methods_provider"><code>provider(provider)</code></a> - registers a <strong>service provider</strong> with the
<a href="api/AUTO.$injector"><code>$injector</code></a></li>
<li><a href="api/AUTO.$provide#methods_constant"><code>constant(obj)</code></a> - registers a value/object that can be accessed by
providers and services.</li>
<li><a href="api/AUTO.$provide#methods_value"><code>value(obj)</code></a> - registers a value/object that can only be accessed by
services, not providers.</li>
<li><a href="api/AUTO.$provide#methods_factory"><code>factory(fn)</code></a> - registers a service <strong>factory function</strong>, <code>fn</code>,
that will be wrapped in a <strong>service provider</strong> object, whose <code>$get</code> property will contain the
given factory function.</li>
<li><a href="api/AUTO.$provide#methods_service"><code>service(class)</code></a> - registers a <strong>constructor function</strong>, <code>class</code> that
that will be wrapped in a <strong>service provider</strong> object, whose <code>$get</code> property will instantiate
a new object using the given constructor function.</li>
</ul>
<p>See the individual methods for more information and examples.</p>
</div></div>
<div class="member method"><h2 id="methods">Methods</h2>
<ul class="methods"><li><h3 id="methods_constant">constant(name, value)</h3>
<div class="constant"><div class="auto-provide-constant-page"><p>Register a <strong>constant service</strong>, such as a string, a number, an array, an object or a function,
with the <a href="api/AUTO.$injector"><code>$injector</code></a>. Unlike <a href="api/AUTO.$provide#value"><code>value</code></a> it can be
injected into a module configuration function (see <a href="api/angular.Module#config"><code>angular.Module#config</code></a>) and it cannot
be overridden by an Angular <a href="api/AUTO.$provide#decorator"><code>decorator</code></a>.</p>
</div><h5 id="methods_constant_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>name</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="auto-provide-constant-page"><p>The name of the constant.</p>
</div></td></tr><tr><td>value</td><td><a href="" class="label type-hint type-hint-object">*</a></td><td><div class="auto-provide-constant-page"><p>The constant value.</p>
</div></td></tr></tbody></table><h5 id="methods_constant_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="auto-provide-constant-page"><p>registered instance</p>
</div></td></tr></table><h4 id="methods_constant_example">Example</h4>
<div class="example"><div class="auto-provide-constant-page"><p>Here a some examples of creating constants:
<pre class="prettyprint linenums">
$provide.constant('SHARD_HEIGHT', 306);
$provide.constant('MY_COLOURS', ['red', 'blue', 'grey']);
$provide.constant('double', function(value) {
return value * 2;
});
</pre>
</div></div>
</div>
</li>
<li><h3 id="methods_decorator">decorator(name, decorator)</h3>
<div class="decorator"><div class="auto-provide-decorator-page"><p>Register a <strong>service decorator</strong> with the <a href="api/AUTO.$injector"><code>$injector</code></a>. A service decorator
intercepts the creation of a service, allowing it to override or modify the behaviour of the
service. The object returned by the decorator may be the original service, or a new service
object which replaces or wraps and delegates to the original service.</p>
</div><h5 id="methods_decorator_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>name</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="auto-provide-decorator-page"><p>The name of the service to decorate.</p>
</div></td></tr><tr><td>decorator</td><td><a href="" class="label type-hint type-hint-function">function()</a></td><td><div class="auto-provide-decorator-page"><p>This function will be invoked when the service needs to be
instantiated and should return the decorated service instance. The function is called using
the <a href="api/AUTO.$injector#invoke"><code>injector.invoke</code></a> method and is therefore fully injectable.
Local injection arguments:</p>
<ul>
<li><code>$delegate</code> - The original service instance, which can be monkey patched, configured,
decorated or delegated to.</li>
</ul>
</div></td></tr></tbody></table><h4 id="methods_decorator_example">Example</h4>
<div class="example"><div class="auto-provide-decorator-page"><p>Here we decorate the <a href="api/ng.$log"><code>$log</code></a> service to convert warnings to errors by intercepting
calls to <a href="api/ng.$log#error"><code>$log.warn()</code></a>.
<pre class="prettyprint linenums">
$provider.decorator('$log', ['$delegate', function($delegate) {
$delegate.warn = $delegate.error;
return $delegate;
}]);
</pre>
</div></div>
</div>
</li>
<li><h3 id="methods_factory">factory(name, $getFn)</h3>
<div class="factory"><div class="auto-provide-factory-page"><p>Register a <strong>service factory</strong>, which will be called to return the service instance.
This is short for registering a service where its provider consists of only a <code>$get</code> property,
which is the given service factory function.
You should use <a href="api/AUTO.$provide#factory"><code>$provide.factory(getFn)</code></a> if you do not need to
configure your service in a provider.</p>
</div><h5 id="methods_factory_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>name</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="auto-provide-factory-page"><p>The name of the instance.</p>
</div></td></tr><tr><td>$getFn</td><td><a href="" class="label type-hint type-hint-function">function()</a></td><td><div class="auto-provide-factory-page"><p>The $getFn for the instance creation. Internally this is a short hand
for <code>$provide.provider(name, {$get: $getFn})</code>.</p>
</div></td></tr></tbody></table><h5 id="methods_factory_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="auto-provide-factory-page"><p>registered provider instance</p>
</div></td></tr></table><h4 id="methods_factory_example">Example</h4>
<div class="example"><div class="auto-provide-factory-page"><p>Here is an example of registering a service
<pre class="prettyprint linenums">
$provide.factory('ping', ['$http', function($http) {
return function ping() {
return $http.send('/ping');
};
}]);
</pre>
You would then inject and use this service like this:
<pre class="prettyprint linenums">
someModule.controller('Ctrl', ['ping', function(ping) {
ping();
}]);
</pre>
</div></div>
</div>
</li>
<li><h3 id="methods_provider">provider(name, provider)</h3>
<div class="provider"><div class="auto-provide-provider-page"><p>Register a <strong>provider function</strong> with the <a href="api/AUTO.$injector"><code>$injector</code></a>. Provider functions
are constructor functions, whose instances are responsible for "providing" a factory for a
service.</p>
<p>Service provider names start with the name of the service they provide followed by <code>Provider</code>.
For example, the <a href="api/ng.$log"><code>$log</code></a> service has a provider called
<a href="api/ng.$logProvider"><code>$logProvider</code></a>.</p>
<p>Service provider objects can have additional methods which allow configuration of the provider
and its service. Importantly, you can configure what kind of service is created by the <code>$get</code>
method, or how that service will act. For example, the <a href="api/ng.$logProvider"><code>$logProvider</code></a> has a
method <a href="api/ng.$logProvider#debugenabled"><code>debugEnabled</code></a>
which lets you specify whether the <a href="api/ng.$log"><code>$log</code></a> service will log debug messages to the
console or not.</p>
</div><h5 id="methods_provider_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>name</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="auto-provide-provider-page"><p>The name of the instance. NOTE: the provider will be available under <code>name +
'Provider'</code> key.</p>
</div></td></tr><tr><td>provider</td><td><a href="" class="label type-hint type-hint-object">Object</a><a href="" class="label type-hint type-hint-function">function()</a></td><td><div class="auto-provide-provider-page"><p>If the provider is:</p>
<ul>
<li><code>Object</code>: then it should have a <code>$get</code> method. The <code>$get</code> method will be invoked using<pre><code> <a href="api/AUTO.$injector#invoke"><code>$injector.invoke()</code></a> when an instance needs to be
created.</code></pre>
</li>
<li><code>Constructor</code>: a new instance of the provider will be created using<pre><code> <a href="api/AUTO.$injector#instantiate"><code>$injector.instantiate()</code></a>, then treated as
`object`.</code></pre>
</li>
</ul>
</div></td></tr></tbody></table><h5 id="methods_provider_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="auto-provide-provider-page"><p>registered provider instance</p>
</div></td></tr></table><h4 id="methods_provider_example">Example</h4>
<div class="example"><div class="auto-provide-provider-page"><p>The following example shows how to create a simple event tracking service and register it using
<a href="api/AUTO.$provide#methods_provider"><code>$provide.provider()</code></a>.</p>
<pre class="prettyprint linenums">
// Define the eventTracker provider
function EventTrackerProvider() {
var trackingUrl = '/track';
// A provider method for configuring where the tracked events should been saved
this.setTrackingUrl = function(url) {
trackingUrl = url;
};
// The service factory function
this.$get = ['$http', function($http) {
var trackedEvents = {};
return {
// Call this to track an event
event: function(event) {
var count = trackedEvents[event] || 0;
count += 1;
trackedEvents[event] = count;
return count;
},
// Call this to save the tracked events to the trackingUrl
save: function() {
$http.post(trackingUrl, trackedEvents);
}
};
}];
}
describe('eventTracker', function() {
var postSpy;
beforeEach(module(function($provide) {
// Register the eventTracker provider
$provide.provider('eventTracker', EventTrackerProvider);
}));
beforeEach(module(function(eventTrackerProvider) {
// Configure eventTracker provider
eventTrackerProvider.setTrackingUrl('/custom-track');
}));
it('tracks events', inject(function(eventTracker) {
expect(eventTracker.event('login')).toEqual(1);
expect(eventTracker.event('login')).toEqual(2);
}));
it('saves to the tracking url', inject(function(eventTracker, $http) {
postSpy = spyOn($http, 'post');
eventTracker.event('login');
eventTracker.save();
expect(postSpy).toHaveBeenCalled();
expect(postSpy.mostRecentCall.args[0]).not.toEqual('/track');
expect(postSpy.mostRecentCall.args[0]).toEqual('/custom-track');
expect(postSpy.mostRecentCall.args[1]).toEqual({ 'login': 1 });
}));
});
</pre>
</div></div>
</div>
</li>
<li><h3 id="methods_service">service(name, constructor)</h3>
<div class="service"><div class="auto-provide-service-page"><p>Register a <strong>service constructor</strong>, which will be invoked with <code>new</code> to create the service
instance.
This is short for registering a service where its provider's <code>$get</code> property is the service
constructor function that will be used to instantiate the service instance.</p>
<p>You should use <a href="api/AUTO.$provide#methods_service"><code>$provide.service(class)</code></a> if you define your service
as a type/class.</p>
</div><h5 id="methods_service_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>name</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="auto-provide-service-page"><p>The name of the instance.</p>
</div></td></tr><tr><td>constructor</td><td><a href="" class="label type-hint type-hint-function">Function</a></td><td><div class="auto-provide-service-page"><p>A class (constructor function) that will be instantiated.</p>
</div></td></tr></tbody></table><h5 id="methods_service_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="auto-provide-service-page"><p>registered provider instance</p>
</div></td></tr></table><h4 id="methods_service_example">Example</h4>
<div class="example"><div class="auto-provide-service-page"><p>Here is an example of registering a service using
<a href="api/AUTO.$provide#methods_service"><code>$provide.service(class)</code></a>.
<pre class="prettyprint linenums">
$provide.service('ping', ['$http', function($http) {
var Ping = function() {
this.$http = $http;
};
Ping.prototype.send = function() {
return this.$http.get('/ping');
};
return Ping;
}]);
</pre>
You would then inject and use this service like this:
<pre class="prettyprint linenums">
someModule.controller('Ctrl', ['ping', function(ping) {
ping.send();
}]);
</pre>
</div></div>
</div>
</li>
<li><h3 id="methods_value">value(name, value)</h3>
<div class="value"><div class="auto-provide-value-page"><p>Register a <strong>value service</strong> with the <a href="api/AUTO.$injector"><code>$injector</code></a>, such as a string, a
number, an array, an object or a function. This is short for registering a service where its
provider's <code>$get</code> property is a factory function that takes no arguments and returns the <strong>value
service</strong>.</p>
<p>Value services are similar to constant services, except that they cannot be injected into a
module configuration function (see <a href="api/angular.Module#config"><code>angular.Module#config</code></a>) but they can be overridden by
an Angular
<a href="api/AUTO.$provide#decorator"><code>decorator</code></a>.</p>
</div><h5 id="methods_value_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>name</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="auto-provide-value-page"><p>The name of the instance.</p>
</div></td></tr><tr><td>value</td><td><a href="" class="label type-hint type-hint-object">*</a></td><td><div class="auto-provide-value-page"><p>The value.</p>
</div></td></tr></tbody></table><h5 id="methods_value_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="auto-provide-value-page"><p>registered provider instance</p>
</div></td></tr></table><h4 id="methods_value_example">Example</h4>
<div class="example"><div class="auto-provide-value-page"><p>Here are some examples of creating value services.
<pre class="prettyprint linenums">
$provide.value('ADMIN_USER', 'admin');
$provide.value('RoleLookup', { admin: 0, writer: 1, reader: 2 });
$provide.value('halfOf', function(value) {
return value / 2;
});
</pre>
</div></div>
</div>
</li>
</ul>
</div>
</div>