.. index:: ! Templates .. _templates: ========= Templates ========= This extension ships Fluid partials the academic extensions share: the responsive image they render their images through, and the fields of a frontend form. Their paths and arguments are public API, and change only with a breaking changelog entry. .. _templates-image: The responsive image partial ============================ :file:`EXT:academic_base/Resources/Private/Partials/Academic/Image.html` renders one image of a record for the frontend: * a raster image as a :html:`` with one WebP :html:`` per breakpoint of the preset, and a fallback :html:`` in the original format that loads lazily and states its width and height; * an SVG image as one :html:`` of the original file, without sources and without processing; * the placeholder as one :html:`` when there is no image, and nothing when there is no placeholder either. A template of an academic extension renders it like this, here the card of :guilabel:`EXT:academic_persons`, :file:`Partials/Profile/Item/Image.html`, with the settings that choose the crop variant of its view and the placeholder: .. code-block:: html For a raster image of the development instances, that renders, shortened to the elements and their attributes: .. code-block:: html Portrait of Jane Doe The fallback :html:`` is the original file here, because it is narrower than the 690 pixels of the preset, and an image is never scaled up. The card passes no class of its own, so the image carries `ace-image` alone, followed by the space the empty argument leaves. The alternative text and the title are those of the file reference. The template of the persons card picks the crop variant of its view and a placeholder per gender before it renders the partial, see the :guilabel:`Profile image` chapter of :guilabel:`EXT:academic_persons`. .. _templates-image-arguments: Arguments --------- .. list-table:: :header-rows: 1 :widths: 20 80 * - Argument - Meaning * - `image` - An Extbase or a core file reference. Empty renders the placeholder. * - `preset` - `card`, `detail`, `logo` or `teaser`. Required: an unknown preset fails the rendering instead of silently rendering no image. * - `cropVariant` - The crop variant applied to every source and to the fallback image, `default` when empty. A variant without a crop area on the image renders the image uncropped. * - `placeholder` - An `EXT:` path to a public file, rendered when there is no image. Empty renders nothing. A path that does not resolve fails the rendering, as :html:`` does. * - `alt` - The alternative text. Empty uses the alternative text of the file. * - `class` - The class of the image element: the fallback :html:``, the SVG or the placeholder. The partial puts its own class `ace-image` in front of it. * - `showCaption` - Renders the description of the file in a :html:`
`. * - `showCopyright` - Renders the copyright of the file in the :html:`
`. The field exists with the core extension `filemetadata` only; without it, nothing is rendered and no error is raised. The :html:`
` around the image is rendered only when a caption or a copyright is requested and the file has one. The partial gives its elements the classes `ace-picture`, `ace-figure`, `ace-caption`, `ace-description` and `ace-copyright`. .. _templates-image-presets: Presets ------- Every preset is a section of the partial holding its sources and the width of its fallback image. A width is a maximum: an image is never scaled up. .. list-table:: :header-rows: 1 * - Preset - Sources (media query: maximum width) - Fallback * - `card` - `min-width: 992px`: 390, `min-width: 768px`: 370, `min-width: 576px`: 690, otherwise 535 - 690 * - `detail` - `min-width: 992px`: 1200, `min-width: 576px`: 960, otherwise 540 - 1200 * - `logo` - `min-width: 768px`: 320, otherwise 240 - 320 * - `teaser` - `min-width: 992px`: 600, `min-width: 576px`: 720, otherwise 540 - 720 `teaser` has no upstream consumer yet; it gives a project a stable name for teaser images rather than a section of its own in an override. WebP output needs `webp` in :php:`$GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']`, which the core default configuration contains on TYPO3 v13 and v14. An installation that removed it gets the exception 1618992262 of the core image view helpers for every raster image the partial renders. .. _templates-image-override: Overriding the partial ---------------------- The academic extensions that render the partial register the path :file:`EXT:academic_base/Resources/Private/Partials/` in their plugin view with the key `-1`, below every key they use themselves. A project overrides the partial like any other partial of the plugin: it places its own :file:`Academic/Image.html` in the partial root path it configures through the constant of that plugin. One override per plugin changes the markup, the presets and the breakpoints of every image that plugin renders. The extensions that ship a page template for their page type - `EXT:academic_partners`, `EXT:academic_programs` and `EXT:academic_projects` - register the same path in :typoscript:`page.10.partialRootPaths`, and `EXT:academic_jobs` does it for the partials it registers there. That array belongs to the site package, so the key is a negative one of its own per extension rather than `-1`: it sorts below every theme and project path, and replaces none of them. A project that replaces the partial root paths of such a plugin completely has to list the academic_base path itself: .. code-block:: typoscript plugin.tx_academicpersons.view.partialRootPaths { -1 = EXT:academic_base/Resources/Private/Partials/ } Without it, the plugin fails on the partial it cannot resolve. .. _templates-form: The form partials ================= The partials below :file:`EXT:academic_base/Resources/Private/Partials/Academic/Form/` render the fields of an Extbase form with a label, a required mark, the validation state and a help text. :guilabel:`EXT:academic_jobs` renders its new job form through them. .. list-table:: :header-rows: 1 :widths: 25 75 * - Partial - Renders * - `Textfield` - A text field of the input type its validation settings name. * - `Textarea` - A text area, with the class `ace-ckeditor` when the element sets `richtext`. * - `Select` - A select of the element's `options`, read through `optionValueField` and `optionLabelField`, with an optional first option of `prependOptionValue` and `prependOptionLabel`. * - `Checkbox` - A checkbox with the value `1`. * - `DateTime` - A date field showing the element's `value` as `Y-m-d`, the only format a date input accepts. * - `Upload` - A file upload. * - `FieldWrapper` - The label, the required mark, the validation state, the messages of a rejected field and the help text around a field. Every field partial renders it. * - `ErrorMessage` - The message of one validation error of a field, see below. * - `Errors` - One alert above the form when any field failed validation. A field partial takes these arguments: .. list-table:: :header-rows: 1 :widths: 25 75 * - Argument - Meaning * - `element` - The field: `identifier` and `validations`, the validation set of the form, and per field `disabled`, `help` and the options of the select. * - `objectName` - The name of the form object, `job` for example. The id of a field is `.`. * - `extensionName` - The extension of the label `create...label` and the placeholder `edit...placeholder`. * - `fieldWrapperPartial` - The partial around the field, `Academic/Form/FieldWrapper` when it is not given. It receives `element`, `elementId`, `class`, `elementContent` and `extensionName`. `Errors` takes the form object as `object`, and `objectName` and `extensionName` for the message `create..incorrectValues`. A field that failed validation gets the class `invalid`, in place of the class `f3-form-error` the form field ViewHelpers set by default, and the attributes `aria-invalid="true"` and `aria-describedby="-error"`. `FieldWrapper` renders the messages of the field right after it, in the element `
`, one `
` per message. The title of the required mark is the label `create.required` of the extension. The elements of a field carry these classes: the wrapper `ace-field`, `invalid` when the field failed validation, and the class of its type the field partial passes, `ace-text-wrap`, `ace-textarea-wrap`, `ace-select-wrap`, `ace-checkbox-wrap`, `ace-date-wrap` or `ace-upload-wrap`, the label `ace-label`, the required mark `ace-required`, the field `ace-control` and its type, `ace-text`, `ace-textarea`, `ace-select`, `ace-checkbox`, `ace-date` or `ace-upload`, and the help text `ace-help`. `Errors` renders its message in an `ace-errors`. `ErrorMessage` shows the first of these that exists, each given the arguments of the error, so a label can name the rejected value with `%s`: the label `create..error.` for the field and the error code, the label `create.error.` for the error code, the message of the validator. An extension that renders the fields under partial names of its own passes its own wrapper name as `fieldWrapperPartial`, so a project that overrides that wrapper changes every field. The new job form does so with :file:`Job/Forms/FieldWrapper.html`, and a project overrides the names below :file:`Job/Forms/` of :guilabel:`EXT:academic_jobs`, not these.