{backlinks:item_id:slice_ids:sort}

Description

Returns the dash-separated IDs of every active item that links to a given item. A backlink is an item somewhere in your site that points at the target through a relation field (or any other field that stores the target id), so backlinks answers the question "what references this item?" - the reverse of following a relation outward. Internally it is a wrapper around the ids command, searching all text fields of the chosen slices for the target id, so the result is a plain id list you can feed to count, view, foreach or item. With no second parameter it scans every slice that shares a site module with the target item, sorted by slice then publish date (newest first); pass a dash-separated list of slice IDs to restrict the search. The third parameter overrides the sort (for example category descending then headline ascending); pass a single dash to skip sorting entirely, which is the fastest way to just collect the ids. If the item id is missing or the item does not exist, backlinks returns an empty string.

Parameters

item_id required default (none)

The item whose backlinks you want - normally the current item via the id getter. backlinks looks up this item, finds its site module, then searches for other items that store this id. If the id is empty or no such item exists, the result is an empty string.

slice_ids optional default all slices in the target item's site module

Dash-separated list of slice IDs to search for backlinks. Leave empty to search every slice that shares a site module with the target item (the default). Restricting to one or a few slices is faster and lets you ask, for example, only which articles link here, ignoring comments or tags.

sort optional default slice then publish date, newest first

Order of the returned ids, written like an ids sort clause - one or more fields separated by commas, each optionally suffixed with a dash for descending (for example category.......1-,headline........). Leave empty for the default sort by slice then publish date, newest first. Pass a single dash to skip sorting entirely, which is the quickest way to just collect the ids.

Examples

test[{backlinks:5726c2c6b035d7aab450d1794e9e90d7:9e1d2b9f88e3d6c3bf0eb967378610d6}]
Expected[]
Actual[]
When no active item links to the target, backlinks returns an empty string. Here the target is a stable test item that nothing references; the square brackets are only there to make the empty result visible.
test{count:{backlinks:5726c2c6b035d7aab450d1794e9e90d7:9e1d2b9f88e3d6c3bf0eb967378610d6}}
Expected0
Actual0
Wrap backlinks in count to get how many items link to the target - a common way to show a reference count. This stable test item has none, so the count is 0.
test[{backlinks:00000000000000000000000000000000}]
Expected[]
Actual[]
If the item id does not match any item, backlinks returns an empty string rather than an error. Useful so templates degrade quietly when an id is wrong or the item was deleted.
virtual{backlinks:{id..............}}
Expected(ids of items that link to the current item, sorted by slice then newest first)
Actualcb2553db0e88c139756d04a4d6af035e
The everyday use - inside a slice or view template, ask which items link to the item being shown. id is the current item getter; with no other parameter backlinks scans every slice in the same site module.
virtual{backlinks:{id..............}::-}
Expected(ids of linking items, in no particular order)
Actualcb2553db0e88c139756d04a4d6af035e
Leave the slice list empty and pass a single dash as the sort to skip ordering. This is the quickest form when you only need the raw id list, for example to feed count or to test whether any backlinks exist.
virtual{view:57:{backlinks:{id..............}}}
Expected(view 57 rendered for each item that links to the current item)
Feed the backlink ids straight into a view to render the linking items - a built-in see-also or what-links-here block. Replace 57 with a view that formats the listed items the way you want.
← All expressions