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 in Frontastic? Here, we'll go through how links can be configured in Frontastic studio, how the API hub delivers them, and how you can use links in the frontend.

Frontastic studio

To allow a Frontastic 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 Frontastic 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 Frontastic page folders.

Below is an example Frontastic component schema that has three 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.

Once uploaded to Frontastic studio, the reference configuration within the component settings panel looks like this:

800800

API hub data

Once configured, the Frontastic 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 Frontastic 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.

🚧

Missing _url field

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 Frontastic 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 Frontastic 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.


Did this page help you?