:navigation-title: Configuration

..  _configuration:

=============
Configuration
=============

This extension ships its frontend TypoScript and its backend page TSconfig in
two forms: as TYPO3 **site sets**, and as classic **static templates** plus
**page TSconfig files** that are selected on a page. Both forms read the very
same files, so they configure an installation identically.

Pick one of them per site and stay with it — see
:ref:`Do not combine both <one-mechanism-per-site>` for what happens otherwise.

..  _configuration-components:

What the sets contain
=====================

The extension ships one content element, so it ships one component set and one
aggregate set that depends on it.

..  list-table::
    :header-rows: 1

    *   -   Set
        -   Delivers
    *   -   `fgtclb/academic-study-plan-content-element`
        -   The :guilabel:`Study Plan` content element: its TypoScript
            (:typoscript:`tt_content.academic_study_plan`, the Fluid root paths
            and the data processor that assigns the semesters and modules to the
            template) and the page TSconfig that makes the content element
            selectable in the backend.
    *   -   `fgtclb/academic-study-plan`
        -   Everything above. This is the set to use unless you deliberately
            want a subset.
    *   -   `fgtclb/academic-study-plan-default`
        -   The name this extension published before the sets were cut per
            component. It delivers exactly what `fgtclb/academic-study-plan`
            delivers, and is kept so that existing site configurations keep
            working.

The component set depends on `fgtclb/academic-base-ctype-group`, the set of
:guilabel:`EXT:academic_base` that labels the content element group all academic
extensions sort their elements into.

..  _configuration-hidden-by-default:

The content element is hidden by default
========================================

:guilabel:`EXT:academic_study_plan` hides its content element for the whole
installation and brings it back per component. Whichever of the two mechanisms
below you use, it is what makes :guilabel:`Study Plan` selectable in the
backend again — without one of them the content element is not offered, and
existing records keep rendering.

This is not new in version 2.4: this extension always hid its content element.
What changed is the file that brings it back and the name it is registered
under — see
:ref:`Breaking: Site sets and static templates have been restructured
<breaking-site-sets-and-static-templates-restructured>`.

..  _site-set:

Include the site set
====================

Add the set to the :file:`config.yaml` of the site that should offer the content
element:

..  code-block:: diff
    :caption: config/sites/my-site/config.yaml (diff)

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

See also `TYPO3 Explained, Using a site set as dependency in a site
<https://docs.typo3.org/permalink/t3coreapi:site-sets-usage>`__.

..  _static-templates:

Include static templates
========================

For an installation that still configures its frontend through
:sql:`sys_template` records, the same files are registered as static templates
and as selectable page TSconfig files.

..  tip::

    On TYPO3 v13 and v14 we recommend the site set — and if you use it, do not
    press the backend button :guilabel:`Create a root TypoScript record` on that
    site. The :sql:`sys_template` record it creates carries the flag
    :guilabel:`Clear` for constants and setup, and that flag discards everything
    the site sets contributed. An installation that is already in that state
    gets its configuration back by selecting the static templates below in that
    very record.

..  _static-typoscript:

Include static TypoScript
-------------------------

Edit the :sql:`sys_template` record of the site root and add the entry to
:guilabel:`Include static (from extensions)`:

..  list-table::
    :header-rows: 1

    *   -   Entry
        -   Delivers
    *   -   :guilabel:`Academic Study Plan: Content element (academic_study_plan)`
        -   The TypoScript of the :guilabel:`Study Plan` content
            element.
    *   -   :guilabel:`Academic Study Plan: All components (academic_study_plan)`
        -   Every component this extension ships, in one entry.
    *   -   :guilabel:`Academic Study Plan: Path up to 2.3 (deprecated, use All
            components) (academic_study_plan)`
        -   The same as :guilabel:`All components`, for a record that still
            stores the path of version 2.3. Deprecated, removed in version 4.0,
            see :ref:`deprecation-legacy-static-template-path`.

..  _static-pagetsconfig:

Include static page TSconfig
----------------------------

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

..  list-table::
    :header-rows: 1

    *   -   Entry
        -   Delivers
    *   -   :guilabel:`Academic Study Plan: Content element (academic_study_plan)`
        -   Makes the :guilabel:`Study Plan` content element selectable,
            and configures its entry in the new content element wizard.
    *   -   :guilabel:`Academic Study Plan: All components (academic_study_plan)`
        -   Every component this extension ships, in one entry.

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

..  _styling:

Style the element
=================

The extension ships no stylesheet. The content element renders the classes and
data attributes :ref:`Templates <templates>` documents, and the stylesheet of
the site package styles them. How the markup is built up, class by class, is
described in :ref:`Styling <styling-markup>`.

The mono repository the extension is developed in carries an example to start
from, the stylesheet of its development instances:
`_academic-study-plan.scss of EXT:academics_dev_site
<https://github.com/fgtclb/academic-extensions/blob/main/packages-dev/dev-site/Resources/Private/Scss/frontend/_academic-study-plan.scss>`__.
It is never shipped with an extension, copy what the site needs.

Three parts of the element depend on rules of that stylesheet, beyond its
appearance:

*   A semester header renders an expand and a collapse glyph, and the
    stylesheet shows one of them, see
    :ref:`The glyphs of a semester header <templates-glyphs>`.
*   The collapsed filter needs
    :css:`.ace-filter .ace-list[hidden] { display: none }`, see
    :ref:`Collapse the category filter <collapsible-filter>`.
*   The accordion of a narrow viewport and the highlighting of a category are
    classes the script writes and the stylesheet gives an effect: :html:`open`
    and :html:`highlighted`.

The shipped icons carry a size of their own, `1em`. The example sizes every
icon of the element to `1.25rem`, which is also what keeps a replacement
drawing without a width and a height of its own visible, see
:ref:`The glyphs of a semester header <templates-glyphs>`.

The label of a dialog trigger is only read out. It carries Bootstrap's
:html:`visually-hidden`, which a site that brings Bootstrap hides already.

Before version 3.0 the extension shipped this stylesheet itself. The setting
:yaml:`plugin.tx_academicstudyplan.assets.css` that switched it off during the
development of 3.0 is gone with it, see
:ref:`breaking-study-plan-ships-no-stylesheet`.

..  _asset-switches:

Skip the script
===============

The content element brings one asset to every page that carries it: the ES
module :js:`@fgtclb/academic-study-plan/frontend/academic-study-plan.js`. A
page without the element does not load it.

It can be switched off per site, for an installation that brings its own
script:

..  list-table::
    :header-rows: 1

    *   -   Setting
        -   Default
        -   Off means
    *   -   :yaml:`plugin.tx_academicstudyplan.assets.js`
        -   :yaml:`true`
        -   The page does not load the script.

With the site set, it is a site setting: edit it in the backend, in the
settings editor of that site, or write it by hand. The editor is the same one
on both TYPO3 versions and only sits elsewhere —
:guilabel:`Site Management > Settings` on TYPO3 v13, and
:guilabel:`Sites > Setup` on TYPO3 v14, which merged it into the module that
edits the site itself.

..  code-block:: yaml
    :caption: config/sites/my-site/settings.yaml

    plugin.tx_academicstudyplan.assets.js: false

With the static template, it is a TypoScript constant of the same name,
:guilabel:`Constants` of the root :sql:`sys_template` record:

..  code-block:: typoscript
    :caption: Constants of the root sys_template record

    plugin.tx_academicstudyplan.assets.js = 0

..  warning::

    Switching the script off leaves the markup exactly as it is. The category
    filter, the semester accordion and the module dialogs do nothing without a
    script — bring your own, addressing the same markup.

    The one part of the markup that is not inert is handled: the single
    :html:`<li>` of the filter list is the template the script clones, and it
    is rendered :html:`hidden` so that its placeholder text never reaches the
    screen. A script of your own has to take that attribute off the items it
    builds from it — otherwise the filter stays empty.

    What stays behind either way is the :html:`<nav>` around that list: a
    labelled navigation landmark with nothing in it until a script fills it.
    It is part of the markup contract, so it is yours to fill or to hide.

    :ref:`Templates <templates>` documents every part the shipped script
    drives, which is the list a script of your own has to address.

..  _collapsible-filter:

Collapse the category filter
============================

The category filter is a row of buttons, one per category the modules of the
plan carry. On a plan with many categories it takes up the first screen before
a visitor has seen a single semester.

Switched on, the filter renders collapsed behind a toggle button that states
whether it is expanded and works by keyboard:

..  list-table::
    :header-rows: 1

    *   -   Setting
        -   Default
        -   On means
    *   -   :yaml:`plugin.tx_academicstudyplan.filter.collapsible`
        -   :yaml:`false`
        -   The filter is hidden until the visitor expands it.

..  figure:: /Images/Screenshots/study-plan-filter-collapsed.png
    :alt: A button Filter by category above the semester columns, the category buttons hidden.
    :class: with-border with-shadow

    With plugin.tx_academicstudyplan.filter.collapsible switched on, the
    filter waits behind its toggle.

..  code-block:: yaml
    :caption: config/sites/my-site/settings.yaml

    plugin.tx_academicstudyplan.filter.collapsible: true

..  code-block:: typoscript
    :caption: Constants of the root sys_template record

    plugin.tx_academicstudyplan.filter.collapsible = 1

The toggle is built by the script rather than rendered by the template, for the
same reason the filter buttons are: a plan whose modules carry no category at
all ends up with an empty filter, and a control that expands nothing would be
worse than none. Two consequences follow:

*   Switching :typoscript:`plugin.tx_academicstudyplan.assets.js` off and
    bringing your own script means bringing the toggle as well. The template
    renders :html:`data-study-plan-filter-collapsible` on the filter list and
    nothing else.
*   The label of the toggle is the one the container carries as
    :html:`data-filter-label`, which is the translation of
    :html:`filter.label`. An override that drops that attribute gets no toggle
    at all rather than an unnamed button, and the filter stays expanded.
*   The collapsed state is the :html:`hidden` attribute, and the stylesheet of
    the site has to give it an effect
    (:css:`.ace-filter .ace-list[hidden] { display: none }`) - the browser's own
    rule for it loses to any author rule that gives the list a :css:`display`.
    See :ref:`Style the element <styling>`.

..  _one-mechanism-per-site:

Do not combine both
===================

A site that uses the site set **and** the static template reads the shipped
files twice. The site set is applied before the :sql:`sys_template` record, so
the second read happens after the site settings and after
:file:`config/sites/<site>/constants.typoscript` — and it resets every constant
the extension ships a default for back to that default. For this extension those
are the three Fluid root paths of the content element, the switch of
:ref:`Skip the script <asset-switches>` and the switch of
:ref:`Collapse the category filter <collapsible-filter>`.

Nothing else is damaged: the :guilabel:`Constants` and :guilabel:`Setup` fields
of the :sql:`sys_template` record, the page TSconfig of a page and the page
TSconfig files selected on a page are all applied afterwards and still win. Use
one mechanism per site and the question does not arise.

..  toctree::
   :maxdepth: 5
   :titlesonly:

   Labels/Index