Relatude Help

18 URLs and the URL manager

A URL is never stored. Each node keeps a short address, the slug in its [AddressProperty], and the store's URL manager builds URLs from addresses and live data: the node's place in a tree, its culture, the host of the request. So renaming a section is one write, and every URL below it changes.

Without configuration the manager is DefaultUrlManager running flat: a node's URL is /{address}, so addresses must be unique. Give it a parent relation and it builds /{addresses of the ancestors}/{address} instead.

// the URL of a node, and of a file variant
string pageUrl = db.GetUrl(venue);                        // absolute: true adds scheme and host
string fileUrl = db.GetUrl(venue.Photo, new FileAdjustmentImage { Width = 400 });

// the reverse: what does this URL point at?
if (db.TryParseUrl(url, out UrlKeys keys)) { … }          // node, file, variant or deeplink
if (db.TryParseUrlForContent(url, out var content)) { … } // all the way to the content to serve
var file = await db.GetUrlContentAsync(keys);             // the same, from keys already parsed

// may this node have this address? (check in an editor, before saving)
bool ok = db.WillAddressResultInUniqueUrl(new NodeKey(venue.Id), "sentrum-scene");
  • Configuring it — Set the options in relatude.db.json, under the database's LocalSettings.UrlOptions:
  • Where the path comes from — A UrlParentRelation names its relation by ParentRelationName (CodeName or full name) or ParentRelationId; ParentIsRelationSource (default true) puts the parent on the source side. With several Parents, the manager…
  • Address uniqueness — WillAddressResultInUniqueUrl(node, address) says whether an address gives a unique URL; ask it in an editor before saving. The store asks the same when it commits. If the answer is no, it adds a number to the address…
  • Page URL formats — UrlFormat decides how a page URL looks. The examples are all the same node: address info, ancestors tv/sony-x90, internal id 1042, public id 9c1b2a3d-4e5f-6071-8293-a4b5c6d7e8f9.
  • Prefixes — A base can be a path (/app) or include scheme and host (https://www.site.com), which makes those URLs absolute. A page or asset base with its own host replaces the primary base, so assets can come from a CDN while pages…
  • 18.1 Asset URLs: files, variants and deeplinks — An asset URL points at a file property, a converted variant of it, or a deeplink into embedded content. It carries a token that the store encodes and reads; the URL manager only decides where the token goes. The…
  • 18.2 Links inside HTML and Markdown — A link in a rich-text field must survive a rename of the page it points at. So properties marked StringValueType.HTML or Markdown ([HtmlProperty] is the short form) store links in an id-based form, never as public URLs:
  • Writing your own manager — When the built-in options do not fit, write a URL manager. Derive from UrlManagerBase, which brings the whole asset side, signing included, and write the page side:
  • The middleware that serves it — Nothing maps an endpoint for these URLs: you add a middleware. It is about thirty lines around TryParseUrlForContent and FileHandler.HandleFileAsync: