How to create origin addons
Data Provider is agnostic about data origins, so it can be used to read data from a REST API, from localStorage
, or from any other origin. Custom addons are distributed for each different type of origin, and you can even create your owns.
In this guide we'll walk through the process of creating a simple "fetch" Data Provider origin able to perform Ajax requests, allowing to connect an application to a REST Api. The complete source code of the guide is in our repository of examples, and all used methods are described in the Provider API.
#
Extending the Provider ClassTo create a new origin type, you'll have to extend the Provider
Class, which is the one providing all data-provider common features and methods.
#
OptionsOur addon will accept a baseUrl
option, which will be defined when instantiating the Provider, and the rest of the url will be defined as a query
parameter. So, every different "queried" instance (every different url) will have its own cache, (it will still be possible to clean all caches calling to the parent
instance cleanCache
method).
It is a very simple scenario, but it will be useful to illustrate the example. If you want to use a more complex data-provider
origin to connect an application to a REST API and handle a lot of possible complex scenarios take a look at the Axios addon.
Define a configMethod
in the Class. It will receive the options when initialized and also when the config
method is called, so the baseUrl
could be also changed after initializing it.
Store the baseUrl
option in an internal property of the class.
#
TagsIn order to allow users to select all instances of our new addon at the same time using the providers
handler, we will add a base tag to it. Users will still be able to add its own tags to the addon instances using options, but all of them will have the base tags too. For this purpose we will add a baseTags
getter returning the tag/tags.
#
Read methodNow we will define the readMethod
of our origin, which will use the cross-fetch
library under the hood. We will use the this.queryValue
to obtain the rest of the url in case the provider is queried. The method also checks the response status code, treating it as an error if it is upper or equal than 400, and converts the response to a json, which will be the value stored in the state data
property.
Errors will be handled automatically by data-provider, its value will be stored in the error
property of the state, and the cache will be invalidated.
And that's all! Now you have a custom origin reading data from a REST API, and you could use it as in the next examples 😊
After next examples we will add more methods to the addon, and give some tips about how to publish it to NPM.
#
Using the addonInstantiate the origin, giving to it an id to make easier the identification of the different providers states in case you have to debug it.
Define also the baseUrl
option, and an empty array as initial state, so it will be the value of the data state while the real data has not been loaded.
Now you can use it directly with promises using the read
method:
And you can use it in a React project using the react
addon, for example:
Read the "Usage with React" chapter of the Basic Tutorial to learn more about how to use the data-provider React addon.
#
Using the addon with SelectorsEvery data-provider origin addon can be used as a dependency of data-provider Selectors, so you can combine the results of two different queries, for example, or combine two different origin instances, or two different addons, etc. You can read the Selectors recipes chapter to get a reference about the power of using Selectors.
Create one selector that will return one post, including the name and email of the user who created it. As query parameter the selector will receive the id of the post.
Now you can use the selector directly, and it will fetch all needed data:
This is only an example in which two API calls are executed when the Post component is rendered. Different behaviors could be achieved simply creating different Selectors, for example one selector reading all posts and users data and filtering or combining them in client side, etc.
Read the Selectors API chapter for further info about data-provider Selectors.
#
Custom methodsFor the moment our addon only can perform GET requests to the API, so let's add some methods to it to allow updating a resource. Our method will send a PATCH request and will clean the cache of the resource when it receives a success response.
Now you could use this new method in the same way than the read
one:
As we have cleaned the cache of the provider after the request, the read method will execute a new request when it is called again, and it will also emit an event, so, if you are using the "react" addon, for example, all of the connected views to the jsonPlaceHolderApi.query("posts/1")
resource will be refreshed automatically with the new data from the server.
#
Go furtherApart of defining custom methods, you could also use arguments in the read method or other custom methods to set the request headers or other fetch
options, etc. It will depend of the addon purpose, the type of the origin, and lots of other details if it is better to use configuration, arguments, custom methods, etc. Remember to read the Provider API chapter to get further information about all of the possibilities.
#
Publish to NPMIf you are going to publish your addon to NPM, you should follow some tips:
- Add @data-provider/core as a
peerDependency
to thepackage.json
file:
- Add at least next keywords to make easier to find your addon to other users:
- We recommend to use Rollup to bundle the package in CJS, ESM and UMD formats at least, defining each different entry point in the
package.json
: