From cb22867c2a2e475e0ffb39b311faaa72f21e9aad Mon Sep 17 00:00:00 2001 From: rolljee Date: Thu, 21 Mar 2024 16:06:29 +0100 Subject: [PATCH] docs(getting-started): add some getting started --- doc/7/getting-started/index.md | 9 + doc/7/getting-started/node-js/index.md | 157 +++++++++++++ .../node-js/snippets/create.js | 39 ++++ .../node-js/snippets/create.test.yml | 11 + .../getting-started/node-js/snippets/init.js | 37 +++ .../node-js/snippets/init.test.yml | 9 + .../node-js/snippets/load-sdk.js | 9 + .../node-js/snippets/load-sdk.test.yml | 9 + .../node-js/snippets/prepare-db.js | 20 ++ .../node-js/snippets/prepare-db.test.yml | 9 + .../node-js/snippets/subscribe.js | 51 +++++ .../node-js/snippets/subscribe.test.yml | 11 + doc/7/getting-started/raw-web/index.md | 168 ++++++++++++++ .../raw-web/snippets/create.html | 31 +++ .../raw-web/snippets/create.test.yml | 12 + .../raw-web/snippets/load-sdk.html | 14 ++ .../raw-web/snippets/load-sdk.test.yml | 10 + .../raw-web/snippets/prepare-db.html | 29 +++ .../raw-web/snippets/prepare-db.test.yml | 10 + .../raw-web/snippets/subscribe.html | 32 +++ .../raw-web/snippets/subscribe.test.yml | 12 + doc/7/getting-started/webpack/index.md | 212 ++++++++++++++++++ .../webpack/snippets.disabled/create.js | 33 +++ .../webpack/snippets.disabled/create.test.yml | 13 ++ .../webpack/snippets.disabled/init-kuzzle.js | 38 ++++ .../snippets.disabled/init-kuzzle.test.yml | 10 + .../webpack/snippets.disabled/subscribe.js | 49 ++++ .../snippets.disabled/subscribe.test.yml | 14 ++ 28 files changed, 1058 insertions(+) create mode 100644 doc/7/getting-started/index.md create mode 100644 doc/7/getting-started/node-js/index.md create mode 100644 doc/7/getting-started/node-js/snippets/create.js create mode 100644 doc/7/getting-started/node-js/snippets/create.test.yml create mode 100644 doc/7/getting-started/node-js/snippets/init.js create mode 100644 doc/7/getting-started/node-js/snippets/init.test.yml create mode 100644 doc/7/getting-started/node-js/snippets/load-sdk.js create mode 100644 doc/7/getting-started/node-js/snippets/load-sdk.test.yml create mode 100644 doc/7/getting-started/node-js/snippets/prepare-db.js create mode 100644 doc/7/getting-started/node-js/snippets/prepare-db.test.yml create mode 100644 doc/7/getting-started/node-js/snippets/subscribe.js create mode 100644 doc/7/getting-started/node-js/snippets/subscribe.test.yml create mode 100644 doc/7/getting-started/raw-web/index.md create mode 100644 doc/7/getting-started/raw-web/snippets/create.html create mode 100644 doc/7/getting-started/raw-web/snippets/create.test.yml create mode 100644 doc/7/getting-started/raw-web/snippets/load-sdk.html create mode 100644 doc/7/getting-started/raw-web/snippets/load-sdk.test.yml create mode 100644 doc/7/getting-started/raw-web/snippets/prepare-db.html create mode 100644 doc/7/getting-started/raw-web/snippets/prepare-db.test.yml create mode 100644 doc/7/getting-started/raw-web/snippets/subscribe.html create mode 100644 doc/7/getting-started/raw-web/snippets/subscribe.test.yml create mode 100644 doc/7/getting-started/webpack/index.md create mode 100644 doc/7/getting-started/webpack/snippets.disabled/create.js create mode 100644 doc/7/getting-started/webpack/snippets.disabled/create.test.yml create mode 100644 doc/7/getting-started/webpack/snippets.disabled/init-kuzzle.js create mode 100644 doc/7/getting-started/webpack/snippets.disabled/init-kuzzle.test.yml create mode 100644 doc/7/getting-started/webpack/snippets.disabled/subscribe.js create mode 100644 doc/7/getting-started/webpack/snippets.disabled/subscribe.test.yml diff --git a/doc/7/getting-started/index.md b/doc/7/getting-started/index.md new file mode 100644 index 000000000..f8e150478 --- /dev/null +++ b/doc/7/getting-started/index.md @@ -0,0 +1,9 @@ +--- +code: false +type: branch +title: Getting Started +description: Get started with the Javascript SDK +order: 0 +--- + + diff --git a/doc/7/getting-started/node-js/index.md b/doc/7/getting-started/node-js/index.md new file mode 100644 index 000000000..4a535ba6f --- /dev/null +++ b/doc/7/getting-started/node-js/index.md @@ -0,0 +1,157 @@ +--- +code: false +type: page +title: Node.js +description: Getting started with Kuzzle and Node.js +order: 0 +--- + +# Getting Started with Kuzzle and Node.js + +This tutorial explains you how to use **Kuzzle** with **Node.js** and the **Javascript SDK**. +It will walk you through creating scripts that can **store** documents in Kuzzle and subscribe to **notifications** about document creations. + +You are going to write an application that **stores** documents in Kuzzle Server and subscribe to **real time notifications** for each created document. + +To follow this tutorial, you must have a Kuzzle Server up and running. Follow these instructions if this is not already the case: [Running Kuzzle](/core/2/guides/getting-started/run-kuzzle). + + +:::info +Having trouble? Get in touch with us on [Discord](http://join.discord.kuzzle.io)! +::: + +## Explore the SDK + +It's time to get started with the [Kuzzle Javascript SDK](/sdk/js/7). This section, explains you how to store a document and subscribe to notifications in Kuzzle using the Javascript SDK. + +Before proceeding, please make sure your system has **Node.js** version 8 or higher ([download page](https://nodejs.org/en/download/)) installed. + +## Prepare your environment + +Create your playground directory and install the Javascript SDK from the command line using npm: + +```sh +mkdir "kuzzle-playground" +cd "kuzzle-playground" +npm install kuzzle-sdk +``` + +:::info +If you are performing a clean install you might get some `UNMET PEER DEPENDENCY` warnings, these are safe to ignore as they refer to optional dependencies. +::: + +Then, create an `init.js` file and start by adding the code below. +This loads the SDK and connects it to a Kuzzle instance using the WebSocket protocol. + +<<< ./snippets/load-sdk.js + +:::info +Replace 'kuzzle' which is the Kuzzle server hostname with 'localhost' or with the host name where your Kuzzle server is running. +::: + +Next, add a listener to be notified in case of a connection error: + +```js +kuzzle.on('networkError', error => { + console.error('Network Error: ', error); +}); +``` + +Then, connect the client to your Kuzzle server with the `connect()` method, afterwards you have to add the code that will access Kuzzle to create a new index 'nyc-open-data' and a new collection 'yellow-taxi' that you will use to store data later on. + +<<< ./snippets/prepare-db.js + +Your `init.js` file should now look like this: + +<<< ./snippets/init.js + +This code does the following: + +- loads the `Kuzzle SDK` from its NPM package +- creates an instance of the SDK +- connects it to Kuzzle running on `kuzzle` (change the hostname if needed) using WebSocket +- creates the `nyc-open-data` index +- creates the `yellow-taxi` collection (within the `nyc-open-data` index), +- disconnects from Kuzzle after the collection is created or if an error occurs + +Run the code with Node.js: + +```bash +node init.js +``` + +The console should output the following message: + +```bash +nyc-open-data/yellow-taxi ready! +``` + +:::success +Congratulations! You are now ready to say Hello to the World! +::: + +## Create your first "Hello World" document + +Create a `create.js` file with the following code: + +<<< ./snippets/create.js + +This code does the following: + +- creates a new document in the `yellow-taxi` collection, within the `nyc-open-data` index +- logs a success message to the console if everything went fine +- logs an error message if any of the previous actions fails +- disconnects from Kuzzle after the document is created or if an error occurs + +Run the code with Node.js: + +```bash +node create.js +``` + +:::success +You have now successfully stored your first document into Kuzzle. You can now open an [Admin Console](http://console.kuzzle.io) to browse your collection and confirm that your document was saved. +::: + + +## Subscribe to realtime document notifications (pub/sub) + +Kuzzle provides pub/sub features that can be used to trigger real-time notifications based on the state of your data (for a deep-dive on notifications check out the [realtime notifications](/sdk/js/7/essentials/realtime-notifications) documentation). + +Let's get started. Create a `subscribe.js` file with the following code: + +<<< ./snippets/subscribe.js + +Run the code with Node.js: + +```bash +node subscribe.js +``` + +The `subscribe.js` program is now running endlessly, waiting for notifications about documents matching its filters, specifically documents that have a `license` field equal to `'B'`. + +Now in another terminal, launch the `create.js` file from the previous section. + +```bash +node create.js +``` + +This creates a new document in Kuzzle which, in turn, triggers a [document notification](/core/2/api/payloads/notifications#document-notification) sent to the `subscribe.js` program. +Check the `subscribe.js` terminal: a new message is printed everytime a document is created using the `create.js` code. + +```bash +New driver Sirkis with id AWccRe3-DfukVhSzMdUo has B license. +``` + +:::success +Congratulations! You have just set up your first pub/sub communication! +::: + +## Where do we go from here? + +Now that you're more familiar with Kuzzle, dive even deeper to learn how to leverage its full capabilities: + +- discover what this SDK has to offer by browsing other sections of this documentation +- learn how to use [Koncorde](/core/2/api/koncorde-filters-syntax) to create incredibly fine-grained and blazing-fast subscriptions +- learn how to perform a [basic authentication](/sdk/js/7/controllers/auth/login) +- follow our guide to learn how to [manage users, and how to set up fine-grained access control](/core/2/guides/main-concepts/permissions) diff --git a/doc/7/getting-started/node-js/snippets/create.js b/doc/7/getting-started/node-js/snippets/create.js new file mode 100644 index 000000000..abd761b20 --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/create.js @@ -0,0 +1,39 @@ +// Loads the Kuzzle SDK modules +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client with the WebSocket protocol +// Replace 'kuzzle' with your Kuzzle server hostname (e.g. 'localhost') +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); + +// Adds a listener to detect connection problems +kuzzle.on('networkError', error => { + console.error('Network Error:', error); +}); + +const run = async () => { + try { + // Connects to the Kuzzle server + await kuzzle.connect(); + + // Creates a document + const driver = { + name: 'Sirkis', + birthday: '1959-06-22', + license: 'B' + }; + + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', driver); + console.log('New document successfully created!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; + +run(); diff --git a/doc/7/getting-started/node-js/snippets/create.test.yml b/doc/7/getting-started/node-js/snippets/create.test.yml new file mode 100644 index 000000000..910484f25 --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/create.test.yml @@ -0,0 +1,11 @@ +name: gettingstarted#nodejscreate +description: Creates a document +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: empty +expected: New document successfully created! +sdk: js +version: 6 diff --git a/doc/7/getting-started/node-js/snippets/init.js b/doc/7/getting-started/node-js/snippets/init.js new file mode 100644 index 000000000..fd0a31384 --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/init.js @@ -0,0 +1,37 @@ +// Loads the Kuzzle SDK modules +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client with the WebSocket protocol +// Replace 'kuzzle' with your Kuzzle server hostname (e.g. 'localhost') +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); + +// Adds a listener to detect connection problems +kuzzle.on('networkError', error => { + console.error('Network Error:', error); +}); + +const run = async () => { + try { + // Connects to the Kuzzle server + await kuzzle.connect(); + + // Creates an index + await kuzzle.index.create('nyc-open-data'); + + // Creates a collection + await kuzzle.collection.create('nyc-open-data', 'yellow-taxi'); + + console.log('nyc-open-data/yellow-taxi ready!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; + +run(); diff --git a/doc/7/getting-started/node-js/snippets/init.test.yml b/doc/7/getting-started/node-js/snippets/init.test.yml new file mode 100644 index 000000000..0e76545bc --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/init.test.yml @@ -0,0 +1,9 @@ +name: gettingstarted#nodejsinit +description: Creates an index and a collection +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: empty +expected: nyc-open-data/yellow-taxi ready! +sdk: js +version: 6 diff --git a/doc/7/getting-started/node-js/snippets/load-sdk.js b/doc/7/getting-started/node-js/snippets/load-sdk.js new file mode 100644 index 000000000..ae17a9b0e --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/load-sdk.js @@ -0,0 +1,9 @@ +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Replace 'kuzzle' with your Kuzzle server hostname (e.g. 'localhost') +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); diff --git a/doc/7/getting-started/node-js/snippets/load-sdk.test.yml b/doc/7/getting-started/node-js/snippets/load-sdk.test.yml new file mode 100644 index 000000000..0d32da204 --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/load-sdk.test.yml @@ -0,0 +1,9 @@ +name: gettingstarted#nodejsload +description: Load SDK +hooks: + before: + after: +template: empty +expected: Success +sdk: js +version: 6 diff --git a/doc/7/getting-started/node-js/snippets/prepare-db.js b/doc/7/getting-started/node-js/snippets/prepare-db.js new file mode 100644 index 000000000..2fb9b8410 --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/prepare-db.js @@ -0,0 +1,20 @@ +const run = async () => { + try { + // Connects to the Kuzzle server + await kuzzle.connect(); + + // Creates an index + await kuzzle.index.create('nyc-open-data'); + + // Creates a collection + await kuzzle.collection.create('nyc-open-data', 'yellow-taxi'); + + console.log('nyc-open-data/yellow-taxi ready!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; + +run(); diff --git a/doc/7/getting-started/node-js/snippets/prepare-db.test.yml b/doc/7/getting-started/node-js/snippets/prepare-db.test.yml new file mode 100644 index 000000000..e51b6f7ce --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/prepare-db.test.yml @@ -0,0 +1,9 @@ +name: gettingstarted#nodejspreparedb +description: Prepare database +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: blank +expected: nyc-open-data/yellow-taxi ready! +sdk: js +version: 6 diff --git a/doc/7/getting-started/node-js/snippets/subscribe.js b/doc/7/getting-started/node-js/snippets/subscribe.js new file mode 100644 index 000000000..f85d66357 --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/subscribe.js @@ -0,0 +1,51 @@ +// Loads the Kuzzle SDK modules +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client with the WebSocket protocol +// Replace 'kuzzle' with your Kuzzle server hostname (e.g. 'localhost') +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); + +// Adds a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error('Network Error:', error); +}); + +const run = async () => { + try { + // Connects to the Kuzzle server + await kuzzle.connect(); + + // Defines a filter + const filter = { + equals: { license: 'B' } + }; + + // Defines a callback invoked each time a notification is received + const callback = (notification) => { + + if (notification.type === 'document' && notification.action === 'create') { + const { + _source: driver, + _id: driverId + } = notification.result; + + console.log(`New driver ${driver.name} with id ${driverId} has B license.`); + kuzzle.disconnect(); + } + }; + + // Subscribes to document notifications using the above filter + await kuzzle.realtime.subscribe('nyc-open-data', 'yellow-taxi', filter, callback); + + console.log('Successfully subscribed to document notifications!'); + } catch (error) { + console.error(error.message); + } +}; + +run(); diff --git a/doc/7/getting-started/node-js/snippets/subscribe.test.yml b/doc/7/getting-started/node-js/snippets/subscribe.test.yml new file mode 100644 index 000000000..5e6720558 --- /dev/null +++ b/doc/7/getting-started/node-js/snippets/subscribe.test.yml @@ -0,0 +1,11 @@ +name: gettingstarted#nodejssubscribe +description: Subscribes to document notifications +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: empty-realtime +expected: Successfully subscribed to document notifications! +sdk: js +version: 6 diff --git a/doc/7/getting-started/raw-web/index.md b/doc/7/getting-started/raw-web/index.md new file mode 100644 index 000000000..371819a4c --- /dev/null +++ b/doc/7/getting-started/raw-web/index.md @@ -0,0 +1,168 @@ +--- +code: false +type: page +title: Browser (Vanilla) +description: Getting started with Kuzzle in the browser +order: 100 +--- + +# Getting Started with Kuzzle in the browser + +This tutorial explains how to use **Kuzzle** with the **Javascript SDK** in a **browser**. + +To follow this tutorial, you must have a Kuzzle Server up and running (you'll need to know the hostname of the machine running it). If this is not already the case, take a look at [how to run Kuzzle](/core/2/guides/getting-started/run-kuzzle). + +Before proceeding, make sure your system has **Node.js** version 8 or higher ([download page](https://nodejs.org/en/download/)) installed. + +In this tutorial, you'll learn how to **store** a document and **subscribe** to notifications in Kuzzle using the Javascript SDK. + +:::info +Having trouble? Get in touch with us on [Discord](http://join.discord.kuzzle.io)! +::: + +## Prepare your environment + +Create your playground directory: + +```sh +mkdir "kuzzle-playground" +cd "kuzzle-playground" +``` + +:::info +If you are performing a clean install you might get some `UNMET PEER DEPENDENCY` warnings, these are safe to ignore as they refer to optional dependencies. +::: + +Then, create an `index.html` file with the following structure: + +```html + + + + + + Kuzzle SDK Playground + + + + + + + + +``` + +:::info +If you are using Internet Explorer (not Edge), you are responsible of installing a Promise polyfill, which enables IE to support +Javascript [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). +Our advice is to use [Bluebird](http://bluebirdjs.com/docs/getting-started.html), as shown in the code example above (refer to the commented lines in the `head` tag). +::: + +Then, add the code below in the `body` tag. +This loads the SDK and connects it to a Kuzzle instance using the WebSocket protocol. If an error occurs, it is displayed +in the console. Once the connection is established, a success message is displayed in the console. + +<<< ./snippets/load-sdk.html + +:::info +Replace `kuzzle` with localhost or with the host name where your Kuzzle server is running. +::: + +Now you have to add the code that will access Kuzzle to create a new index `nyc-open-data` and a new collection `yellow-taxi` +that you will use to store data later on. Make sure the code inside your `body` tag looks like the following: + +<<< ./snippets/prepare-db.html + +Now, let's take a look at what your script is doing: + +- creates an instance of the SDK, +- connects it to Kuzzle running on `kuzzle` (change the hostname if needed) using WebSocket, +- creates the `nyc-open-data` index, +- creates the `yellow-taxi` collection (within the `nyc-open-data` index), +- disconnects from Kuzzle after the collection is created, +- displays an error whenever something goes wrong. + +Run this code by opening the `index.html` file in your favorite browser. +The console should output the following message: + +``` +Successfully connected to Kuzzle +nyc-open-data/yellow-taxi ready! +``` + +:::success +Congratulations! You are now ready to say Hello to the World! +::: + +:::info +If you reload the page, you should see an error in the console. This is OK, since Kuzzle is just refusing to create +the `nyc-open-data` index as it already exists. +::: + +## Create your first "Hello World" document + +Create a `create.html` file with the same structure as `index.html` (see above). +And, right like before, add some code to the `body` tag: + +<<< ./snippets/create.html + +This code does the following: + +- creates an instance of the SDK, +- connects it to Kuzzle running on `kuzzle` (change the hostname if needed) using WebSocket, +- creates a new document in the `yellow-taxi` collection, within the `nyc-open-data` index +- logs a success message to the console if everything went fine +- logs an error message if any of the previous actions fails +- disconnects from Kuzzle after the document is created or if an error occurs + +Run this code by opening the `create.html` file in your favorite browser. +The console should output the following message: + +``` +Successfully connected to Kuzzle +New document successfully created! +``` + +:::success +You have now successfully stored your first document into Kuzzle. Check our [Admin Console Guide](http://next-console.kuzzle.io) to see how to browse your collection and confirm that your document was saved. +::: + + +## Subscribe to realtime document notifications (pub/sub) + +Kuzzle provides pub/sub features that can be used to trigger real-time notifications based on the state of your data (for a deep-dive on notifications check out the [realtime notifications](/sdk/js/7/essentials/realtime-notifications) documentation). + +Let's get started. Create a `subscribe.html` file (same structure as above) with the following code in the `body` tag: + +<<< ./snippets/subscribe.html + +Run this code by opening the `subscribe.html` file in a new tab, leaving the previous one (showing `create.html`) open. +The console should output the following message: + +``` +Successfully connected to Kuzzle +Successfully subscribed to document notifications! +``` + +The code in the `subscribe.html` page is now running endlessly, waiting for notifications about documents matching its filters, specifically documents that have a `license` field equal to `'B'`. + +Now go back to the other tab and reload `create.html`. + +This creates a new document in Kuzzle which, in turn, triggers a [document notification](/core/2/api/payloads/notifications#document-notification) sent to the `subscribe.html` tab. Check the `subscribe.html` tab: a new message is printed everytime a document is created using the `create.html` code. + +``` +New driver Sirkis with id AWccRe3-DfukVhSzMdUo has B license. +``` + +:::success +Congratulations! You have just set up your first pub/sub communication! +::: + +## Where do we go from here? + +Now that you're more familiar with Kuzzle, dive even deeper to learn how to leverage its full capabilities: + +- discover what this SDK has to offer by browsing other sections of this documentation +- learn how to use [Koncorde](/core/2/api/koncorde-filters-syntax) to create incredibly fine-grained and blazing-fast subscriptions +- learn how to perform a [basic authentication](/sdk/js/7/controllers/auth/login) +- follow our guide to learn how to [manage users, and how to set up fine-grained access control](/core/2/guides/main-concepts/permissions) diff --git a/doc/7/getting-started/raw-web/snippets/create.html b/doc/7/getting-started/raw-web/snippets/create.html new file mode 100644 index 000000000..70aee4f09 --- /dev/null +++ b/doc/7/getting-started/raw-web/snippets/create.html @@ -0,0 +1,31 @@ + diff --git a/doc/7/getting-started/raw-web/snippets/create.test.yml b/doc/7/getting-started/raw-web/snippets/create.test.yml new file mode 100644 index 000000000..557868de8 --- /dev/null +++ b/doc/7/getting-started/raw-web/snippets/create.test.yml @@ -0,0 +1,12 @@ +name: gettingstarted#browservanillacreate +description: Create a document +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: default +expected: New document successfully created +sdk: js +version: 6 +runner: web diff --git a/doc/7/getting-started/raw-web/snippets/load-sdk.html b/doc/7/getting-started/raw-web/snippets/load-sdk.html new file mode 100644 index 000000000..10d2477d1 --- /dev/null +++ b/doc/7/getting-started/raw-web/snippets/load-sdk.html @@ -0,0 +1,14 @@ + \ No newline at end of file diff --git a/doc/7/getting-started/raw-web/snippets/load-sdk.test.yml b/doc/7/getting-started/raw-web/snippets/load-sdk.test.yml new file mode 100644 index 000000000..c17ef17d8 --- /dev/null +++ b/doc/7/getting-started/raw-web/snippets/load-sdk.test.yml @@ -0,0 +1,10 @@ +name: gettingstarted#browservanillaconnect +description: Connect to Kuzzle +hooks: + before: + after: +template: default +expected: Successfully connected to Kuzzle +sdk: js +version: 6 +runner: web diff --git a/doc/7/getting-started/raw-web/snippets/prepare-db.html b/doc/7/getting-started/raw-web/snippets/prepare-db.html new file mode 100644 index 000000000..c392a86b4 --- /dev/null +++ b/doc/7/getting-started/raw-web/snippets/prepare-db.html @@ -0,0 +1,29 @@ + \ No newline at end of file diff --git a/doc/7/getting-started/raw-web/snippets/prepare-db.test.yml b/doc/7/getting-started/raw-web/snippets/prepare-db.test.yml new file mode 100644 index 000000000..3ac1c5a75 --- /dev/null +++ b/doc/7/getting-started/raw-web/snippets/prepare-db.test.yml @@ -0,0 +1,10 @@ +name: gettingstarted#browservanillaprepare +description: Prepare the database +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: default +expected: nyc-open-data/yellow-taxi ready +sdk: js +version: 6 +runner: web diff --git a/doc/7/getting-started/raw-web/snippets/subscribe.html b/doc/7/getting-started/raw-web/snippets/subscribe.html new file mode 100644 index 000000000..ec6c858ab --- /dev/null +++ b/doc/7/getting-started/raw-web/snippets/subscribe.html @@ -0,0 +1,32 @@ + \ No newline at end of file diff --git a/doc/7/getting-started/raw-web/snippets/subscribe.test.yml b/doc/7/getting-started/raw-web/snippets/subscribe.test.yml new file mode 100644 index 000000000..2fad572cd --- /dev/null +++ b/doc/7/getting-started/raw-web/snippets/subscribe.test.yml @@ -0,0 +1,12 @@ +name: gettingstarted#browservanillasubscribe +description: Subscribe to notifications +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: default +expected: Successfully subscribed to document notifications +sdk: js +version: 6 +runner: web diff --git a/doc/7/getting-started/webpack/index.md b/doc/7/getting-started/webpack/index.md new file mode 100644 index 000000000..5d7b5a444 --- /dev/null +++ b/doc/7/getting-started/webpack/index.md @@ -0,0 +1,212 @@ +--- +type: page +code: false +title: Webpack +description: Getting started with Kuzzle and Webpack +order: 200 +--- + +# Getting Started with Kuzzle and Webpack + +In this tutorial you will learn how to install, run and use **Kuzzle** with the **Javascript SDK** in the browser using **Webpack**. +We will walk you through creating scripts that can **store** documents in Kuzzle and subscribe to **notifications** for each new document created. + +:::info +Having trouble? Get in touch with us on [Discord](http://join.discord.kuzzle.io)! +::: + +## Running Kuzzle + +Before going through this tutorial, you should have a Kuzzle server running. Please refer to the [Running Kuzzle Tutorial](/core/2/guides/getting-started/run-kuzzle) if you don't have one yet. + +## Fun with the SDK + +It's time to play with the [Kuzzle Javascript SDK](/sdk/js/7). In this section, we will store a document and subscribe to notifications in Kuzzle using the Javascript SDK in your browser. + +Before proceeding, please make sure your system has **Node.js** version 8 or higher ([instructions here](https://nodejs.org/en/download/)) installed. + +## Including the Kuzzle SDK in a Webpack project + +::: info +This section explains how to use the Kuzzle SDK within an existing Webpack project. +If you don't have your project up and running yet and want to learn how to leverage Webpack to build it, please refer to +the [official Webpack Getting Started page](https://webpack.js.org/guides/getting-started). +::: + +In your terminal, go to the root of your front-end project using Webpack and type + +```bash +npm install kuzzle-sdk +``` + +:::info +If you are performing a clean install you might see some `UNMET PEER DEPENDENCY` warnings, these are safe to ignore as they refer to optional dependencies. +::: + +Then, create a `init-kuzzle.js` file and start by adding the code below. This will load the Kuzzle Javascript SDK: + +<<< ./snippets/init-kuzzle.js:1 + +Next, we instantiate a client that will connect to Kuzzle via WebSocket. If Kuzzle is not running on localhost, replace it with the corresponding server name or IP address. + +<<< ./snippets/init-kuzzle.js:2 + +Next we add a listener to be notified in case of a connection error: + +<<< ./snippets/init-kuzzle.js:3 + +Then we have to connect our web app to the Kuzzle server with the `connect()` method. + +```js +const run = async () => { + try { + // Connect to Kuzzle server + await kuzzle.connect(); + // Some more things will go here... + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; +``` + +Finally, we will create a new index `nyc-open-data` and a new collection +`yellow-taxi` that we will use to store data later on. + +<<< ./snippets/init-kuzzle.js:4 + +Your `kuzzle-init.js` file should now look like this: + +<<< ./snippets/init-kuzzle.js + +This code does the following: + +- loads the `kuzzle-sdk` from its NPM package +- creates an instance of the SDK +- connects it to Kuzzle running on `localhost` with the `WebSocket` protocol +- creates the `nyc-open-data` index +- creates the `yellow-taxi` collection (within the `nyc-open-data` index), +- disconnects from Kuzzle after the collection is created or if an error occurs + +Now, to have your script up and running, require it somewhere in your application +(e.g. your main entry point) and launch it. + +```js +require('../path/to/init-kuzzle.js'); +``` + +Your console should output the following message: + +``` +nyc-open-data/yellow-taxi ready! +``` + +::: success +Congratulations! You are now ready to say Hello to the World! +::: + +::: info +Having trouble? Get in touch with us on [Discord!](http://join.discord.kuzzle.io) We're happy to help. +::: + +## Create your first document + +Create a `create.js` file with following code: + +<<< ./snippets/create.js + +This code does the following: + +- creates a new document in `nyc-open-data` within the `yellow-taxi` index +- logs a success message to the console if everything went fine +- logs an error message if any of the previous actions failed +- disconnects from Kuzzle after the document is created or if an error occurs + +To activate this code, create a button somewhere in your page like the following + +```html + +``` + +Then, associate it to the `create` function by adding this code to your application + +```js +const create = require('../path/to/create.js'); + +// This is the most "vanilla" way to call a function in reaction to a click, +// if you're using a front-end framework like Vuejs, React or jQuery, feel free +// to follow any convenience method it provides for this purpose. +document.querySelector('#create-document-btn').addListener('click', event => { + create(); +}); +``` + +Now, click the button and check your console for a message like the following: + +```bash +New document successfully created! +``` + +::: success +You have now successfully stored your first document into Kuzzle. Click +[here](http://next-console.kuzzle.io) to see how you can use the +[**Kuzzle Admin Console**](http://console.kuzzle.io) to browse your collection and +confirm that your document was saved. +::: + +::: info +Having trouble? Get in touch with us on [Discord!](http://join.discord.kuzzle.io) We're happy to help. +::: + +## Subscribe to realtime document notifications (pub/sub) + +Kuzzle provides pub/sub features that can be used to trigger real-time notifications based on the state of your data (for a deep-dive on notifications check out the [realtime notifications](/sdk/js/7/essentials/realtime-notifications) documentation). + +Let's get started. Create a `subscribe.js` file with following code: + +<<< ./snippets/subscribe.js + +This code does the following: + +- loads the `Kuzzle SDK` from its NPM package +- creates an instance of the SDK +- connects it to Kuzzle running on `localhost` with the `websocket` protocol +- defines a filter for the subscription to be done later (drivers with "B" license) +- defines a callback that will be called whenever a notification is received from Kuzzle (print driver name to console) +- subscribes for notifications on the `yellow-taxi` collection + +You can execute this code in the same page as before or in another page of your app. Whatever option you choose, to +execute the code, you just need to require it in your page + +```js +require('../path/to/subscribe.js'); +``` + +From now on, whenever you click the button we created before, Kuzzle will send a notification to the page containing +the subscription to the `yellow-taxi` collection. In the console corresponding to this page, you should see the following message: + +```bash +New driver Sirkis with id has B license. +``` + +In place of `` you'll see the ID that Kuzzle automatically generated for the document. + +::: success +Congratulations! You have just choreographed your first pub/sub pattern! +::: + +::: info +Having trouble? Get in touch with us on [Discord!](http://join.discord.kuzzle.io) We're happy to help. +::: + +## Where do we go from here? + +Now that you're more familiar with Kuzzle, dive even deeper to learn how to leverage its full capabilities: + +- take a look at the [SDK Reference](/sdk/js/7) +- learn how to use [Koncorde](/core/2/api/koncorde-filters-syntax) to create incredibly fine-grained and blazing-fast subscriptions +- follow our guide to learn how to implement [basic authentication](/core/2/guides/main-concepts/authentication#local-strategy) +- follow our guide to learn how to implement [manage users and setup fine-grained access control](/core/2/guides/main-concepts/permissions) diff --git a/doc/7/getting-started/webpack/snippets.disabled/create.js b/doc/7/getting-started/webpack/snippets.disabled/create.js new file mode 100644 index 000000000..fe66ca6b5 --- /dev/null +++ b/doc/7/getting-started/webpack/snippets.disabled/create.js @@ -0,0 +1,33 @@ +// load the Kuzzle SDK module +import { Kuzzle, WebSocket } from 'kuzzle-sdk'; + +// instantiate a Kuzzle client +const kuzzle = new Kuzzle(new WebSocket('kuzzle')); + +// add a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error}`); +}); + +const doIt = async () => { + try { + // Connect to Kuzzle server + await kuzzle.connect(); + + // Create your document + const driver = { + name: 'Sirkis', + birthday: '1959-06-22', + license: 'B' + }; + + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', driver); + console.log('New document successfully created!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; + +export default doIt; diff --git a/doc/7/getting-started/webpack/snippets.disabled/create.test.yml b/doc/7/getting-started/webpack/snippets.disabled/create.test.yml new file mode 100644 index 000000000..fb4561210 --- /dev/null +++ b/doc/7/getting-started/webpack/snippets.disabled/create.test.yml @@ -0,0 +1,13 @@ +name: gettingstarted#webpackcreate +description: Creates a document +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: doIt +expected: New document successfully created! + +runner: webpack +sdk: js +version: 6 diff --git a/doc/7/getting-started/webpack/snippets.disabled/init-kuzzle.js b/doc/7/getting-started/webpack/snippets.disabled/init-kuzzle.js new file mode 100644 index 000000000..dd8476b40 --- /dev/null +++ b/doc/7/getting-started/webpack/snippets.disabled/init-kuzzle.js @@ -0,0 +1,38 @@ +// load the Kuzzle SDK module +/* snippet:start:1 */ +import { Kuzzle, WebSocket } from 'kuzzle-sdk'; +/* snippet:end */ + +// instantiate a Kuzzle client +/* snippet:start:2 */ +const kuzzle = new Kuzzle(new WebSocket('kuzzle')); +/* snippet:end */ + +// add a listener to detect any connection problems +/* snippet:start:3 */ +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error}`); +}); +/* snippet:end */ + +/* snippet:start:4 */ +const run = async () => { + try { + // Connect to Kuzzle server + await kuzzle.connect(); + + // Create an index + await kuzzle.index.create('nyc-open-data'); + + // Create a collection + await kuzzle.collection.create('nyc-open-data', 'yellow-taxi'); + console.log('nyc-open-data/yellow-taxi ready!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; +/* snippet:end */ + +run(); diff --git a/doc/7/getting-started/webpack/snippets.disabled/init-kuzzle.test.yml b/doc/7/getting-started/webpack/snippets.disabled/init-kuzzle.test.yml new file mode 100644 index 000000000..cd2ff4589 --- /dev/null +++ b/doc/7/getting-started/webpack/snippets.disabled/init-kuzzle.test.yml @@ -0,0 +1,10 @@ +name: gettingstarted#webpackinitkuzzle +description: Creates an index and a collection +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: empty +expected: nyc-open-data/yellow-taxi ready! +sdk: js +version: 6 +runner: webpack diff --git a/doc/7/getting-started/webpack/snippets.disabled/subscribe.js b/doc/7/getting-started/webpack/snippets.disabled/subscribe.js new file mode 100644 index 000000000..892c99bcb --- /dev/null +++ b/doc/7/getting-started/webpack/snippets.disabled/subscribe.js @@ -0,0 +1,49 @@ +// load the Kuzzle SDK module +import { Kuzzle, WebSocket } from 'kuzzle-sdk'; + +// instantiate a Kuzzle client +const kuzzle = new Kuzzle(new WebSocket('kuzzle')); + +// add a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error}`); +}); + +const doIt = async () => { + try { + // Connect to Kuzzle server + await kuzzle.connect(); + + // Define a filter + const filter = { + equals: { license: 'B' } + }; + + // Define a callback + const callback = notification => { + if ( + notification.type === 'document' && + notification.action === 'create' + ) { + const driver = notification.result._source; + const driverId = notification.result._id; + console.log( + `New driver ${driver.name} with id ${driverId} has B license.` + ); + } + }; + + // Subscribes to document notifications with our filter + await kuzzle.realtime.subscribe( + 'nyc-open-data', + 'yellow-taxi', + filter, + callback + ); + console.log('Successfully subscribed to document notifications!'); + } catch (error) { + console.error(error.message); + } +}; + +doIt(); diff --git a/doc/7/getting-started/webpack/snippets.disabled/subscribe.test.yml b/doc/7/getting-started/webpack/snippets.disabled/subscribe.test.yml new file mode 100644 index 000000000..f62f51a44 --- /dev/null +++ b/doc/7/getting-started/webpack/snippets.disabled/subscribe.test.yml @@ -0,0 +1,14 @@ +name: gettingstarted#webpacksubscribe +description: Subscribes to document notifications +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: createDocumentAfterSnippet +expected: + - Successfully subscribed to document notifications! + - New driver Sirkis with id +sdk: js +version: 6 +runner: webpack