Cross-app navigation

To handle navigation between 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

If you have multiple Weavy apps on the same page, navigation between these apps is automatically handled. 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.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.navigation.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.

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 id 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 /appid?navigate=encodedRouteData

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.app.id + "?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 disable 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.

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.app.id + "?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");
    });
  }
}