Introduction
Note: This feature is not yet supported in Wix Blocks.
The Wix Router API allows you to handle certain incoming requests to your site's pages and sitemap and customize the responses.
Some things you might do with the Router API are:
- Control the URL structure of your site.
- Customize your site's sitemap.
- Extend dynamic pages to include subpages that use different data.
- Cache router response data used to display pages.
The API gives you access to the following:
- Requests to certain pages on your site and routing responses for those pages.
- Sitemap requests and responses.
- Hooks to control the flow of the data used to display pages returned by the router or sitemap. Hooks are often used when working with the code for dynamic pages.
Router caching
To enhance performance, you can implement caching for your router responses using the ok() function. Router caching allows you to temporarily store the function's return value, reducing response times and the need to repeatedly fetch data every time a visitor makes a request on your site. Learn more about router caching.
Before you begin
It's important to note the following points before starting to code:
- Code using the Routers API is stored in the routers.js file in the backend code section the Code sidebar. You shouldn't create this file manually.
- The file is created automatically when you add a router to your site.
To use the router() and sitemap() functions in the routers.js file, use the following convention:
To import the other API functions into the routers.js file, use the following syntax:
Get hands-on experience with the Routers API on our Hello Routers example page.
Terminology
- Router: Part of the code on your site that receives requests for specific URLs and handles which page is served and what data is included in that page.
- Sitemap: A model of a site's content structure, designed to help both users and search engines navigate the site.
- Data binding router hooks: Functions that run before, during, and after data is included in the pages that the router and sitemap functions return. Router hooks are often used when working with dynamic pages. The API includes 4 hooks:
- Caching: The process of storing frequently accessed data in a temporary storage location so that it can be retrieved more quickly, improving the performance and speed of your site.
Coding with the Router API
The functions in the routers.js file are named with the following convention:
These are not functions that you call in your code, rather they are functions that you define. They are called when your users browse to a URL that is handled by a router as described below.
For example, the following code creates a router on the myRouter prefix that shows a page when the path begins with the word "good" and returns a 404 in all other cases.
Code Router
Code your own router() and sitemap() functions for a
router that handles all incoming
requests with a specified URL prefix. Your code decides what actions to
perform, what responses to return, where to route the request, and what data
to pass to pages.
You might want to use a router to:
- Display a dynamic page using content from any data source.
- Customize your URLs to make them more meaningful and yield better SEO results.
- Authenticate users and then display content just for them.
- Return custom HTTP response codes.
Data Binding Router Hooks
When a request comes in for a page that a router handles, either a code router or a dynamic page, you can add data binding router hooks to intercept the process of the data getting bound to the page at certain points and insert additional logic.
The hooks you can use are listed here in the order they are triggered:
beforeRouter- Before the data binding router logic.customizeQuery- As the data binding router prepares a data query.afterRouter- After the data binding router completes its logic, but before the page is displayed.afterSitemap- After the data binding sitemap function completes preparing the list of urls.
Prefixes
When using the wix-router API you often need to know the prefix of your code router
or dynamic pages. You can find prefixes as follows:
-
Code router:
- Go to in the Page Code's Router Pages section of the Velo Sidebar.
- Click the ellipsis
icon that appears when you hover over the title of the router's grouped router pages. - Click Change Router.
The router's prefix is displayed.
-
Dynamic pages:
-
Go to in the Page Code's Dynamic Pages section of the Velo Sidebar.
-
Click the ellipsis
icon that appears when you hover over the dynamic page. -
Click Settings.
The Page Info tab shows the page URL. The prefix is the first editable section of the URL up until the first forward slash (/).
-
wixRouterSitemapEntry
afterRouter( )
Registers a hook that is called after a router.
The afterRouter hook is a data binding router hook that is triggered
after the router with the specified prefix has bound the data, but before
the page is displayed. The router can be a code router or the data binding
router that binds data to a dynamic page.
The afterRouter() function is not a function that you call from your code.
You define the function in a file named routers.js in the Code File's Backend section of the Velo Sidebar.
The function is called as described above.
Use this hook with a code router to change the router's response based on the data that was retrieved. For example, you can have two versions of a page, one for portrait oriented images and another for landscape oriented ones. After the image is pulled from the database, you can show the page that corresponds to the image's orientation.
The function receives a WixRouterRequest
object containing information about the incoming request and a WixRouterResponse
object containing information about the router's response.
The function returns a WixRouterResponse
object that causes the router to respond with a specified page, specified data,
and a success response code, or respond with any other HTTP response code.
The returned response can be either the response received or a new response
that overrides the one received.
If the function does not return a WixRouterResponse,
the response received as the response parameter acts as the effective router response.
Typically, the response is created using one of the ok(),
forbidden(), notFound(), redirect(),
or sendStatus() functions.
The routing request.
The router response.
This example creates an after router hook on the myRouter prefix.
afterSitemap( )
Registers a hook that is called after a sitemap is created.
The afterSitemap hook is a data binding router hook that is triggered
after a sitemap is created for the specified router.
The afterSitemap() function is not a function that you call from your code.
You define the function in a file named routers.js in the Code File's Backend section of the Velo Sidebar.
The function is called as described above.
Use this hook to revise the list of pages in your sitemap. For example, you can add a search page's information to your sitemap.
The function returns an array of WixRouterSitemapEntry
objects. Typically the returned array is a modified version of the one the
function received.
If the function does not return a WixRouterSitemapEntry
array, the array received as the sitemapEntries parameter acts as the router's effective sitemap entries.
The sitemap request.
The generated sitemap entries.
This example creates an after sitemap hook on the myRouter prefix.
beforeRouter( )
Registers a hook that is called before a router.
The beforeRouter hook is a data binding router hook that is triggered
before the router with the specified prefix has bound the data to the page.
The router can be a code router or the data binding router that binds data
to a dynamic page.
The beforeRouter() function is not a function that you call from your code.
You define the function in a file named routers.js in the Code File's Backend section of the Velo Sidebar.
The function is called as described above.
Use this hook with a code router to route requests to a different page or return an error response. For example, you can check who is requesting the page and then decide based on the user's role whether to let the router continue to the next step or to return an error type response code.
The function receives a WixRouterRequest
object containing information about the incoming request.
The function returns a WixRouterResponse
object that causes the router to continue its routing, or respond with an
HTTP response code.
Typically, the response is created using one of the next(),
forbidden(), notFound(), redirect(),
or sendStatus() functions.
The routing request.
This example creates a before router hook on the myRouter prefix.
customizeQuery( )
Registers a hook that is called after a route is resolved by the data binding router, but before the wix-data query is executed.
The customizeQuery hook is a data binding router hook that is triggered
before the data query is executed for the pages in the specified router.
The customizeQuery() function is not a function that you call from your code.
You define the function in a file named routers.js in the Code File's Backend section of the Velo Sidebar.
The function is called as described above.
Use this hook to further refine or
change the query that will determine what data is bound to your page's
dataset. For example, you can filter the query to only return items that have
a status field set to "active".
The function returns a WixDataQuery object.
Typically the returned query is a modified version of the one the
function received.
The customizeQuery() hook is triggered when using dynamic pages, but not
when you code your own router.
The routing request.
The resolved router URL pattern.
The wix-data query.
This example creates a customize query hook on the myRouter prefix.