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 studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`., how the API hub delivers them, and how you can use links in the frontend.

Frontastic studio

To allow a Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. 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 componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. 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 componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. 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 studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`., the reference configuration within the component settings panel looks like this:

API hub data

Once configured, the Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. data provided to you by the API hubAPI hub - The API hub combines our code, your code, and APIs to create the backend of a commerce site. Any backend development or extensions are done here. Known as `Catwalk` in code. 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?