Merge pull request #16 from giuseppeg/real-time-updates

real-time updates

README.md

@@ -15,6 +15,7 @@ A set of components and utilities to work faster with [DatoCMS](https://www.dato
 
 - [Demos](#demos)
 - [Installation](#installation)
+- [Live real-time updates](#live-real-time-updates)
 - [Progressive/responsive image](#progressiveresponsive-image)
   - [Out-of-the-box features](#out-of-the-box-features)
   - [Setup](#setup)
@@ -44,6 +45,22 @@ A set of components and utilities to work faster with [DatoCMS](https://www.dato
 npm install vue-datocms
 ```
 
+## Live real-time updates
+
+Thanks to the `subscribeToQuery` helper provided by the [datocms-listen](https://www.npmjs.com/package/datocms-listen) package you can get real-time updates for the page when the content changes. This helper connects to the DatoCMS's [Real-time Updates API](https://www.datocms.com/docs/real-time-updates-api/api-reference) to receive the updated query results in real-time, and is able to reconnect in case of network failures.
+
+Live updates are great both to get instant previews of your content while editing it inside DatoCMS, or to offer real-time updates of content to your visitors (ie. news site).
+
+### Reference
+
+`subscribeToQuery` provides a way to create a subscription to DatoCMS's [Real-time Updates API](https://www.datocms.com/docs/real-time-updates-api/api-reference).
+
+Please consult the [datocms-listen package documentation](https://www.npmjs.com/package/datocms-listen) to learn more about how to configure `subscribeToQuery`.
+
+In Vue.js v2, the subscription can be created inside of the [`mounted`](https://vuejs.org/v2/api/#mounted) lifecycle method. Please refer to the [query-subscription example](./examples/query-subscription/src/App.vue#L47) for a sample implementation.
+
+In Vue.js v3, `subscribeToQuery` can be used to implement a custom hook. Please take a look at the [React.js one](https://github.com/datocms/react-datocms/blob/master/src/useQuerySubscription/index.ts) for a sample implementation.
+
 ## Progressive/responsive image
 
 `<datocms-image>` is a Vue component specially designed to work seamlessly with DatoCMS’s [`responsiveImage` GraphQL query](https://www.datocms.com/docs/content-delivery-api/uploads#responsive-images) that optimizes image loading for your sites.

examples/query-subscription/.gitignore

@@ -0,0 +1,21 @@
+.DS_Store
+node_modules
+/dist
+
+# local env files
+.env.local
+.env.*.local
+
+# Log files
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/query-subscription/README.md

@@ -0,0 +1,39 @@
+# query-subscription
+
+Example of using [datocms-listen](https://www.npmjs.com/package/datocms-listen) to implement real-time updates in a Vue.js v2 application.
+
+## Project setup
+```
+npm install
+```
+
+### Compiles and hot-reloads for development
+```
+npm run serve
+```
+
+### Compiles and minifies for production
+```
+npm run build
+```
+
+### Lints and fixes files
+```
+npm run lint
+```
+
+### Customize configuration
+See [Configuration Reference](https://cli.vuejs.org/config/).
+
+## To test locally
+
+Get to the main `vue-datocms` folder and run:
+``` bash
+$ npm link
+```
+
+Then in the `examples/query-subscription` folder run:
+``` bash
+$ npm link vue-datocms
+```
+to use the code from the above folder in the example project.

examples/query-subscription/babel.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  presets: [
+    '@vue/cli-plugin-babel/preset'
+  ]
+}