Query Component
A Query component is a lower level component which you would typically use in making only get reqeusts
, hence the component name Query
. Queries are typically operations performed on a database which do not cause side effects to the database. The Query component is a component exported from react-kunyora
which you could use to connect your UI to datas sent by your api. It is also a declarative API which allows you to carry out operations while handling states like loading and error in a declarative manner.
In this section of the documentation, we would be creating a very simple notification list application
, so sit tight and get your hands ready to practice some query code.
Creating a Notification List Application
Creating the client
Connecting to our data using the Query component
Creating a Notification List Application
In this section of the Query tutorial, we would be creating a simple notification listing application which would query our online API to get a list of notification, it would then render the results of this notification in a list. The List would be able to refetch its queries in case there is an error in the network. We shall also provide detailed explanation of the Query props
in action.
Creating the client
Let's go ahead to create the client for our application. We would assume that you are familiar with creating the client already and therefore we would explain other details that you should be aware of when using our library with reactJs
. However, if you do not have enough knowledge about creating a client
, then check our indepth tutorial docs
and the Kunyora Api Reference Configuration section.
/**
* Index.js
*/
import React from 'react';
import {render} from 'react-dom';
import KunyoraClient from 'kunyora';
import {KunyoraProvider} from 'react-kunyora';
import registerServiceWorker from './registerServiceWorker';
import NotificationList from './NotificationList';
const client = KunyoraClient({
baseURL: 'https://kunyora.herokuapp.com/',
nouns: [{path: 'notification', name: 'notification'}],
});
const App = () => (
<KunyoraProvider client={client} store={client.store}>
<div>
<NotificationList />
</div>
</KunyoraProvider>
);
render(<App />, document.getElementById('root'));
registerServiceWorker();
The client
above is created using just the baseURL
and the nouns
of the config
. When using a view layer like reactJs
, there is no need to specify the thenables
and catchables
properties in your config as react-kunyora
automatically handles that for you internally and just feeds your UI with the result sent by the restful Api. Also we created a test url for this application on heroku which we specified in our baseURL
property. We would also be connecting to the /notification
routes. Then we go ahead to connect our entire application to a top level KunyoraProvider component while passing in the client
instance and the store
as props.
Connecting to our data using the Query component
Lets connect our UI to the data from the store using a query component. We would cover all the possible scenarios of using the Query
component here including a render loading and error component and refetching queries.
/**
* NotificationList.js
*/
import React from 'react';
import {Query} from 'react-kunyora';
export default (NotificationList = (props) => (
<Query
operation="getNotification"
renderError={<p>An error just occurred</p>}
renderLoading={<p> Loading... </p>}
options={{fetchPolicy: 'network-only'}}>
{(notifications, fetchMore, refetchQuery) => [
<div key={0}>
{notifications.data.map((notification, i) => (
<li key={i}>{notification.name}</li>
))}
</div>,
<button key={1} onClick={() => refetchQuery()}>
Refresh List
</button>,
]}
</Query>
));
Notice that the above code uses react fragment api
to render 2 children components in the Query
component. The code above queries for a list of notification which it displays in a list and then renders a button that can be used to refetch the query. Lets go ahead to explain the props used in this example.
operation : This prop is used to specify the command to run. Typically in a
get
request, it is formed by camel-casingget
with thename
orpath
attribute supplied by the user when creating theclient
and in our case, this isnotification
. For a full understanding of howoperations
are formed, please refer to the Introduction to operation Docs section for a more detailed explanation.renderError : This prop is used to render a view in case an error occurred while fetching the query. In our case, we render a text which notifies a user that an error just occured.
renderLoading : This prop is used to render a view when the query is in flight. In our case, we render a text
loading...
.options : This prop helps us to specify the configuration of the application. It accepts an object containing 2 properties;
fetchPolicy
andconfig
.fetchPolicy
can be used to specify a fetching pattern that our application should use whileconfig
generally specifies the configuration particular to just the query being sent. In theconfig
property, we can specifyget parameters
that the application should use along with some other custom parameters. In our case, we specify anetwork-only
fetchPolicy. Please refer to the API reference of this docs.
Now, lets go ahead to explain the parameters passed to our this.props.children
of the Query
component.
notifications : This is an object which contains the
error
,loading
and thedata
entities for our query. Theerror
andloading
value of theQuery
component are passed in case you choose to handle error and loading manually yourself within the application instead of using therenderError
and therenderLoading
props.notifications.data
on the other hand, contains the data which has been sent back by your api probably in .json format. In our case, thenotification.data
contains the list of notifications stored in our online database.fetchMore : This is a function used to fetch more results
refetchQuery : This is a function used to refetch a query
The Query
component also uses a lot of other props such as the skip
props to skip queries, and the notification.data
property also contains an isInitialDataSet
boolean field which can tell your application if an initial data has been loaded before by the query or not.
Please refer to the Query Api Overview section of this docs for more details on the Query
component.