Skip to content

k.site.routes ​

Query site routes, rename paths with changeRoute, and create route aliases

Execution ContextPrerequisitesTypical Use
KScript API / Server scriptsCurrent site context; makeAlias() requires an existing source routeLook 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 / PropertyDescriptionReturns
all()Returns all routes registered in the siteRoute[]
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 idRoute | null
getByObjectId(objectId)Looks up a route by its target object GUID idRoute | null
changeRoute(oldurl, newurl)Renames an existing route URL from oldurl to newurlvoid
makeAlias(url, alias)Creates an alias route pointing to an existing route urlRoute

Related Docs and Console Tools

API / GuidePurpose
k.site.routesQuery routes, move paths (changeRoute), and create aliases (makeAlias)
k.site.pagesManage 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 route url does not exist throws an error ("Object reference not set to an instance of an object."). Always verify the source route exists with getByUrl(url) first.
  • An alias route references the target route (destinationConstType is 15, with objectId set to the target route id). 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.id or route.objectId using String(...).

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.

MethodParametersReturnsDescription
all()NoneRoute[]Returns all routes registered in the site
getByUrl(url)url: stringRoute | nullLooks up a route by URL path (for example, "/about")
getByNameOrId(nameOrId)nameOrId: stringRoute | nullLooks up a route by route name (URL) or GUID id
getByObjectId(objectId)objectId: stringRoute | nullLooks 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.

MethodParametersReturnsDescription
changeRoute(oldurl, newurl)oldurl: string, newurl: stringvoidChanges an existing route path from oldurl to newurl
makeAlias(url, alias)url: string, alias: stringRouteCreates 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;
}