k.site.routes
Query site routes, rename paths with changeRoute, and create route aliases
| Execution Context | Prerequisites | Typical Use |
|---|---|---|
| KScript API / Server scripts | Current site context; makeAlias() requires an existing source route | Look up routes by URL or object ID, remap paths, and create URL aliases |
Quick Start
Inspect all registered routes, the home route, and the route bound to the first site page:
js
k.api.get(() => {
const allRoutes = k.site.routes.all()
const homeRoute = k.site.routes.getByUrl("/")
const page = k.site.pages.all()[0]
const pageRoute = page ? k.site.routes.getByObjectId(page.id) : null
return {
routeCount: allRoutes.length,
homeRouteId: homeRoute ? String(homeRoute.id) : null,
firstPageRoute: pageRoute ? {
name: pageRoute.name,
destinationConstType: pageRoute.destinationConstType
} : null
}
})Quick Reference
| Method / Property | Description | Returns |
|---|---|---|
all() | Returns all routes registered in the site | Route[] |
getByUrl(url) | Looks up a route by URL path (such as "/about") | Route | null |
getByNameOrId(nameOrId) | Looks up a route by route name (URL) or GUID id | Route | null |
getByObjectId(objectId) | Looks up a route by its target object GUID id | Route | null |
changeRoute(oldurl, newurl) | Renames an existing route URL from oldurl to newurl | void |
makeAlias(url, alias) | Creates an alias route pointing to an existing route url | Route |
Related Docs and Console Tools
| API / Guide | Purpose |
|---|---|
k.site.routes | Query routes, move paths (changeRoute), and create aliases (makeAlias) |
| k.site.pages | Manage site pages and page routes (updateRoute) |
| URLs and Routing (CMS Console) | Manage site URL routes and aliases in the console |
Runtime Notes
- Calling
makeAlias(url, alias)when the source routeurldoes not exist throws an error ("Object reference not set to an instance of an object."). Always verify the source route exists withgetByUrl(url)first. - An alias route references the target route (
destinationConstTypeis15, withobjectIdset to the target routeid). Deleting a page while an alias references its route prevents automatic removal of those linked routes; manage alias cleanup in Console URLs and Routing. - Compare GUID fields such as
route.idorroute.objectIdusingString(...).
Detailed Methods
all() / getByUrl() / getByNameOrId() / getByObjectId()
List all site routes or look up an individual route by URL path, route ID, or target resource ID.
| Method | Parameters | Returns | Description |
|---|---|---|---|
all() | None | Route[] | Returns all routes registered in the site |
getByUrl(url) | url: string | Route | null | Looks up a route by URL path (for example, "/about") |
getByNameOrId(nameOrId) | nameOrId: string | Route | null | Looks up a route by route name (URL) or GUID id |
getByObjectId(objectId) | objectId: string | Route | null | Looks up a route by the target object's GUID id (page, file, style, etc.) |
Returns: Route[] or Route | null
js
k.api.get(() => {
const route = k.site.routes.getByUrl("/about")
return route
? { id: String(route.id), objectId: String(route.objectId), culture: route.culture }
: { found: false }
})changeRoute() and makeAlias()
Move an existing route path to a new URL, or register an alias pointing to an existing route.
| Method | Parameters | Returns | Description |
|---|---|---|---|
changeRoute(oldurl, newurl) | oldurl: string, newurl: string | void | Changes an existing route path from oldurl to newurl |
makeAlias(url, alias) | url: string, alias: string | Route | Creates an alias route alias targeting existing route url (destinationConstType === 15, objectId === target.id) |
Returns: changeRoute() returns void; makeAlias() returns the newly created Route
js
k.api.post(() => {
const oldUrl = k.request.form.oldUrl
const newUrl = k.request.form.newUrl
k.site.routes.changeRoute(oldUrl, newUrl)
const updated = k.site.routes.getByUrl(newUrl)
return {
moved: !!updated && !k.site.routes.getByUrl(oldUrl),
newName: updated?.name
}
})Create an alias after confirming the target route exists:
js
k.api.post(() => {
const targetUrl = k.request.form.targetUrl
const aliasUrl = k.request.form.aliasUrl
const target = k.site.routes.getByUrl(targetUrl)
if (!target) {
return { error: "target route not found" }
}
const alias = k.site.routes.makeAlias(targetUrl, aliasUrl)
return {
aliasName: alias.name,
destinationConstType: alias.destinationConstType,
pointsToTarget: String(alias.objectId) === String(target.id)
}
})TypeScript Definitions
ts
interface RouteObjectRepository {
all(): Route[];
getByNameOrId(nameOrId: string): Route | null;
getByUrl(url: string): Route | null;
getByObjectId(objectId: string): Route | null;
changeRoute(oldurl: string, newurl: string): void;
makeAlias(url: string, alias: string): Route;
}
interface Route {
id: string;
name: string;
objectId: string;
destinationConstType: number;
culture: string;
parameters: Record<string, string>;
getParameter(key: string): string | null;
copy(): Route;
creationDate: Date;
lastModified: Date;
}