Navigation Handling - Development | Client SDK

Introduction

To handle navigation between different apps, you need to add some navigation handling. Since weavy apps are placed within your app, they would not know where to navigate unless you added some handling for navigation requests. Weavy has events and methods for this to provide you with all the data and functionality you need to do a proper navigation.

Automatic navigation within weavy

If you have multiple weavy apps on the same page, navigation between these two apps is handled automatically. Let's say for instance that you have a notification app with a notification that links to another app on the same page, this link will be automatically opened in the other app.

You may use the weavy.navigation.open(route) function at any time to try to open a url or a route in the app it belongs to.

The function accepts both a string url or a route object like the one in the navigate event. It returns a promise which resolves if the correct app is present and fails if the app is missing.

Tip: If you know the space and app, you may also open the url directly by using weavy.space("spacekey").app("appkey").open(url);

// Tries to open a notification in the app where it points to
var route = "/notifications/1234"
weavy.navigation.open(route)
   .then(function() {
       console.log("navigated on the page");
   })
   .catch(function() {
       console.log("no page navigation done");
   })

Listening to navigation requests

To handle navigation, you need to register a handler to the navigate event. The event will provide you with the keys you have used for the space and app which we are about to navigate to. Use these keys to determine which location in your system to navigate to.

You may use any preferred way you normally use in your app to navigate to the next view. Some apps may use a normal url navigation, while a single page app might call a function to load the next view.

To be able to fully display the correct item after the navigation, you should at least pass the url provided by the event data. If you have apps that might not be visble initially after the navigation, you should also pass the keys in the navigation to be able to open the correct app after the navigation is done.

Event route data

The event route data object is used both by the navigate event and the weavy.navigate.open(route) function

Some of the properties are provided by the server as meta data and not needed for the actual request when passing the route to the open function.

Property	Description
`space`	Data for the space which the next app belongs to.
`space.key`	The key for that space.
`space.id`	The server id for that space.
`[space.name]`	The name of that space.
`app`	The next app which the navigate url belongs to.
`app.key`	The key for that app.
`app.id`	The server id for that app.
`[app.name]`	The name of that app.
`[entity]`	If applicable, the next item which the navigate url belongs to.
`entity.id`	The server id for that item.
`entity.type`	The type of that item.
`[target]`	Preferred target for the request. Set to "overlay" for any preview.
`url`	The navigate url which the next app should open.

Simple URL navigation example

This example uses the navigate event triggered only if internal auto navigation can't open the route in another app.

It uses classic url navigation to navigate to an url and uses the keys for building up the url. Then it appends the route data to the url to pass it to the destination.

The url we construct here has the form /spacekey/appkey?navigate=encodedRouteData

var weavy = new Weavy();
weavy.on("navigate", function (event, route) {
   // base64 encode data and pass it as query string to url
   var encoded = btoa(JSON.stringify(route));
   window.location = "/" + route.space.key + "/" + route.app.key + "?navigate=" + encodeURIComponent(encoded);
});

Advanced navigation example

If you want to have full control over the navigation handling including the auto navigation you should use the before:navigate-event together with event.preventDefault() to prevent the ordinary internal auto navigation.

It tries the internal auto navigation manually and navigates when the auto navigation is unsuccessful.

The result from the code in this example is exactly the same as the simple example, but with full control over all the steps.

var weavy = new Weavy();
weavy.on("before:navigate", function (event, route) {
   // Stop the internal auto navigation from being executed
   event.preventDefault();
 
   // Try to navigate on the same page otherwise navigate to another page
   weavy.navigation.open(route).then(function() { console.log("navigated on the page")}).catch(function() {
       console.log("no page navigation done, do url navigation instead");
 
       // base64 encode data and pass it as query string to url
       var encoded = btoa(JSON.stringify(route));
       window.location = "/" + route.space.key + "/" + route.app.key + "?navigate=" + encodeURIComponent(encoded);
   });
});

Receiving the navigation

When you have successfully navigated to a new view, you should pass weavy the route data to make weavy open the correct item in the correct app.

You should make sure that the app is visible when trying to open the route. If you handle this using the open event, then it will be taken care of for you.

To handle the navigation data you simply call the weavy.navigation.open(route) function, which will open the route in the correct app if present.

// Decode the base64 encoded navigate data
var encodedRoute = new URLSearchParams(window.location.search).get("navigate");
if (encodedRoute) {
   var route = JSON.parse(atob(encodedRoute));
 if (route) {
       // Try to open the route
       weavy.navigation.open(route).then(function() {
           console.log("The route was opened");
       });
   }
}

Handling navigation