Port #284 to 3-dev

src/sdk/js/6/core-classes/base-controller/index.md

@@ -0,0 +1,7 @@
+---
+code: true
+type: branch
+title: BaseController
+description: BaseController object documentation
+order: 500
+---

src/sdk/js/6/core-classes/base-controller/introduction/index.md

@@ -0,0 +1,13 @@
+---
+code: true
+type: page
+title: Introduction
+description: BaseController class
+order: 0
+---
+
+# BaseController
+
+Base class for a [custom SDK controller](/sdk/js/6/essentials/extend-sdk/#define-a-custom-sdk-controller).  
+
+Custom SDK controllers have to extend the `BaseController` class to be added with the [Kuzzle.useController](/sdk/js/6/core-classes/kuzzle/use-controller) method.

src/sdk/js/6/core-classes/base-controller/properties/index.md

@@ -0,0 +1,16 @@
+---
+code: true
+type: page
+title: Properties
+description: BaseController Properties
+---
+
+# Properties
+
+| Property name        | Type     | Description          |
+| -------------------- | -------- | --------------------------------------- |
+| `name`               | <pre>string</pre> | Controller name    |
+| `kuzzle`             | <a href="/sdk/js/6/core-classes/kuzzle/constructor"><pre>Kuzzle</pre></a> | Kuzzle SDK instance      |
+
+**Note:**
+ - The `name` property will be injected in the request sent by the [BaseController.query](/sdk/js/6/core-classes/base-controller/query) method if the `controller` property is not set.

src/sdk/js/6/core-classes/base-controller/query/index.md

@@ -0,0 +1,55 @@
+---
+code: true
+type: page
+title: query
+description: Wrapper around the Kuzzle.query method
+---
+
+# query
+
+Base method used to send queries to a Kuzzle controller, following the [API Documentation](/core/1/api/essentials/connecting-to-kuzzle).  
+
+This method injects the controller name into the the request and forwards it to the original [Kuzzle.query](/sdk/js/6/core-classes/kuzzle/query) method.
+
+## Arguments
+
+```javascript
+query (request, [options]);
+```
+
+<br/>
+
+| Argument  | Type   | Description            |
+| -------------- | --------- | ------------- |
+| `request` | <pre>object</pre> | API request  |
+| `options` | <pre>object</pre> | Optional query options |
+
+### request
+
+All properties necessary for the Kuzzle API can be added in the request object.
+The following properties are the most common.
+
+| Property     | Type   | Description                               |
+| -------------- | --------- | ------------- |
+| `action`     | <pre>string</pre> | Action name (required)                   |
+| `controller` | <pre>string</pre> | Controller name                           |
+| `body`       | <pre>object</pre> | Query body for this action                |
+| `index`      | <pre>string</pre> | Index name for this action                |
+| `collection` | <pre>string</pre> | Collection name for this action           |
+| `_id`        | <pre>string</pre> | id for this action                        |
+| `volatile`   | <pre>object</pre> | Additional information to send to Kuzzle |
+
+**Note:**
+ - If the `controller` property is not set, the controller [name property](/sdk/js/6/core-classes/base-controller/properties) will be used
+
+### options
+
+Additional query options
+
+| Property     | Type<br/>(default)    | Description   |
+| -------------- | --------- | ------------- |
+| `queuable` | <pre>boolean</pre><br/>(`true`) | If true, queues the request during downtime, until connected to Kuzzle again |
+
+## Resolves
+
+Resolve to the raw Kuzzle API response. See the [API Documentation](/core/1/api/essentials/connecting-to-kuzzle).

src/sdk/js/6/core-classes/kuzzle/index.md

@@ -3,5 +3,5 @@ code: true
 type: branch
 title: Kuzzle
 description: Kuzzle object documentation
-order: 500
+order: 510
 ---

src/sdk/js/6/core-classes/kuzzle/query/index.md

@@ -23,7 +23,7 @@ query(request, [options]);
 
 | Argument  | Type              | Description            |
 | --------- | ----------------- | ---------------------- |
-| `request` | <pre>object</pre> | API request options    |
+| `request` | <pre>object</pre> | API request    |
 | `options` | <pre>object</pre> | Optional query options |
 
 ### request

src/sdk/js/6/core-classes/kuzzle/use-controller/index.md

@@ -0,0 +1,34 @@
+---
+code: true
+type: page
+title: useController
+description: Adds a new controller to the SDK
+---
+
+# useController
+
+Adds a new controller to the SDK. 
+
+*See also:* 
+  - *[Extend the SDK](/sdk/js/6/essentials/extend-sdk)*
+
+## Arguments
+
+```javascript
+useController (ControllerClass, accessor);
+```
+
+<br/>
+
+| Argument  | Type   | Description            |
+| -------------- | --------- | ------------- |
+| `ControllerClass` | <pre>Class</pre> | Controller class. Must inherit from [BaseController](/sdk/js/6/core-classes/base-controller)    |
+| `accessor` | <pre>string</pre> | Accessor name for the controller in the Kuzzle object |
+
+## Returns
+
+Returns the Kuzzle object.
+
+## Usage
+
+<<< ./snippets/use-controller.js

src/sdk/js/6/core-classes/kuzzle/use-controller/snippets/use-controller.js

@@ -0,0 +1,35 @@
+class TaxiController extends BaseController {
+    constructor (kuzzle) {
+      super(kuzzle, 'my-plugin/taxi');
+    }
+
+    enroll () {
+      return this.query({
+        action: 'enroll'
+      });
+    }
+  }
+
+  const kuzzle = new Kuzzle(
+    new WebSocket('kuzzle')
+  );
+
+  // Add the custom SDK controller
+  kuzzle.useController(TaxiController, 'taxi');
+
+  const run = async () => {
+    try {
+      await kuzzle.connect();
+
+      // Call the custom SDK controller action
+      console.log(await kuzzle.taxi.enroll());
+
+      console.log('Success');
+    } catch (error) {
+      console.error(error);
+    } finally {
+      kuzzle.disconnect();
+    }
+  };
+
+  run();

src/sdk/js/6/core-classes/kuzzle/use-controller/snippets/use-controller.test.yml

@@ -0,0 +1,11 @@
+---
+name: kuzzle#useController
+description: Adds a new controller to the SDK
+hooks:
+  before:
+  after:
+template: controller
+expected: Success
+
+sdk: js
+version: 6