Guide 03 · Developer docs

The theme repo and the asset pipeline

Everything a developer changes on a Core dna site lives in its theme repository. This guide covers the repository and its build, printing records in templates, stylesheets and client-side code, and the parts of a site around the main content.

L1–L2
Unit 02 · Records in templates

Linking between records

Records in templates Page 13 of 35 Updated

Take a record's URL from the record with getFullPath(), never from its slug. What the path includes, why it keeps links right when an editor sets a custom URL or moves a page, the empty path, the absolute form, and the other URL getters.

Who this is for. The theme developer writing any link to a page, post, product or custom entity record. Afterwards your links survive custom URLs, moved pages and renamed blogs, and you know which getter to use for a relative link, an absolute one and a link that must not be printed at all.

Always getFullPath()

getFullPath() returns the path that addresses the record on its site, with a leading slash. It knows things a template does not:

  • The custom URL, when an editor has set one: it replaces the whole path.
  • Every parent: a page's path is built from the slugs of all its ancestors, so moving a page in the tree moves its URL.
  • The module's path: a post's path starts with its blog's path, including the blog's custom URL; with the Operation mode setting of the Blogs module on Single blog mode, the blog is left out.

A path built in the template from getSlug() gets each of these wrong the day an editor changes something, and nothing reports it: the link points at a page that does not exist, or at the wrong one.

Template code 
{$href = $post->getFullPath()}
{if $href}
  <a href="{$href}">{$post->getName()|escape}</a>
{else}
  {$post->getName()|escape}
{/if}
{% set href = post.getFullPath() %}
{% if href %}
  <a href="{{ href }}">{{ post.getName()|e }}</a>
{% else %}
  {{ post.getName()|e }}
{% endif %}

An empty path means no link

getFullPath() returns an empty string when no path can be built: a page with a missing slug somewhere in its chain of parents, or a post whose blog the visitor cannot see. Printed as it is, href="" links to the current page. Test the value, as above, and print the name without a link when it is empty.

Absolute URLs

A canonical link, a share link or a URL in structured data needs the scheme and host. Put the current request's in front of the path:

Template code 
<meta property="og:url" content="{$_request->getSchemeAndHost()}{$page->getFullPath()}">
<meta property="og:url" content="{{ _request.getSchemeAndHost() }}{{ page.getFullPath() }}">

On each environment that gives the environment's own host, so a development copy links to itself rather than to the live site.

The other URL getters

GetterReturnsUse it for
getFullPath()The effective path, custom URL includedEvery link
getOriginalFullPath()The path from the tree, ignoring any custom URLRarely: comparing a record's tree position, never a link
getUrl() on a pageA protocol-relative URL on the primary hostname of the site's primary environment, such as //www.example.com/aboutA link that must point at the live site, wherever it is rendered
getUrl() on a postThe same as getFullPath(); deprecatedNothing; use getFullPath()

Use getFullPath() for every link within the site, so a template means the same thing whichever record it is given and whichever environment renders it.

Other language versions

A translated page is a separate record with its own path, not the same path with a language prefix. Link to it from the record: getOtherLanguageVersions() returns the other versions keyed by language code. Translated content and the language switcher has the switcher.

Go deeper
GuideCategories and tags How-toLink to a record without hardcoding its URL How-toGive a record a second URL with a custom URL How-toBuild a breadcrumb trail from a record's ancestors

Was this page helpful?

Your answer goes to the docs team.