..  include:: /Includes.rst.txt

..  _introduction:

============
Introduction
============

What does it do?
================

The :guilabel:`Frontend Theme for Extension Development` extension provides a
TYPO3 frontend theme for development purposes. Its job is to give a TYPO3
installation a reasonable frontend to look at and to render against, without
building a site package for it first.

..  important::

    The theme is not finished. What this chapter describes is what the extension
    is for; see the note at the end of this section for what it already does.

The situations it is built for, where an extension has to be seen or exercised
in a frontend rather than only in a test assertion:

*   **Extension development**, to click through what an extension actually
    outputs instead of reading the rendered HTML in a test failure.
*   **DDEV based test instances** of an extension repository, where a throwaway
    TYPO3 installation needs a frontend rendering pages, navigation and
    content elements.
*   **Acceptance tests**, which need a stable and predictable frontend to
    drive a browser against.
*   **Reproducing an issue** in a minimal installation before debugging it.

..  warning::

    This is a development tool, not a production theme. It is meant to be
    required as a development dependency of an extension repository or
    installed into a disposable test instance, and it makes no promise about
    design, markup stability or upgrade paths for a live site.

..  note::

    The theme renders a page once it is enabled for a site — through its site
    set on TYPO3 v13, or through a :sql:`sys_template` record selecting the
    classic static include, which is the only way on TYPO3 v12. See
    :ref:`configuration`. It covers **every classic content element**
    :file:`EXT:frontend` registers, the eleven menu elements, the elements of
    its own, and third-party Extbase plugins, none of which requires
    :file:`fluid_styled_content` — that extension is not a dependency here and
    the development instances do not install it. An installation that has it
    anyway enables a bridge, which keeps the rendering the theme's own — see
    :ref:`feature-fluid-styled-content-bridge`. It ships a set of backend
    layouts, from a bare single column through two and three column grids to
    an article, a cover page and a stack of full width bands. It renders a
    main menu, a section menu and a breadcrumb, and it offers a light/dark
    appearance switch. A seeded ``/styleguide`` page renders the whole
    component library on one page, so the theme can be looked at without
    building content for it first — see :ref:`feature-styleguide`. This
    chapter is extended along with the implemented features.

    Underneath that sits the foundation: TYPO3 v12 and v13 support from one
    code base with :ref:`core version aware <introduction-core-version-aware>`
    classes, wired by the dependency injection container of the running TYPO3
    version.

..  _introduction-core-version-aware:

Core version aware implementations
==================================

Code that has to differ between TYPO3 versions lives in one directory per
supported major version in the repository root — :file:`Core12/` and
:file:`Core13/` on this branch. Shared code — interfaces, abstract base classes
and everything that does not depend on a core version — lives in
:file:`Classes/`.

Only the directory matching the running TYPO3 version is registered in the
dependency injection container, so a service asking for an interface always
receives the implementation matching the current core version. The mechanism
does not depend on how many versions are supported at a time: a version is
added or dropped with its directory, and the shared code stays untouched.

Compatibility
=============

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

    *   -   Branch
        -   Extension
        -   TYPO3
        -   PHP
    *   -   1
        -   1.x
        -   v12.4
        -   8.1 - 8.4
    *   -   1
        -   1.x
        -   v13.4
        -   8.2 - 8.4

One row per supported TYPO3 version, because the PHP ranges differ: PHP 8.1 is
supported for TYPO3 v12 only, as :composer:`typo3/cms-core` 13.4 requires PHP
``^8.2``. The lowest TYPO3 v12 patch level supported is **12.4.22**.

Contributing
============

Contributions are welcome. The development setup, the quality gates and the
commit message rules are described in the :file:`CONTRIBUTING.md` file of the
`source repository <https://github.com/sbuerk/theme-extension-development>`__.