initial implementation of withQuery()

Author: theodorDiaconu

CHANGELOG.md

@@ -1,3 +1,6 @@
+### 0.1.0
+- Moved to withQuery() functionality
+
 ### 0.0.5
 - Improved stability
 

README.md

@@ -1,41 +1,234 @@
-Grapher-React Components
-========================
+## Grapher React Components
 
 Using the [cultofcoders:grapher](https://github.com/cult-of-coders/grapher) query component in React.
 
-createQueryContainer
---------------------
+### Installation
+```bash
+meteor add cultofcoders:grapher-react
+```
+
+
+### Signature
+
 ```js
-// TaskList.jsx
-import React from 'react';
-import Tasks from '/imports/api/tasks/collection.js';
-import { createQueryContainer } from 'meteor/cultofcoders:grapher-react';
+withQuery(() => query, config)(Component)
+```
+
+The first function needs to return a valid Query or NamedQuery from Grapher.
 
-const query = Tasks.createQuery({
-    title: 1,
-});
+### Configuration:
 
-const TaskList = ({loading, error, tasks}) => (
-  <div>
-    {
-      _.map(tasks, task => <div key={task._id}>{task.title}</div>)
+<table>
+  <tr>
+    <th>Property</th>
+    <th>Valid values</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>reactive</td>
+    <td>true/false</td>
+    <td>
+        Defaults to `false`.
+        Makes your query reactive (subscribes to changes) or non-reactive, falls back to method calls.
+    </td>
+  </tr>
+  <tr>
+    <td>errorComponent</td>
+    <td>React.Component (optional)</td>
+    <td>Defaults to `null`. Receives `error` object as a prop. Is rendered when subscription or method call triggered an exception</td>
+  </tr>
+  <tr>
+    <td>loadingComponent</td>
+    <td>React.Component (optional)</td>
+    <td>Defaults to `null`. Renders when the data is waiting to be loaded from the server</td>
+  </tr>
+  <tr>
+    <td>single</td>
+    <td>true/false</td>
+    <td>Defaults to `false`. If your query is for a single result, then using `true` will send data as an object instead of an array</td>
+  </tr>
+</table>
+
+### Simple Usage
+
+```jsx harmony
+import React from 'react';
+import {withQuery} from 'meteor/cultofcoders:grapher-react';
+
+const PostList = ({data, isLoading, error}) => {
+    if (isLoading) {
+        return <div>Loading</div>
+    }
+    
+    if (error) {
+        return <div>{error.reason}</div>
     }
-  </div>    
-);
+    
+    return (
+        <div>
+            {data.map(post => <li key={post._id}>{post.title}</li>)}
+        </div>
+    )
+}
 
-export default createQueryContainer(query, TaskList, {
-    reactive: true, // defaults to false, will use pub/sub system
-    dataProp: 'tasks', // defaults to 'data'
-    single: false, // defaults to false, when you expect a single document, like you filter by _id, use this. 
-});
+export default withQuery((props) => {
+    return getPostLists.clone();
+})(PostList)
 ```
 
-You can pass params directly in the constructor, these params will be passed to the query.
+### Props Received
 
-```js
-import TaskList from './Tasks.jsx';
+Below are the properties received by the component we wrap, in the example above, that's `PostList`
+
+<table>
+  <tr>
+    <th>Property</th>
+    <th>Valid values</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>isLoading</td>
+    <td>true/false</td>
+    <td>
+        Lets your component know whether the data is waiting to be loaded.
+    </td>
+  </tr>
+  <tr>
+    <td>error</td>
+    <td>Meteor.Error</td>
+    <td>Represents the error triggered from your method or publication. Is falsy if it's not the case.</td>
+  </tr>
+  <tr>
+    <td>refetch</td>
+    <td>Function</td>
+    <td>For non-reactive queries it passes a refetch function for convenience to help you easily reload the data.</td>
+  </tr>
+  <tr>
+    <td>query</td>
+    <td>Query/NamedQuery</td>
+    <td>For your convenience, if you ever need the query for any reason, it's passed in there so you can access it.</td>
+  </tr>
+  <tr>
+    <td>...props</td>
+    <td></td>
+    <td>The props you pass to withQuery, are passed down to the component it wraps</td>
+  </tr>
+</table>
+
+### 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)
+```
 
-export default () => {
-    return <TaskList params={{isActive: true}} anyOtherProp="willBePassedToComponent" />
+As mentioned above, the props received are passed down to the component we wrap, meaning:
+
+```jsx harmony
+const PostList = ({data, something}) => {
+    return <div>Something is true!</div>
+};
+
+const Container = withQuery((props) => {
+    return getPostLists.clone();
+}, {reactive: true})(PostList);
+
+export default function () {
+    return <Container something={true} />;
 }
 ```
+
+
+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 (
+        <div>
+            <a onClick={refetch}>Reload the data</a>
+            {/* Rest of the component */}
+        </div>
+    )
+}
+
+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 (
+        <div>{data.email}</div>
+    )
+};
+
+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 isLoading or it errored. For this you can do:
+```jsx harmony
+function ErrorComponent({error}) {
+    return <div>{error.reason}</div>
+};
+
+function LoadingComponent() {
+    return <div>Please wait...</div>
+};
+
+const UserProfile = ({data}) => {
+    return (
+        <div>{data.email}</div>
+    )
+}
+
+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
+})
+```
+
+If you need custom behavior for a specific component for `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)
+```

defaults.js

@@ -0,0 +1,4 @@
+export default {
+    reactive: false,
+    single: false,
+}

grapher-react.js

@@ -2,11 +2,9 @@ import React from 'react';
 import {createContainer} from 'meteor/react-meteor-data';
 
 export default (query, component, options = {}) => {
-    (new SimpleSchema({
-        reactive: {type: Boolean, defaultValue: false},
-        single: {type: Boolean, defaultValue: false},
-        dataProp: {type: String, defaultValue: 'data'}
-    })).clean(options);
+    if (Meteor.isDevelopment) {
+        console.warn('createQueryContainer() is deprecated, please use withQuery() instead')
+    }
 
     if (options.reactive) {
         return createContainer((props) => {

lib/createQueryContainer.js legacy/createQueryContainer.js

@@ -0,0 +1,40 @@
+import {withTracker} from 'meteor/react-meteor-data';
+
+/**
+ * Wraps the query and provides reactive data fetching utility
+ *
+ * @param props
+ * @param handler
+ * @param config
+ * @param queryContainer
+ */
+export default function createReactiveContainer(props, handler, config, queryContainer) {
+    let subscriptionError;
+
+    return withTracker((props) => {
+        const query = handler(props);
+
+        const subscriptionHandle = query.subscribe({
+            onStop(err) {
+                if (err) {
+                    subscriptionError = err;
+                }
+            },
+            onReady() {
+                subscriptionError = null;
+            }
+        });
+
+        const isReady = subscriptionHandle.ready();
+
+        return {
+            grapher: {
+                isLoading: !isReady,
+                data: query.fetch(),
+                error: subscriptionError,
+            },
+            config,
+            props,
+        }
+    })(queryContainer)
+}

lib/createReactiveContainer.js

@@ -0,0 +1,19 @@
+import React from 'react';
+
+/**
+ * Wraps the query and provides static data fetching utility
+ *
+ * @param props
+ * @param handler
+ * @param config
+ * @param staticQueryContainer
+ */
+export default function createStaticContainer(props, handler, config, staticQueryContainer) {
+    const query = handler(props);
+
+    return React.createElement(staticQueryContainer, {
+        query,
+        props,
+        config
+    })
+}

lib/createStaticContainer.js

@@ -0,0 +1,3 @@
+export default function getDisplayName(WrappedComponent) {
+    return WrappedComponent.displayName || WrappedComponent.name || 'Component';
+}