Configuration

This extension ships no frontend TypoScript. What it does ship is the backend page TSconfig that labels the content element group Academic, the group every academic extension sorts its content elements into.

That page TSconfig is delivered in three ways, and the first one needs no configuration at all:

Configuration/page.tsconfig of this extension, which TYPO3 includes for the whole installation. The group is therefore labelled on every installation, whatever the site configuration says.
The site set fgtclb/academic-base-ctype-group, for a site configuration that lists it — usually because another academic extension depends on it.
The page TSconfig file registered for the page field Page TSconfig.

All three read the same file, so nothing changes when more than one of them applies.

What the sets contain

Set	Delivers
`fgtclb/academic-base-ctype-group`	The label of the content element group Academic in the new content element wizard.
`fgtclb/academic-base`	Everything above. This is the set to use unless you deliberately want a subset.

Every academic extension that ships content elements depends on fgtclb/academic-base-ctype-group, so a site that includes one of those sets gets this one with it and needs no entry of its own.

No content element is hidden by default

This extension ships no content element of its own, so it hides none. The content elements of the other academic extensions are hidden for the whole installation and brought back per component by the extension that ships them — see the Configuration chapter of that extension.

An existing content element keeps its hidden type

A content element that already exists keeps its content type on a page where that type is not enabled — a site that does not include the component, or a page that restricts the content types with its own page TSconfig. The Type field shows the stored type as the selected option, followed by (not enabled on this page), so saving the record leaves the type as it is.

Choosing another type and saving changes it as usual; the hidden type is not offered again afterwards. A new content element is only offered the types enabled on its page.

This covers every content element in the Academic group, without any configuration. Content types of other extensions keep the behaviour of TYPO3, which selects the first available option instead. See Important: A hidden academic content type stays selected.

Include the site set

Add the set to the config.yaml of the site:

config/sites/my-site/config.yaml (diff)

 base: 'https://example.com/'
 rootPageId: 1
+dependencies:
+  - fgtclb/academic-base

Include static templates

For an installation that configures itself through records rather than through a site configuration, the same file is registered as a selectable page TSconfig file.

Include static TypoScript

This extension ships no TypoScript and therefore registers no static template.

Include static page TSconfig

Edit the page record of the site root, tab Resources, field Page TSconfig, and add the entry:

Entry	Delivers
Academic Base: Content element group (academic_base)	The label of the content element group Academic.
Academic Base: All components (academic_base)	Every component this extension ships, in one entry.

The setting is inherited by every page below the one it is set on.

Do not combine both

For this extension both mechanisms assign the same two values, so combining them is harmless. For the academic extensions that also ship TypoScript it is not — see the Configuration chapter of the extension in question. Use one mechanism per site.

Icons that follow the text colour

This extension ships an icon provider for the other academic extensions and for site packages: \FGTCLB\AcademicBase\Imaging\IconProvider\CurrentColorSvgIconProvider. It inlines the SVG file as the icon markup, in the default markup as well as in the inline alternative markup, so an icon drawn in currentColor takes the colour of the text around it - the backend colour scheme, or the theme of the frontend.

The core provider \TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider renders the default markup as an <img> tag. An image is opaque to CSS, so such an icon keeps the colours of its file. That is right for a brand icon drawn in fixed colours and meant to look the same on every background, and wrong for anything that should match the text next to it - a record icon in the record list as much as an action icon in a button.

The academic extensions register every icon they ship with it, starting with the shared icon set of this extension, see Icons. Category type and group icons are registered programmatically by EXT:category_types and ask for it with inlineIcon: true in the Configuration/CategoryTypes.yaml that declares them.

Opting in

Register the icon with this provider instead of the core one, in the file of the registry that shows it: Configuration/FrontendIcons.php of the extension that ships it for an icon a frontend template renders (see Frontend icons), Configuration/Icons.php for an icon the backend shows. The academic extensions decide by the group of the identifier, see Identifiers and files: an action, a state or the glyph in front of a piece of information is a frontend icon, the icon of a record type, a content element or a page type a backend icon.

EXT:my_extension/Configuration/FrontendIcons.php

return [
    'tx-myextension-action-add' => [
        'provider' => \FGTCLB\AcademicBase\Imaging\IconProvider\CurrentColorSvgIconProvider::class,
        'source' => 'EXT:my_extension/Resources/Public/Icons/action/add.svg',
    ],
];

Nothing else changes: the icon is rendered as before, in a frontend template with <ab:icon identifier="tx-myextension-action-add" />, and a backend icon with the <core:icon> ViewHelper, with IconFactory::getIcon(), or as a typeicon_classes entry of a TCA table. Whether the inline alternative markup is requested or not, the markup is the inlined file.

What the SVG file must look like

The file is inlined into the HTML of the page, possibly several times, so it has to be drawn for that:

A viewBox attribute on the root element; without it the element cannot scale.
width="1em" and height="1em" for an icon used in the frontend. Both core versions keep the two attributes, and with them the icon follows the font size of the text around it. The backend needs neither: its CSS sizes every icon through the wrapper.
fill="currentColor" or stroke="currentColor" on every drawable element, and no hardcoded colour anywhere - not as an attribute and not in a <style> element. A hardcoded colour is exactly what this provider exists to avoid.
No id attributes and no <style> element. The markup may appear more than once in one document, and once inlined an id and a style rule are global: two files that both carry Adobe Illustrator's defaults (id="SVGID_1_", .st0) will paint each other's shapes and resolve each other's clip-path.
No <script> element and no event handler attributes. The provider sanitises the content on both core versions - TYPO3 v14 does it itself, and on TYPO3 v13, whose getInlineSvg() removes <script> elements and nothing else, the provider runs \TYPO3\CMS\Core\Resource\Security\SvgSanitizer before inlining. That is a filter, not a licence: the provider is still meant for files an extension ships and registers itself, never uploads.
A comment does not survive the sanitiser on either core version. A licence attribution the icon set requires can stay inside the file for whoever reads the repository, but the rendered page never carries it - give it in the documentation or a credits line where the licence requires attribution in the output.

EXT:my_extension/Resources/Public/Icons/add.svg

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">
    <!-- Attribution of the icon set, when its licence requires one -->
    <path fill="currentColor" d="M7 2h2v5h5v2H9v5H7V9H2V7h5z"/>
</svg>

A file that does not exist renders empty markup rather than a broken image, so check a new registration once in the backend or with a rendering test.

The icons of the academic extensions follow a stricter house format on top of these rules: Font Awesome Free solid, one 640 unit grid for every icon and fill="currentColor" on the root element, see Icons.

Frontend icons

This extension keeps a registry of its own for the icons a visitor sees. The icon registry of TYPO3 is built for the backend: it loads every core icon, the record icons and the flags with it, and its icons are styled by the backend stylesheet. The frontend registry holds only what extensions and site packages register for the frontend. Neither registry reads the other.

Registering an icon

Every active extension and site package can ship Configuration/FrontendIcons.php. It has the format of Configuration/Icons.php: an array of icon identifiers to the icon provider and its options. Every icon provider of TYPO3 can be used, and \FGTCLB\AcademicBase\Imaging\IconProvider\CurrentColorSvgIconProvider for an SVG drawn in currentColor. An entry without a provider gets the one TYPO3 derives from the file name, the SVG provider for a file ending in svg and the bitmap provider for every other file.

EXT:my_sitepackage/Configuration/FrontendIcons.php

return [
    'my-sitepackage-download' => [
        'provider' => \FGTCLB\AcademicBase\Imaging\IconProvider\CurrentColorSvgIconProvider::class,
        'source' => 'EXT:my_sitepackage/Resources/Public/Icons/download.svg',
    ],
];

The files are read in the loading order of the packages, and a package loaded later replaces the whole configuration of an identifier an earlier one registered. A site package replaces an icon of an academic extension by registering the same identifier, provided it loads after that extension: it requires the extension in its composer.json, and in classic mode names it under depends in its ext_emconf.php as well.

An icon that both the frontend and the backend show, such as a category type icon, is registered in both files with the same configuration. A site that replaces it replaces it in both.

An entry whose provider is not an icon provider makes every icon of the view helper fail with an error that names the entry, so a typo in a class name is found on the first page rather than shipped.

Rendering an icon

The view helper icon of this extension renders an icon of the frontend registry. It takes the arguments of <core:icon> with the same defaults: identifier, size (default small), overlay, state (default default), alternativeMarkupIdentifier, for example inline, and title. The markup is the one <core:icon> renders for an icon registered with the same provider and options, so a stylesheet written for one fits the other.

EXT:my_sitepackage/Resources/Private/Partials/Download.html

<html xmlns:ab="http://typo3.org/ns/FGTCLB/AcademicBase/ViewHelpers"
      data-namespace-typo3-fluid="true">

<ab:icon identifier="my-sitepackage-download" alternativeMarkupIdentifier="inline" />

</html>

Unlike <core:icon>, a title appears only on the icon rendered with it, also when the same icon is rendered several times on one page.

The view helper reads the frontend registry only. An icon registered in Configuration/Icons.php alone, or one of TYPO3's own icons, is unknown to it. An unknown identifier renders the placeholder default-not-found, the red drawing TYPO3 shows for an unknown icon, marked data-identifier="default-not-found". This extension registers it in its own Configuration/FrontendIcons.php, so a site package replaces it like any other icon.

Icons from code

An extension that computes its icons contributes them through the event \FGTCLB\AcademicBase\Event\CollectFrontendIconsEvent, see CollectFrontendIconsEvent.

Caching

The registry is built once and kept with the system caches. A change to a Configuration/FrontendIcons.php, or to what a listener contributes, takes effect after the system caches are flushed, as a change to Configuration/Icons.php does:

vendor/bin/typo3 cache:flush --group system

Installing or removing an extension needs no flush, the registry is kept per set of active packages. vendor/bin/typo3 cache:warmup builds it, so the first frontend request after a deployment does not.