providers
#
PurposeData Provider gives to us a way for managing a provider or a groups of providers without having to import them directly. For that purpose, it exports the providers
object.
The purpose of this utility is to give the possibility of delegate the configuration of providers to a piece that should have not known about used providers (usually the "main app").
The providers
object gives to us some methods that could be usually wanted to be executed over many providers at a time, as cleanCache
, on
, etc. But the most interesting method is the config
one, which works for already instantiated providers, and also for providers instantiated in the future, so it does not matter if we first call to the providers.config
method, or if we first instantiate the providers. This is a very important detail, because the piece at charge of configuring providers does not need to know about specific providers, and the providers don't need to know about the base configuration, which boost the reusability. This is the reason why Data Provider gives to us a "tag based configuration system".
#
Defining tagsWe can define tags
for our providers when creating them, and later we can use those tags for configuring at a time all providers containing certain tag.
#
Origins tagsOrigin addons should usually automatically add its own tags to the provided tags
array when we create a provider. This is made to allow configuring easily all providers of a same type, as "axios", "localStorage", etc. Read the documentation of each addon to know which tags are automatically added by it.
#
Selectors tagsTags can be added also to selectors using the tags
option, but all of them include automatically the selector
tag, that may be useful to handle all selectors together.
#
ExampleAs a brief example for a better understand before describing the API:
providers
Methods#
Note that, even when the object is called providers
, all described methods here also are applied to instantiated selectors.
The providers
object has next methods:
getByTag(tag)
#
#
Argumentstag
(String): Tag to use for selecting providers.
#
ReturnsA group of providers containing the provided tag. The returned "selection" has its own methods, which are described in the providers selection Methods chapter below.
#
ExamplegetById(id)
#
#
Argumentsid
(String): Id to use for selecting providers.
#
ReturnsA selection of providers with the provided id (normally only one). The returned "selection" has its own methods, which are describe in the providers selection Methods chapter below.
The
providers
object also contains all methods described in theproviders selection
Methods chapter. The only difference is that theprovider selection
will contain all instantiated providers and selectors.
#
ExampleonNewProvider(listener)
#
Executes the provided listener each time a new provider is created. Useful to add listeners or call to methods of providers that are not even created (indispensable in a "lazy loading" scenario).
#
Argumentslistener
(Function): Listener function. It will receive the created provider as first argument.
#
Returns(Function) A function that unsubscribes the added listener.
#
Exampleclear()
#
Clears all registered providers, which will not be available any more for selecting them using previously mentioned providers
methods. This method is intended to be used for testing and internal usage only.
providers selection
Methods#
onNewProvider(listener)
#
Same method than described before, but it can also be used scoped for an specific selection of providers.
#
Exampleconfig(configuration)
#
Calls to the config
method of selected providers with provided configuration object. Note that this method works for already instantiated providers, and also for providers instantiated in the future, so it does not matter if we first call to the providers.config
method, or if we first instantiate the providers.
#
Argumentsconfiguration
(Object): An object containing configuration to be set into the providers. Read the Provider api and Selector api pages for further info about available options.
#
ReturnsThe providers selection
object itself.
#
ExamplecleanCache(options)
#
Cleans the cache of selected providers and selectors.
#
Argumentsoptions
(Object): Object that can contain next properties:force
(Boolean): Iftrue
, will force to clean the cache immediately, ignoring thecleanCacheThrottle
option.
#
ReturnsThe providers selection
object itself.
#
ExamplescleanDependenciesCache(options)
#
Cleans the cache of all dependencies of selected selectors.
#
Argumentsoptions
(Object): Object that can contain next properties:force
(Boolean): Iftrue
, will force to clean the cache immediately, ignoring thecleanCacheThrottle
option.except
(Array): Array of providers which cache shouldn't be cleaned.
#
ReturnsThe providers selection
object itself.
#
ExamplesresetState()
#
Resets the state of selected providers and selectors. Read the providers and selectors methods chapter for further info.
#
ReturnsThe providers selection
object itself.
#
Exampleson(eventName, listener)
#
Subscribes the provided listener to the given eventName
in selected providers. Read the providers and selectors methods and the API Events chapters for further info.
#
Returns(Function): A function that unsubscribes all added listeners.
#
ExamplesonChild(eventName, listener)
#
Subscribes the provided listener to the given eventName
in selected providers children. Read the providers and selectors methods and the API Events chapters for further info.
#
Returns(Function): A function that unsubscribes all added listeners.
#
Examplesonce(eventName, listener)
#
Subscribes the provided listener to the given eventName
in selected providers for once time. Read the providers and selectors methods and the API Events chapters for further info.
#
Returns(Function): A function that unsubscribes all added listeners.
#
ExamplesonceChild(eventName, listener)
#
Subscribes the provided listener to the given eventName
in selected providers children for once time. Read the providers and selectors methods and the API Events chapters for further info.
#
Returns(Function): A function that unsubscribes all added listeners.
#
Examplescall(methodName, ...arguments)
#
Calls to the given method using given arguments in selected providers and selectors.
#
Returns(Array): Array containing the returned results by each one of the providers and selectors. The array will contain undefined
in the positions corresponding to providers that didn't have the provided method.
#
Examplesproviders selection
getters#
size
#
#
Returns(Number): Total count of selected providers and selectors, including children (queried instances).
#
Exampleelements
#
#
Returns(Array): Array containing all selected providers and selectors.
#
Example#
Tips- Use the
providers
object only for configuring options that should not be coupled to the initialization of the provider itself. This can help to make your providers reusable across applications. - Use the addons automatic tags for configuring all providers of the same type at a time (for example, use the "axios" tag to set the
baseUrl
of the API if you are using the "axios" addon)