"Speaking URL fragments" 2.0.0 (EXT:content_slug)

Today I released a new major version of the extension content_slug. It allows using the human-readable fragments beyond the "Section Index" menus and simplifies configuration and templating.

By default, the jump links contain a UID prefix (#c123-interesting-section) to avoid any problems with id attributes in the website template. This prefix — or a possible suffix — previously had to be maintained in several places in the Fluid templates.

Therefore, I had already planned to make the complete URL fragment centrally configurable with TypoScript when I initially created this extension.

Starting with version 2, the extension adds a new variable {fragmentIdentifier} to the Fluid templates of the content elements:

lib.contentElement.variables {
    fragmentIdentifier = COA
    fragmentIdentifier {
        if.isTrue.field = tx_content_slug_fragment

        10 =< plugin.tx_contentslug.urlFragmentPrefix

        20 = TEXT
        20.field = tx_content_slug_fragment

        30 =< plugin.tx_contentslug.urlFragmentSuffix

        stdWrap.trim = 1
    }
}

From now on, this is the only variable you'll need in the Fluid templates, which simplifies templating and avoids typos.

Prefix and suffix are preconfigured separately and can be (de)activated with TypoScript constants.

plugin.tx_contentslug {
    urlFragmentPrefix = TEXT
    urlFragmentPrefix {
        field = uid
        stdWrap.noTrimWrap = |c|-|
        if.isTrue = {$plugin.tx_contentslug.settings.renderPrefix}
    }
}

TYPO3 integrators can customize the prefix under plugin.tx_contentslug, or configure the entire URL fragment directly in the COA of the Fluid variable.

For the "Section Index" menus, I wrote a DataProcessor that processes the URL fragments for the individual links.

The extension documentation contains an overview of the whole configuration.

In the two Header partials, a variable named fragmentIdentifier was already in use. It contained the raw contents of data.tx_content_slug_fragment.

With the implementation of the TypoScript configuration, the previously manually set supplements in the fragment must be removed, such as the c{uid}- prefix in the following example.

Before:

<h1 id="{f:if(condition: fragmentIdentifier, then: 'c{uid}-{fragmentIdentifier}')}" class="{positionClass}">
    <f:link.typolink parameter="{link}">{header}</f:link.typolink>
    <f:if condition="{fragmentIdentifier} && {renderAnchorLink}"><a class="headline-anchor" href="#c{uid}-{fragmentIdentifier}">#</a></f:if>
</h1>

After:

<h1 id="{fragmentIdentifier}" class="{positionClass}">
    <f:link.typolink parameter="{link}">{header}</f:link.typolink>
    <f:if condition="{fragmentIdentifier} && {renderAnchorLink}"><a class="headline-anchor" href="#{fragmentIdentifier}">#</a></f:if>
</h1>

There should be no immediate breaking changes in the two "Section Index" templates since the tx_content_slug_fragment field is read there directly. Nevertheless, it is recommended to switch to the new fragmentIdentifier variable there, too.

Until now, the usage of the human-readable fragments was limited to the "Section Index" menus. Several users had asked whether it would also be possible to use them for links set in the rich text editor.

The biggest problem up to now was the possible individual prefix or suffix, which in version 1.x was maintained directly in the templates. Thanks to the new TypoScript configuration, the complete URL fragment can now be processed in a hook using cObjGetSingle().

When rendering the page, this new hook checks internal links for an existing fragment and overwrites it with the human-readable fragment, if one has been defined by an editor.

All links remain unchanged in the database (t3://page?uid=77#123). Thus, links will stay valid in case the human-readable fragment of a content element is subsequently adjusted or this extension is uninstalled.

Besides the rich text editor, links set in backend fields of type inputLink (such as the header link field) are also supported.

If desired, the hook can be disabled via TypoScript.