Creating and Debugging Website Routers

Creating a router allows you to take complete control when handling certain incoming requests to your site.

This article takes you through what code you have to write in order to make your router work. To learn more about what a router is and why you would want to create one, see About Routers.

Add a Router

To add a router:

1. Click on the

icon that appears when hovering over the Page Code's Main Pages section in the Velo Sidebar and choose Add a Router.

2. Enter a URL prefix for your router and click Add & Edit Code. All incoming requests with the specified URL prefix will be sent to your router for handling. 

When adding a router:

• Your router's

  router()

  and

  sitemap()

  functions are added in a routers.js file with sample code for a simple routing scenario. The routers.js file is found in the Code Files's Backend section of the Velo Sidebar.
• A new section, Router Pages, is created in the Velo Sidebar for your routers. Router pages are grouped together under a title based on the prefix you chose earlier. One router page is created to start with. For example, if you named your router "myRouter", a page named myRouter-page is added under the title MyRouter Pages (Router).

Sample Scenario

There are four parts to the sample code that's added to the routers.js file:

1. The

   import

   statement.
2. The sample data.
3. The

   router()

   function.
4. The

   sitemap()

   function.

Import statement

The functionality used to create a router is contained in the Router API. To use this functionality, you need to import it. By default, the

ok()

notFound()

WixRouterSitemapEntry

import {ok, notFound, WixRouterSitemapEntry} from "wix-router"; 

If you want to use more of the functionality from the Router API, you need to add it to the

import

Sample Data

In the sample scenario, the router uses some static data contained in an object named

peopleData

const peopleData = {  
  "Ash": {    
    title: "Ash Stowe",    
    image: "https://static.wixstatic.com/media/b8f383e0fe2b478ea91362b707ef267b.jpg"  
  },  
  "Aiden": {    
    title: "Aiden Johnson",    
    image: "https://static.wixstatic.com/media/ca3c7ac5427e43928aa5f3f443ae2163.jpg"  
  },  
  "Jess": {    
    title: "Jess White",    
    image: "https://static.wixstatic.com/media/147fe6f37fe24e83977b4124e41b6d3d.jpg"  
  },  
  "Morgan": {    
    title: "Morgan James",    
    image: "https://static.wixstatic.com/media/59e1f2f4dbbc4f7c9d6e66e3e125d830.jpg"  
  }
};

The

peopleData

title

image

Although you can use static data with a router, typically you would use data
from your site's database or an external source. We'll see where you would write code to retrieve that data a little later.

Regardless of where you get the data from, since you'll be writing the code that handles it, the data can be structured in any way you like.

Router Function

Remember, all incoming requests with the URL prefix you specified when creating the router are sent to your router for handling. The

router()

The

router()

<router prefix>_Router(request)

So if you named your router myRouter, the code added to the routers.js file should look like:

myRouter_Router(request) {  // routing code ...}

The

router()

WixRouterRequest

Typically, the

router()

forbidden()

notFound()

ok()

redirect()

or

sendStatus()

Let's take a look at the sample

router()

export function myRouter_Router(request) {

  // Get item name from URL request
  const name = request.path[0];

  // Get the item data by name
  const data = peopleData[name];

  if (data) {

    //define SEO tags 
    const seoData = { 
      title: data.title, 
      description: `This is a description of ${data.title} page`,
      noIndex: false,
      metaTags: [
         {"og:title": data.title,
          "og:image": data.image,
          content: "People Data"
         }
      ]
    };

    // Render item page 
    return ok("myRouter-page", data, seoData); 
  }

  // Return 404 if item is not found 
  return notFound();
}

The

router()

const name = request.path[0];

For example, a user might reach this

router()

https://mysite.com/myRouter/Ash

WixRouterRequest

path

["Ash"]

Ash

Next, the

router()

name

const data = peopleData[name];

Continuing our example above, we pull out Ash's information from the

peopleData

So

data

{ 
  title: "Ash Stowe",
  image: "https://static.wixstatic.com/media/b8f383e0fe2b478ea91362b707ef267b.jpg"
}

If you want to retrieve data from an external source, this is where you place the call to retrieve that data.

After attempting to retrieve the data that corresponds to the incoming request, we check to see if any data was found:

if (data) {
  // ...
}

If nothing was found, the

if

notFound()

return notFound();

Assuming we found the data we were looking for, we now prepare some header data for our page:

const seoData = { 
  title: data.title, 
  description: `This is a description of ${data.title} page`,
  noIndex: false,
  metaTags: {
    "og:title": data.title,
    "og:image": data.image
  }
};

Here we create a

HeadOptions

The sample code creates a

title

description

title

data

noIndex

metaTags

You can create the

HeadOptions

You can also add a keywords property to the

HeadOptions

Finally, we return a

WixRouterResponse

ok()

return ok("myRouter-page", data, seoData); 

Here we route the user to the router page named "

myRouter-page

data

seoData

Depending on the situation, you can return a number of different responses from the

router()

notFound()

ok()

forbidden()

403

redirect()

301

302

sendStatus()

Router Data

To use the data that was returned with a

WixRouterResponse

ok()

wix-

getRouterData()

For example, we can take the data passed by the sample router code and use it to present a person's information on the myRouter-page page that was created.

First, we need to add a text and image element to serve as placeholders for a person's title and image.

Next, in the page's code we retrieve the router data and set the text and image elements to display the

title

image

import wixWindow from 'wix-window';

$w.onReady(function () {
  let data = wixWindow.getRouterData();
  $w("#text1").text = data.title;
  $w("#image1").src = data.image;
});

If you preview the page, you'll see that the placeholders we put on the page are filled in with information from the data that was passed to the page. You can use the preview widget to see what the page looks like for any of the people in the

peopleData

The preview widget gets populated with the

title

WixRouterSitemapEntry

sitemap()

Sitemap Function

Like the

router()

sitemap()

<router prefix>_Sitemap(sitemapRequest)

So if you named your router myRouter, the code added to the routers.js file should look like:

myRouter_Sitemap(sitemapRequest) {  // routing code ...}

The

sitemap()

sitemapRequest

WixRouterSitemapEntry

Typically, the

sitemap()

WixRouterSitemapEntry

personData

Let's take a look at the sample

sitemap()

export function myRouter_SiteMap(sitemapRequest) {

  // Convert the data to site map entries
  const siteMapEntries = Object.keys(peopleData).map( (name) => {
    const data = peopleData[name];
    const entry = new WixRouterSitemapEntry(name);
    entry.pageName = "myRouter-page"; // The name of the page in the Wix Editor to render
    entry.url = `/myRouter/${name}`; // Relative URL of the page
    entry.title = data.title;   // For better SEO - Help Google
    return entry;
  } );

  // Return the site map entries
  return siteMapEntries;
}

The

sitemap()

map()

WixRouterSitemapEntry

pageName

url

title

Promise

A sitemap entry can also contain

changeFrequecy

lastModified

priority

In a case where you're using a router with external data, in the

sitemap()

Previously published at https://support.wix.com/en/article/velo-creating-a-router