https://github.com/cult-of-coders/grapher-react
Provides easy to use React Components that are suitable for grapher package.
https://github.com/cult-of-coders/grapher-react
Last synced: 5 months ago
JSON representation
Provides easy to use React Components that are suitable for grapher package.
- Host: GitHub
- URL: https://github.com/cult-of-coders/grapher-react
- Owner: cult-of-coders
- Created: 2016-09-15T13:35:14.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2023-12-15T09:48:12.000Z (over 1 year ago)
- Last Synced: 2024-04-11T22:26:49.848Z (about 1 year ago)
- Language: JavaScript
- Homepage: https://atmospherejs.com/cultofcoders/grapher-react
- Size: 45.9 KB
- Stars: 39
- Watchers: 7
- Forks: 19
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
## Grapher React Components
Using the [cultofcoders:grapher](https://github.com/cult-of-coders/grapher) query component in React.
### Installation
```bash
meteor add cultofcoders:grapher-react
```
### Signature
```js
withQuery(() => query, options)(Component);
```
The first function needs to return a valid `Query` or `NamedQuery` from Grapher.
```js
// This is a query
const query = createQuery({
users: {
emails: 1,
},
});
// This is a named query
const query = createQuery('usersWithEmails', {
users: {
emails: 1,
},
});
```
### Options
Property
Valid values
Default value
Description
reactive
true/false
`false`
Makes your query reactive (subscribes to changes) or non-reactive, falls back to method calls.
dataProp
string
`'data'`
How to properly inject data in your component, like `users` or `posts`
errorComponent
React.Component (optional)
`null`
Receives `error` object as a prop. Is rendered when subscription or method call triggered an exception
loadingComponent
React.Component (optional)
`null`
Renders when the data is waiting to be loaded from the server
single
true/false
`false`
If your query is for a single result, then using `true` will send data as an object instead of an array
pollingMs
Number
`undefined`
Only works for non-reactive queries, it constantly polls for new data every `pollingMs` miliseconds.
loadOnRefetch
true/false
`true`
For static (`reactive = false`) queries only, sets `isLoading` to true every time you call refetch until the data is loaded. Set this to false to only get `isLoading` on the initial fetch.
shouldRefetch
(currentProps, nextProps) => Boolean
`undefined`
For static queries only, provides a hook into `componentWillReceiveProps` to determine whether the query should be refetched or not. The function will be called with nextProps and currentProps as arguments.
### Simple Usage
```jsx harmony
import React from 'react';
import { withQuery } from 'meteor/cultofcoders:grapher-react';
const PostList = ({ data, isLoading, error }) => {
if (isLoading) {
return
Loading;
}
if (error) {
return
{error.reason};
}
return (
{data.map(post => (
{post.title}
))}
);
};
export default withQuery(props => {
return getPostLists.clone();
})(PostList);
```
### Props Received
Below are the properties received by the component we wrap, in the example above, that's `PostList`
Property
Valid values
Description
isLoading
true/false
Lets your component know whether the data is waiting to be loaded.
error
Meteor.Error
Represents the error triggered from your method or publication. If no error it will be a falsy value.
refetch
Function
For non-reactive queries it passes a refetch function for convenience to help you easily reload the data.
query
Query/NamedQuery
For your convenience, if you ever need the query for any reason, it's passed in there so you can access it.
...props
Object
The props you passed inside withQuery, are passed down to the component it wraps
### Let's react!
The first example uses the query non-reactively (because that is the default). But let's say you want your query to be reactive (react to changes in the database)
```jsx harmony
// ...
export default withQuery(
props => {
return getPostLists.clone();
},
{ reactive: true },
)(PostList);
```
As mentioned above, the props received are passed down to the component we wrap, meaning:
```jsx harmony
const PostList = ({ data, something }) => {
return
Something is true!;
};
const Container = withQuery(
props => {
return getPostLists.clone();
},
{ reactive: true },
)(PostList);
export default function() {
return ;
}
```
The query object is also passed down as a prop, so, if you ever need it you can access it from there.
For a non-reactive query, we also pass `refetch` function as prop, which simply refetches the query from the database,
and updates the components properly:
```jsx harmony
import React from 'react';
import { withQuery } from 'meteor/cultofcoders:grapher-react';
const PostList = ({ data, isLoading, error, refetch }) => {
return (
);
};
export default withQuery(
props => {
return getPostLists.clone();
},
{ reactive: false },
)(PostList);
```
If you container wraps a single object, and not a list of objects, you can configure your query like this:
```jsx harmony
const UserProfile = ({ data, isLoading, error }) => {
return
{data.email};
};
export default withQuery(
props => {
return getUserProfile.clone({ userId: props.userId });
},
{
single: true,
},
)(UserProfile);
```
You will find yourself repeating the same code over and over again for when the query is loading or it has an error. For this you can do:
```jsx harmony
function ErrorComponent({ error }) {
return
{error.reason};
}
function LoadingComponent() {
return
Please wait...;
}
const UserProfile = ({ data }) => {
return
{data.email};
};
export default withQuery(
props => {
return getUserProfile.clone({ userId: props.userId });
},
{
single: true,
errorComponent: ErrorComponent,
loadingComponent: LoadingComponent,
},
)(UserProfile);
```
The `UserProfile` component will not render if it's loading or it errored.
To make things even more simple, you can globally define these rules, and all the components by default will have those options.
```jsx harmony
import { setDefaults } from 'meteor/cultofcoders:grapher-react';
setDefaults({
reactive: false, // you can default it to true
single: false, // doesn't make sense to default this to true
errorComponent: ErrorComponent,
loadingComponent: LoadingComponent,
});
```
You can override the defaults at the `withQuery` level, for example you want different `error` and `loading` components, you can simply do:
```jsx harmony
export default withQuery(
props => {
return getUserProfile.clone({ userId: props.userId });
},
{
errorComponent: null,
loadingComponent: AnotherLoadingComponent,
},
)(UserProfile);
```