Fliplet Router JS API

Fliplet.Router is the client-side routing helper for V3 SPA apps. It reads the route manifest from app.settings.v3, normalizes the base path for the current hosting context (slug-hosted web, Studio preview iframe, native shell), and performs server-ACL-backed access checks for each route.

Fliplet.Router is available on V3 apps only and is auto-loaded at boot. It depends on fliplet-core (Fliplet.Env, Fliplet.User) and fliplet-media (Fliplet.Media.getContents).

For the full routing contract, per-framework integration examples, and forbidden patterns, see V3 routing. This page is the API reference only.

Contents

• Methods
  • getBasePath()
  • getRouteManifest()
  • getRouteConfig(path)
  • resolveRoute(pathOrRoute)
• Reason codes
• Manifest shape
• Related

Methods

Fliplet.Router.getBasePath()

Returns the base path used by the router’s history mode, normalized with a trailing slash so string concatenation doesn’t produce //route.

Returns: String

The value depends on the hosting context:

var base = Fliplet.Router.getBasePath();

// Pass to Vue Router 4:
var history = VueRouter.createWebHistory(base);

// Pass to React Router 6:
var router = ReactRouterDOM.createBrowserRouter(routes, { basename: base });

Never hardcode '/'. Slug-hosted apps, preview iframes, and native shells all mount the SPA at a different base.

Fliplet.Router.getRouteManifest()

Returns the route manifest stored in app.settings.v3. Defaults are provided for every field so callers can use the return value without null checks.

Returns: Object with the following properties:

var manifest = Fliplet.Router.getRouteManifest();

manifest.routes.forEach(function(r) {
  console.log(r.name, r.path, r.fileId, r.public);
});

console.log(manifest.defaultRoute); // '/home'
console.log(manifest.authRedirect); // '/login'

Fliplet.Router.getRouteConfig(path)

Looks up a single route entry from the manifest by path. The lookup is path-based and normalizes leading slashes (home and /home match the same route).

Parameters:

Returns: Object | undefined. The matching route entry from manifest.routes, or undefined if no route matches.

var route = Fliplet.Router.getRouteConfig('/home');

if (route) {
  console.log(route.fileId);   // 222
  console.log(route.public);   // true
} else {
  // Path isn't in the manifest
}

Fliplet.Router.resolveRoute(pathOrRoute)

Resolves a route to its access decision and its screen source. On success, result.content is the screen’s source already loaded via Fliplet.Media.getContents — render it directly rather than re-fetching. The server’s media ACL is the source of truth; this method either fast-fails when the outcome is known (no session, unknown route) or derives the decision from the server’s 401/403 response.

Parameters:

Returns: Promise that:

• Resolves with an access decision (see shapes below).
• Rejects with the underlying error on transient or infra failures (network errors, 5xx responses) so callers can show an error UI instead of redirecting silently.

Resolution shape on success:

{
  allowed: true,
  content: '<!-- raw screen HTML/JS source -->',
  route: { name: 'Home', path: '/home', fileId: 222, public: true }
}

Resolution shape on denial:

{
  allowed: false,
  redirectTo: '/login',      // manifest.authRedirect
  reason: 'no-session',      // see Reason codes below
  status: 401                // only present when reason is 'media-denied'
}

Don't call Fliplet.Media.getContents(fileId) yourself. resolveRoute already does this internally and returns the content in result.content. A second fetch duplicates the round trip, can race with the access check, and fails outright on private media where auth headers aren't applied.

Example:

Fliplet.Router.resolveRoute('/my-account').then(function(result) {
  if (!result.allowed) {
    // Redirect to the auth screen (or wherever the server says)
    navigate(result.redirectTo);
    return;
  }

  // Mount the screen using result.content
  mountScreen(result.content, result.route);
}, function(err) {
  // Transient failure (network, 5xx). Show an error UI rather than redirecting.
  showErrorScreen(err);
});

Passing a route object instead of a path:

If you already have a route entry from the manifest, you can pass it directly to skip the path lookup:

var manifest = Fliplet.Router.getRouteManifest();
var route = manifest.routes[0];

Fliplet.Router.resolveRoute(route).then(function(result) {
  // ...
});

Reason codes

When resolveRoute resolves with allowed: false, the reason property indicates why. Handle each case explicitly.

The manifest's public: true flag is advisory. It just lets the client skip a known-401 round trip. Flipping public: true in the manifest without updating the media file's access rule grants no access; the server still returns 401 and resolveRoute resolves with reason: 'media-denied'.

Transient errors (network failures, 5xx responses) do not resolve with a reason. They reject the Promise with the underlying error so you can distinguish “user can’t access this” from “infrastructure is broken”.

Manifest shape

The manifest is stored at app.settings.v3 and emitted to the runtime via window.ENV.appSettings. See V3 app settings convention for how settings are stored and filtered.

{
  "routes": [
    { "name": "Home",      "path": "/home",       "fileId": 222, "public": true },
    { "name": "Login",     "path": "/login",      "fileId": 444, "public": true },
    { "name": "MyAccount", "path": "/my-account", "fileId": 333 }
  ],
  "defaultRoute": "/home",
  "authRedirect": "/login"
}

Each route entry has the following properties:

Update the manifest via the App Settings API (PUT /v1/apps/:id with settings.v3) or the Studio routing UI whenever you add or remove a user-visible route.

Related

• V3 routing. Full routing contract, per-framework examples, forbidden patterns, and post-login redirect.
• V3 app bootstrap constraints. Three constraints every V3 boot HTML must satisfy.
• V3 app settings convention. Where the route manifest is stored (app.settings.v3).
• Media JS APIs. Fliplet.Media.getContents details.