Working with links

It's best practice to have links in your site to other pages and external sources. But how do you do this? Here, we'll go through how links can be configured in Studio, how the API hub delivers them, and how you can use links in the frontend.

Studio

To allow a Studio user to configure a link, a field of type reference or node (which is the legacy name for a page folder) needs to be added to a Frontend component schema. The difference between reference and node is that the first one gives the user a choice between internal and external links, while the latter only allows internal links to page folders.

Below is an example Frontend component schema that has 3 fields that show how the data is configured:

{
  "tasticType": "example/links-references",
  "name": "Links and references example",
  "icon": "anchor",
  "category": "general",
  "schema": [
    {
      "name": "Configuration",
      "fields": [
        {
          "label": "A link reference",
          "field": "aLinkReferenceField",
          "type": "reference"
        },
        {
          "label": "A page folder reference",
          "field": "aPageFolderReferenceField",
          "type": "reference"
        },
        {
          "label": "A page folder link",
          "field": "aPageFolderField",
          "type": "node"
        }
      ]
    }
  ]
}

The example shows 3 fields to see the different representations of a reference in the API hub further down this article.

When you preview the above JSON in the schema editor, you can see how each would display in the component settings:

API hub data

Once configured, the Frontend component data provided to you by the API hub follows the TypeScript interfaces ReferenceValue (for reference fields) and PageFolderValue:

"aLinkReferenceField": {
  "_type": "Frontastic\\Catwalk\\NextJsBundle\\Domain\\Api\\TasticFieldValue\\LinkReferenceValue",
  "link": "https://example.com",
  "openInNewWindow": false,
  "type": "link"
}

A reference always contains its type (selected in the Studio) and if the link is expected to openInNewWindow. For a LinkReferenceValue, the link property holds the target URL (relative or absolute).

"aPageFolderReferenceField": {
  "_type": "Frontastic\\Catwalk\\NextJsBundle\\Domain\\Api\\TasticFieldValue\\PageFolderReferenceValue",
  "openInNewWindow": false,
  "pageFolder": {
    "_type": "Frontastic\\Catwalk\\NextJsBundle\\Domain\\Api\\TasticFieldValue\\PageFolderValue",
    "_urls": {
      "de_CH": "/sub-page",
      "de_LI": "/sub-page",
      "fr_CH": "/sub-page",
      "it_CH": "/sub-page"
    },
    "configuration": {
      "path": "sub-page",
      "pathTranslations": []
    },
    "name": "Sub",
    "pageFolderId": "8733ddef122e2c9769a2dd441f11a7b9"
  },
  "type": "page-folder"
}

A PageFolderReferenceValue holds a pageFolder instead of the link. This is of type PageFolderValue and contains information about the page folder, such as its name. It also holds the special field _urls, which contains a map of all defined locales to the corresponding path for the page folder. This map allows you to link to the folder in different languages in a multi-language project.

The PageFolderValue is meant to contain a property _url, which holds the path of the page folder in the current locale so that you don't need to care for locale resolution in the frontend. This feature is still to be implemented.

If you use a node type field, the value received is only the inner PageFolderValue, for example:

"aPageFolderField": {
  "_type": "Frontastic\\Catwalk\\NextJsBundle\\Domain\\Api\\TasticFieldValue\\PageFolderValue",
  "_urls": {
    "de_CH": "/",
    "de_LI": "/",
    "fr_CH": "/",
    "it_CH": "/"
  },
  "configuration": {
    "path": "/",
    "pathTranslations": []
  },
  "name": "Main",
  "pageFolderId": "2484aae237475b21de02bc1e2d13b3c4"
}

Links in the frontend

Link values generated by the API hub are meant to be used as they're with the Next.js router, for example:

import Link from 'next/link';

const SimpleLink: React.FC = ({ data }) => {
  return (
    <Link href={aPageFolderField.urls['de_CH']}>{aPageFolderValue.name}</Link>
  );
};

Linking to dynamic pages

For dynamic pages, which have been implemented using the dynamic page handler extension point, we recommend using the same _url (and probably _urls) property scheme shown further up in this article. With that, there's a single unique scheme for handling links in the frontend, and link generation is centrally handled in the backend.