Slugs / URL parts

The main purpose of this type is to define parts of a URL path to generate and resolve URLs. The according database field is generated automatically.

Table of contents:

Introduction

The main purpose of this type is to define parts of a URL path to generate and resolve URLs.

With a URL like https://www.typo3.org/ch/community/values/core-values/ a URL slug is typically a part like /community or /community/values/core-values.

Within TYPO3, a slug is always part of the URL "path" - it does not contain scheme, host, HTTP verb, etc.

A slug is usually added to a TCA-based database table, for example pages. The TCA then contains rules for evaluation and definition.

When applied to pages a hierarchy of pages is often represented by a combined slug: From each page the characteristic last part of its slug is used as path segment. The segments are combined into one slug, separated by slashes. The resulting URL's path is therefore similar to the file paths in common operating systems.

However, slugs in TYPO3 are not limited to be separated by slashes. It is possible to use other separators. Furthermore, a single path segment may contain any sign allowed in URLs, including slashes.

It is not required to build hierarchical paths. It is possible to assign a single, unique path segment to each page in a deep page hierarchy. In TYPO3 the only requirement is that the slug for each page in a domain must be unique.

If a TCA table contains a field called "slug", it needs to be filled for every existing record. It can be shown and edited via regular backend forms, and is also evaluated during persistence via DataHandler.

The default behaviour of a slug is as follows:

A slug only contains characters which are allowed within URLs. Spaces, commas and other special characters are converted to a fallback character.
A slug is always lower-cased.
A slug is unicode-aware.

It is possible to build a default value from the rootline (very helpful for pages, or categorized slugs), but also to just generate a "speaking" segment from e.g. a news title.

Sanitation and Validation configuration options apply when persisting a record via DataHandler.

In the backend forms a validation happens by an AJAX call, which immediately checks any input and receives a new proposal in case the slug is already used.

Example: A basic slug field

This example limits the length of the slug to 50 characters. It takes only the field input_1 into account for generating the slug.

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_slugs.php

[
    'columns' => [
        'slug_2' => [
            'label' => 'slug_2',
            'config' => [
                'type' => 'slug',
                'size' => 50,
                'generatorOptions' => [
                    'fields' => [
                        'input_1',
                    ],
                    'fieldSeparator' => '/',
                    'prefixParentPageSlug' => true,
                ],
                'fallbackCharacter' => '-',
                'eval' => 'uniqueInSite',
                'default' => '',
            ],
        ],
    ],
]

Example: A slug field with prefix hook

This example uses a custom slug prefix hook via config['appearance']['prefix'] to adapt the displayed prefix. It takes the two fields input_1 and input_2 into account for generating the slug.

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_slugs.php

[
    'columns' => [
        'slug_1' => [
            'label' => 'slug_1',
            'description' => 'field description',
            'config' => [
                'type' => 'slug',
                'generatorOptions' => [
                    'fields' => [
                        'input_1',
                        'input_2',
                    ],
                    'fieldSeparator' => '/',
                    'prefixParentPageSlug' => true,
                    'replacements' => [
                        '/' => '',
                    ],
                ],
                'appearance' => [
                    'prefix' => 'TYPO3\\CMS\\Styleguide\\UserFunctions\\FormEngine\\SlugPrefix->getPrefix',
                ],
                'fallbackCharacter' => '-',
                'eval' => 'uniqueInSite',
                'default' => '',
            ],
        ],
    ],
]

Properties of the TCA column type `slug`

Name	Type	Scope
appearance	array	Display
prefix	userFunction	Display
eval	string (list of keywords)	Proc. / Display
fallbackCharacter	string	Proc. / Display
generatorOptions	array	Proc. / Display
fields	array	Proc. / Display
fieldSeparator	string	Proc. / Display
prefixParentPageSlug	boolean	Proc. / Display
replacements	array	Proc. / Display
postModifiers	array	Proc. / Display
prependSlash	boolean	Proc. / Display

appearance

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display

Properties that only apply to how the field is displayed in the backend.

prefix

Type: userFunction
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']
Scope: Display

Provides a string that is displayed in front of the input field. The URL of the site is set by default if nothing has been defined.

Assign a user function. It receives two arguments:

The first argument is the parameters array containing the site object, the language id, the current table and the current row.
The second argument is the reference object TcaSlug.

The user function should return the string which is then used for display purposes.

Example: Set a slug field prefix

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_slugs.php

[
    'columns' => [
        'slug_1' => [
            'label' => 'slug_1',
            'description' => 'field description',
            'config' => [
                'type' => 'slug',
                'generatorOptions' => [
                    'fields' => [
                        'input_1',
                        'input_2',
                    ],
                    'fieldSeparator' => '/',
                    'prefixParentPageSlug' => true,
                    'replacements' => [
                        '/' => '',
                    ],
                ],
                'appearance' => [
                    'prefix' => 'TYPO3\\CMS\\Styleguide\\UserFunctions\\FormEngine\\SlugPrefix->getPrefix',
                ],
                'fallbackCharacter' => '-',
                'eval' => 'uniqueInSite',
                'default' => '',
            ],
        ],
    ],
]

The user function can be implemented like this:

<?php

declare(strict_types=1);

/*
 * This file is part of the TYPO3 CMS project.
 *
 * It is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License, either version 2
 * of the License, or any later version.
 *
 * For the full copyright and license information, please read the
 * LICENSE.txt file that was distributed with this source code.
 *
 * The TYPO3 project - inspiring people to share!
 */

namespace TYPO3\CMS\Styleguide\UserFunctions\FormEngine;

/**
 * A user function to compare two fields
 *
 * @internal
 */
use TYPO3\CMS\Backend\Form\FormDataProvider\TcaSlug;

final class SlugPrefix
{
    public function getPrefix(array $parameters, TcaSlug $reference): string
    {
        return 'custom slug prefix';
    }
}

eval

Type: string (list of keywords)
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc. / Display

Configuration of field evaluation.

Keywords:

unique: Evaluate if a record is unique in the whole TYPO3 installation (specific to a language). This option is recommended as it allows to show any record stored inside other sites. The only downside is that it is not possible to have the same slug on multiple sites.
uniqueInSite: Requires the field to be unique for the current site and language. This allows for multiple records of the same table to have the same slug as long as these records are separated by their sites. Consequently records of a foreign site are not accessible with uniqueInsite since slugs are looked up respecting the current site.

Warning

Be aware that using this option makes it impossible to show records stored inside other sites. If this is required, unique should be used instead.
uniqueInPid: Requires the field to be unique for the current PID among other records on the same page.

No other eval setting is checked for. It is possible to set different eval options, however it is recommended not to do so.

Example: eval = uniqueInSite

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_slugs.php

[
    'columns' => [
        'slug_2' => [
            'label' => 'slug_2',
            'config' => [
                'type' => 'slug',
                'size' => 50,
                'generatorOptions' => [
                    'fields' => [
                        'input_1',
                    ],
                    'fieldSeparator' => '/',
                    'prefixParentPageSlug' => true,
                ],
                'fallbackCharacter' => '-',
                'eval' => 'uniqueInSite',
                'default' => '',
            ],
        ],
    ],
]

fallbackCharacter

Type: string
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc. / Display
Default: -

Character that represents the separator of slug sections, that contain the fieldSeparator.

Example: fallbackCharacter and fieldSeparator set

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_slugs.php

[
    'columns' => [
        'slug_2' => [
            'label' => 'slug_2',
            'config' => [
                'type' => 'slug',
                'size' => 50,
                'generatorOptions' => [
                    'fields' => [
                        'input_1',
                    ],
                    'fieldSeparator' => '/',
                    'prefixParentPageSlug' => true,
                ],
                'fallbackCharacter' => '-',
                'eval' => 'uniqueInSite',
                'default' => '',
            ],
        ],
    ],
]

generatorOptions

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['']
Scope: Proc. / Display

Holds information about the record fields to be used for slug generation:

fields

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['generatorOptions']['fields']
Scope: Proc. / Display

Insert several field names (of type string) that will be considered during slug construction.

Can also be used as nested array to combine multiple fields [['nav_title', 'title'], 'other_field'].

Info

Inserting multiple fields in a simple array would result in an concatenated slug.

Nested array values would result in "take nav_title if not empty, otherwise take value from title".

Examples:

Configuration value	Values of an example page record	Resulting slug
`[['nav_title', 'title']]`	`['title' => 'Products', 'nav_title' => '']`	`/products`
`[['title', 'subtitle']]`	`['title' => 'Products', 'subtitle' => 'Product subtitle']`	`/products`
`['title', 'subtitle']` or `[['title'], ['subtitle']]`	`['title' => 'Products', 'subtitle' => 'Product subtitle']`	`/products/product-subtitle`
`['nav_title', 'title'], 'subtitle'`	`['title' => 'Products', 'nav_title' => 'Best products', 'subtitle' => 'Product subtitle']`	`/best-products/product-subtitle`
`['seo_title', 'title'], ['nav_title', 'subtitle']`	`['title' => 'Products', 'nav_title' => 'Best products', 'subtitle' => 'Product subtitle', 'seo_title' => 'SEO product title']`	`/seo-product-title/best-products`

fieldSeparator

Type: string
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['generatorOptions']['fieldSeparator']
Scope: Proc. / Display
Default: "/"

This value will divide the slug parts. If a section value contains this very value, it will be replaced by the value given in fallbackCharacter.

prefixParentPageSlug

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['generatorOptions']['prefixParentPageSlug']
Default: true
Scope: Proc. / Display

The slugs of parent pages will be prefixed to the slug for the page itself. Disable it for shorter URLs, but take the higher chance of collision into consideration.

Note

This option is exclusively for page records. It won't have an effect on any other records.

replacements

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['generatorOptions']['replacements']
Scope: Proc. / Display

It allows to replace strings of a slug part. Add one of more array items with the key being the string to replace and the value being the replacement string.

postModifiers

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['generatorOptions']['postModifiers']
Scope: Proc. / Display

The "slug" TCA type includes a possibility to hook into the generation of a slug via custom TCA generation options.

Hooks can be registered via:

EXT:myextension/Configuration/TCA/Overrides/table.php

$GLOBALS['TCA'][$tableName]['columns'][$fieldName]['config']['generatorOptions']['postModifiers'][]
    = MyClass::class . '->method';

Consider $tableName = 'pages' and $fieldName = 'slug' inside EXT:my_extension/Configuration/TCA/Overrides/table.php:

EXT:myextension/Configuration/TCA/Overrides/table.php

$GLOBALS['TCA']['pages']['columns']['slug']['config']['generatorOptions']['postModifiers'][] =
    MyClass::class . '->modifySlug';

The method then receives an parameter array with the following values

  [
      'slug', // ...  the slug to be used
      'workspaceId', // ...  the workspace ID, "0" if in live workspace
      'configuration', // ...  the configuration of the TCA field
      'record', // ...  the full record to be used
      'pid', // ...  the resolved parent page ID
      'prefix', // ...  the prefix that was added
      'tableName', // ...  the table of the slug field
      'fieldName', // ...  the field name of the slug field
];

All hooks need to return the modified slug value.

Example: Generate a concatenated slug

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_slugs.php

[
    'columns' => [
        'slug_4' => [
            'label' => 'slug_4',
            'config' => [
                'type' => 'slug',
                'generatorOptions' => [
                    'fields' => [
                        'input_1',
                        'input_2',
                    ],
                    'prefixParentPageSlug' => false,
                ],
                'fallbackCharacter' => '-',
                'eval' => 'uniqueInSite',
                'default' => '',
            ],
        ],
    ],
]

Example: Generate a slug from one field with a backup field if first is empty

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_slugs.php

[
    'columns' => [
        'slug_5' => [
            'label' => 'slug_5',
            'config' => [
                'type' => 'slug',
                'generatorOptions' => [
                    'fields' => [
                        [
                            'input_1',
                            'input_2',
                        ],
                    ],
                    'prefixParentPageSlug' => false,
                ],
                'fallbackCharacter' => '-',
                'eval' => 'uniqueInSite',
                'default' => '',
            ],
        ],
    ],
]

Example: remove all strings "(f/m)" from job titles

This will change the provided slug 'Some Job in city1/city2 (f/m)' to 'some-job-in-city1-city2'.

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_slugs.php

[
    'columns' => [
        'slug_3' => [
            'label' => 'slug_3',
            'description' => 'remove string (f/m)',
            'config' => [
                'type' => 'slug',
                'generatorOptions' => [
                    'fields' => [
                        'input_3',
                    ],
                    'replacements' => [
                        '(f/m)' => '',
                        '/' => '-',
                    ],
                ],
                'fallbackCharacter' => '-',
                'prependSlash' => true,
                'eval' => 'uniqueInPid',
            ],
        ],
    ],
]

prependSlash

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc. / Display

Defines whether a slug field should contain a prepending slash, for example for nested categories with speaking segments.

If not set, this defaults to false. (Exception: for the pages.slug field this defaults to true and cannot be changed.)

Slugs / URL parts

Introduction

Example: A basic slug field

Example: A slug field with prefix hook

Properties of the TCA column type slug

appearance

prefix

eval

fallbackCharacter

generatorOptions

fields

fieldSeparator

prefixParentPageSlug

replacements

postModifiers

prependSlash

Properties of the TCA column type `slug`