Navigation objects

The navigation objects is necessary to understand in order to get the most out of the EmbeddableView. These are also responsible for the Route-specific customizability.

We have the Navigation-object which is used for Navigating to a route. Meaning that this object is used for changing the route.

Remember that the Routes-enum are just strings. Eg. Routes.ACCOUNTS = “/accounts”

Basic example:

import { Embeddable, Routes } from 'embeddables'

const embeddable = new Embeddable({
  embedToken: getEmbedToken(),
})
embeddable.createView({
  // The initial route that will be displayed
  // Navigation-object:
  route: {
    path: Routes.ACCOUNTS,
    options: {}, // See the Navigation options section for more information.
  }
});

As seen in previous examples—the navigation object can also be an Routes-enum like this:

embeddable.createView({
  route: Routes.ACCOUNTS
});

A routeName can be used instead of a path, the routeName needs to be defined in a Navbar-item in settings.navbar to be able to use this property:

embeddable.createView({
  route: {
    // routeName is referencing the settings.navbar-item with the same routeName
    routeName: 'account-page-defined-in-navbar',
    options: {},
  },
  settings: {
    navbar: [
      // This can be referenced when navigating
      routeName: 'account-page-defined-in-navbar', // 'routeName' is required
      path: Routes.ACCOUNTS,                       // 'path' is required

      // ...other settings. See Navigation options section for more information.
    ],
  },
});

We have the Navbar-item-object which is used to define a route, this is only used in the navbar-property in the EmbeddableView settings (as seen above), this object provides a routeName-property which can be used to identify the route. This routeName will be referenced in the Navigation object when navigating to this route.

There are several valid Navbar-item objects, we will start from the simplest to the more advanced:

Using straight Routes-enum. The default route-options will be generated, and the routeName will be the path, eg. Routes.ACCOUNTS and Routes.PAYMENTS respectively in these cases.

...
navbar: [
  Routes.ACCOUNTS,
  Routes.PAYMENTS,
  // Other routes
],
...

The code example above becomes this behind the scenes:

...
navbar: [
  {
    path: Routes.ACCOUNTS,
    routeName: Routes.ACCOUNTS,
  },
  {
    path: Routes.PAYMENTS,
    routeName: Routes.PAYMENTS,
  },
],
...

Omitting the routeName-property from the Navbar-item object. The routeName will, again, be set to the path behind the scenes:

...
navbar: [
  {
    path: Routes.ACCOUNTS,
    // As no routeName was present, it is set to the following automatically:
    // routeName: Routes.ACCOUNTS
  },
  {
    path: Routes.PAYMENTS,
    // As no routeName was present, it is set to the following automatically:
    // routeName: Routes.PAYMENTS
  },
],
...

Defining the full object:

...
navbar: [
  {
    path: Routes.ACCOUNTS,
    routeName: Routes.ACCOUNTS // Can be any string
  },
  {
    path: Routes.PAYMENTS,
    routeName: Routes.PAYMENTS // Can be any string
  },
],
...

The routeName-property in the Navbar-items needs to be unique

...
navbar: [
  {
    path: Routes.ACCOUNTS,
    routeName: 'my-route',
  },
  {
    path: Routes.PAYMENTS,
    routeName: 'my-route', // ❌ routeName IS NOT UNIQUE ANYMORE
  },
],
...

Examples

Simple example

The example below will create an account-view with a navbar with redirect-buttons pointing to the Account-, Payment- and Payouts-view.

embeddable.createView({
  // This will actually point to the Routes.ACCOUNTS in the navbar because, 
  // as mentioned before, the routeName is defaulted to the path, both in the
  // Navigation object and the Navbar-item object.
  route: Routes.ACCOUNTS,
  settings: {
    navbar: [
      Routes.ACCOUNTS,
      Routes.PAYMENTS,
      Routes.PAYOUTS
    ],
  },
});

Full example

embeddable.createView({
  route: {
    // Using the route from 'settings.navbar'
    routeName: 'my-tos-accepted-accounts',
    // Adding extra options to be merged with the Navbar-item
    // See Route options for more information.
    options: {
      table: {
        search: {
          balance: {       // Accounts balance
            '>': {         // Greater than
              value: 1000, // 1 000øre (10kr)
            },
          },
        },
      },
    },
  // When using routeName, we need to add the 'satisfies'-keyword to get TS typings
  } satisfies EmbeddableNavigation<Routes.ACCOUNTS>,
  settings: {
    navbar: [
       Routes.ACCOUNTS,
      // Custom route with static filters
      {
        routeName: 'my-tos-accepted-accounts',
        path: Routes.ACCOUNTS,
        displayText: 'My TOS accepted accounts',  

        // Options for the route
        // See other examples for more information
        options: {
          table: {
            staticSearch: {   // staticSearch: meaning not visible or mutable in the UI
              tosIsAccepted: {// Accounts with terms of service accepted at (Date)
                '!=': {       // is not
                  value: null,// present
                },
              },
            },
          },
        },
      },
      // Route without 'displayText' will use the default
      {
        path: Routes.PAYMENTS,
      },
      // Routes enum
      Routes.PARTIAL_PAYMENTS,
      Routes.PAYOUTS,
      // Route with parameters
      {
        path: Routes.PARTIAL_PAYMENTS_REFUND,
        params: {
          paymentReferenceId: 'payment-reference-id',
        },
        // Customizing the navbars display text
        displayText: 'Refund my favorite payment',
      },
    ], // This is the navbar type 'satisfies EmbeddableNavbar'
  },
})

Conclusion

These are very similar in structure, but knowing the distinction is important. To repeat, the Navigation object is what you use to navigate to the Navbar-item object.

The Navigation object

The Navbar-item object

Examples

Simple example

Full example

Conclusion