feat: Document not authenticated users management (#147)

* feat: Routes roles

* feat: Public routes guide

* Update src/markdown/features/routes.md

* Update src/markdown/guides/public-routes.md

doc-deps.yml

@@ -6,5 +6,5 @@ components:
  containsVersion: true
 - name: cli
  url: https://github.com/lenra-io/lenra_cli
- version: v1.1.0
+ version: v1.3.0
  filePrefix: lenra-cli-docs

src/markdown/features/routes.md

@@ -1,28 +1,31 @@
-Routes are defined in the app manifest under the `lenraRoutes` property. The `lenraRoutes` property is an array of objects, where each object represents a route. Each route object has two properties:
+Routes are defined in the app manifest under the `routes` property of the `json` and `lenra` providers. The `routes` property is an array of objects, where each object represents a route. Each route object has two properties:
 
 - `path` - Defines the URL path that corresponds to the route.
 - `view` - Defines the view that is associated with the route.
+- `roles` - Defines the roles that are allowed to access the route. The default value is `["user"]`. [Read more about roles](#routeroles)
 
 ## Manifest example
 
 ```json
 {
- "lenraRoutes": [
- {
- "path": "/",
- "view": {
- "type": "view",
- "name": "main"
- }
- },
- {
- "path": "/newPage",
- "view": {
- "type": "view",
- "name": "newPage"
+ "lenra": {
+ "routes": [
+ {
+ "path": "/",
+ "view": {
+ "type": "view",
+ "name": "main"
+ }
+ },
+ {
+ "path": "/newPage",
+ "view": {
+ "type": "view",
+ "name": "newPage"
+ }
  }
- }
- ]
+ ]
+ }
 }
 ```
 
@@ -80,9 +83,9 @@ export default function (data, props, context) {
  }
 ```
 
-## Navigating to a route
+## Navigating to a Lenra route
 
-You can navigate to any route that is defined in the `lenraRoutes` property in the app manifest. To do that, you have to call the specific listener action `@lenra:navTo`. Here is an example of a button using this listener.
+You can navigate to any route that is defined in the `lenra.routes` property in the app manifest. To do that, you have to call the specific listener action `@lenra:navTo`. Here is an example of a button using this listener.
 
 ```json
 {
@@ -94,3 +97,32 @@ You can navigate to any route that is defined in the `lenraRoutes` property in t
  }
 }
 ```
+
+## Route roles
+
+There are for now only two roles managed by Lenra:
+- `guest`: This role is used for users that are not logged in.
+- `user`: This role is used for users that are logged in.
+
+The route roles are defined in the app manifest under the `roles` property of the route object.
+The default value is `["user"]` to only allow the authenticated users.
+If you want to allow both logged in and not logged in users to access the route, you can set the `roles` property to `["guest", "user"]`.
+
+```json
+{
+ "lenra": {
+ "routes": [
+ {
+ "path": "/",
+ "view": {
+ "type": "view",
+ "name": "main"
+ },
+ "roles": ["guest", "user"]
+ }
+ ]
+ }
+}
+```
+
+If you want to make your app accessible to guest users you'll have to [make it public](../guides/manage-access.html#publicaccess).

src/markdown/guides/public-routes.md

@@ -0,0 +1,80 @@
+---
+description: Give access to not authenticated users.
+---
+
+Do you want to give access to your app to not authenticated users?
+In this guide we will explain how to create a public route and how to use it in a front-end app.
+
+## Create a public route
+
+To create a public route, you need to set the `roles` property of one of your manifest routes to `["guest"]` or `["guest", "user"]` if you want the same route to be accessible to authenticated and not authenticated users.
+
+Here is an example of a public route:
+
+```json
+{
+ "json": {
+ "routes": [
+ {
+ "path": "/public",
+ "view": "myPublicView",
+ "roles": ["guest"]
+ },
+ {
+ "path": "/all",
+ "view": "myView",
+ "roles": ["guest", "user"]
+ },
+ {
+ "path": "/private",
+ "view": "myPrivateView"
+ }
+ ]
+ }
+}
+```
+
+## Use a public route in a front-end app
+
+To use the [{:rel="noopener" target="_blank"} Lenra JavaScript client lib](https://github.com/lenra-io/client-lib-js) as an unauthenticated user, simply use the `openSocket()` method to connect to the Lenra server without a token, and then open the desired route :
+
+```js
+import { LenraApp } from '@lenra/client';
+
+const app = new LenraApp({
+ // Needed for not authenticated users
+ appName: "Example Client",
+ // Needed for authentication
+ clientId: "XXX-XXX-XXX",
+});
+
+app.openSocket().then((socket) => {
+ const route = app.route("/public", (data) => {
+ // Handle data
+ });
+});
+```
+
+That's it! You can now use public routes in your front-end app.
+
+You can authenticate users with the `authenticate()` method of the `LenraApp` class that will return the token to use as `openSocket(token)` method parameter.
+Remember to close your existing socket if you don't need it anymore with the `close()` method:
+
+```js
+app.openSocket().then((socket) => {
+ const route = app.route("/public", (data) => {
+ // Handle data
+ });
+
+ document.getElementById("login").addEventListener("click", () => {
+ socket.close();
+ app.authenticate().then((token) => {
+ app.openSocket(token).then((socket) => {
+ const privateRoute = app.route("/private", (data) => {
+ // Handle data
+ });
+ });
+ });
+ });
+});
+```