Skip to content

Latest commit

 

History

History
126 lines (95 loc) · 5.71 KB

Routing.adoc

File metadata and controls

126 lines (95 loc) · 5.71 KB
Raw

Routing

FirstSpirit Navigation Service

The Crownpeak PWA Template directly maps the navigation structure of the underlying FirstSpirit project into the predefined navigation component. This is achieved using the navigation service which maps all the routes as defined in FirstSpirit to CaaS URLs. The data is fetched by the Content API. Here is an example of navigation data.

  "c8a158a3-2ba3-427c-a7e4-7d41d9844464": {
      "id": "c8a158a3-2ba3-427c-a7e4-7d41d9844464",
      "parentIds": [
          "5a7cdf48-5031-4fcd-b6c7-99e802d0ce57"
      ],
      "label": "Home",
      "contentReference": "https://url.to.your.content",
      "caasDocumentId": "c8a158a3-2ba3-427c-a7e4-7d41d9844464",
      "seoRoute": "/Home/",
      "seoRouteRegex": null,
      "customData": null
  },
  "aa684dc6-2220-4d71-b468-f3e056b0c4f0": {
      "id": "aa684dc6-2220-4d71-b468-f3e056b0c4f0",
      "parentIds": [],
      "label": "Our Solutions",
      "contentReference": "https://url.to.your.content",
      "caasDocumentId": "4bd4e5af-c55d-4b46-b335-58e284f2f4c6",
      "seoRoute": "/Our-Solutions/",
      "seoRouteRegex": null,
      "customData": null
  },

It contains labels and contentReferences which you can use to fill a navigation menu or sitemap.

Routing concept in frontend projects

When implementing a frontend application, such as an SPA or PWA, there are various ways to implement routing. This chapter describes a possible routing flow that is based on the NavigationService and addresses the usual use cases:

  1. Routing after opening a link

  2. Routing within the application

Routing after opening a link

This use case is relevant as soon as an user is directed to the application via a link outside the application, e.g. via a search result.

In this scenario, the developer has the seoRoute of the requested object available by using the called URL.

Called URL: https://my-examplepage.com/products/products.html seoRoute: /products/

In this case, the "by-seo-route" endpoint of the navigation service can be used. The result contains the navigation data for the corresponding node in the navigation tree. With the navigation data and the locale, which can also be taken from the seoRoute, the further procedure is analogous to the "Routing within the application" use case.

Routing within the application

In this use case, the developer already knows the language and navigation data resulting from the state of the application. The state is application-specific data, but in most applications there is a possibility to access navigation data and content that has already been queried.

The content to be rendered comes either from a content projection or from a pageRef and can be requested at CaaS. The application can use the navigation data via the "seo-route-regex" attribute to decide whether it needs to retrieve a dataset or a pageRef. In the case of a content projection, the developer filters the CaaS for datasets that have a matching route (compare section Dataset routes) in their data. The associated pageRef can also be resolved so that all data for rendering the requested page is available. The navigation data contains a contentReference, which is represented by the direct CaaS url to the pageRef.

The Crownpeak PWA template contains a sample implementation for the routing concept.

Internal Linking

Nuxt.js provides file based routing conventions. We assume you are familiar with how routing works in Nuxt.js. If not, please make sure to check out the documentation linked above.

Since routing is slightly more complex in the context of the Crownpeak PWA Template, you also have the possibility to use the example <InternalLink /> component. Using this component, you can easily link to pages in the navigation structure by providing a NavigationItem as a property instead of a route.

SFC Example

<template>
  <div>
    <InternalLink :nav-item="navItem">Link to internal page</InternalLink>
  </div>
</template>

<script setup lang=ts>
import { NavigationItem } from 'fsxa-api'
const navItem:NavigationItem = ...
</script>

Trigger route changes programmatically

You can also trigger a route change to an item in the navigation structure by using the setActiveNavigationItem function from the navigation composable.

SFC Example

<template>
  <button @click="triggerRouteChange">
    Change page
  </button>
</template>

<script setup lang="ts">
const { setActiveNavigationItem } = useNavigation()
function triggerRouteChange(){
  setActiveNavigationItem(...) // provide the navigation item to navigate to

}

</script>

Middleware

The middleware (~/middleware/routing.global.ts) handles the use case of deep links and redirects the index page to the corresponding route (e.g. / to /Home/). It is executed before a page renders, and if the route is set programmatically or by an internal link, the middleware will not do anything. If a user opens a deep link, the middleware will figure out the corresponding locale and navigation item. After setting the locale and navigation item, the middleware is finished, and the flow is the same as if the user had navigated to the page via an internal link. In most cases, you do need to change anything in the middleware.