.. index:: Templates; Override .. _templates-override: ==================== Overriding templates ==================== EXT:academic_jobs is using Fluid as template engine. This documentation won't bring you all information about Fluid but only the most important things you need for using it. You can get more information in the section :ref:`Fluid templates of the Sitepackage tutorial `. A complete reference of Fluid ViewHelpers provided by TYPO3 can be found in the :ref:`ViewHelper Reference ` .. index:: Templates; TypoScript Change the templates using TypoScript constants ----------------------------------------------- As any Extbase based extension, you can find the templates in the directory :file:`Resources/Private/`. If you want to change a template, copy the desired files to the directory where you store the templates. We suggest that you use a sitepackage extension. Learn how to :ref:`Create a sitepackage extension `. .. code-block:: typoscript # TypoScript constants plugin.tx_academicjobs { view { templateRootPath = EXT:mysitepackage/Resources/Private/Extensions/myextension/Templates/ partialRootPath = EXT:mysitepackage/Resources/Private/Extensions/myextension/Partials/ layoutRootPath = EXT:mysitepackage/Resources/Private/Extensions/myextension/Layouts/ } } .. index:: Templates; Labels Change the labels of the job properties --------------------------------------- The job list and the job detail view render the properties of a job through one loop, in :file:`Resources/Private/Partials/Job/Item.html` respectively :file:`Resources/Private/Partials/Job/Information.html`. The loop takes every label from :file:`Resources/Private/Language/locallang.xlf`, which follows three rules: * ``jobs.`` is the row label of a property, for example ``jobs.workLocation`` or ``jobs.link``. * ``jobs..`` is the label of a value of a select property: ``jobs.type.1`` to ``jobs.type.3`` and ``jobs.employmentType.1`` to ``jobs.employmentType.2``. * Two properties are rendered without their stored value and therefore carry a label that is a full statement: ``jobs.internationalsWelcome`` and ``jobs.alumniRecommend``. They are rendered only when the flag is set. The ``link`` property is the one exception to the first rule: it renders the row label ``jobs.link`` and, as the text of the anchor, ``jobs.linkText``. Override any of them the way you override a label of an extension, without copying the partial: .. code-block:: typoscript # TypoScript setup plugin.tx_academicjobs._LOCAL_LANG { default.jobs.linkText = To the application form de.jobs.linkText = Zum Bewerbungsformular } Every label of the extension, and the path of each content element, is listed in :ref:`configuration-labels`. .. index:: Templates; Icons .. _templates-override-icons: Replace the icon of a job property ---------------------------------- The same loop renders an icon in front of every property. Each property has an identifier of its own, ``tx-academicjobs-info-`` and the property name in kebab case, for example ``tx-academicjobs-info-work-location`` for ``workLocation``. The loop lists every property it shows together with the name of its icon: .. code-block:: html … The contact block renders ``tx-academicjobs-info-contact-phone`` and ``tx-academicjobs-info-contact-email`` in front of the phone number and the e-mail address. The extension also registers ``tx-academicjobs-info-starttime``, ``tx-academicjobs-info-contact-name`` and ``tx-academicjobs-info-contact-additional-information``, which no shipped template renders, so an override that adds one of these properties to the loop gets an icon without registering one. The icons are the shared Font Awesome Free glyphs of :guilabel:`EXT:academic_base`, several properties share one. They are inlined and drawn in `currentColor`: they take the colour of the surrounding text and are as large as its font, so they need no CSS of their own. These are frontend icons. They are registered in :file:`Configuration/FrontendIcons.php` and rendered with the ``ab:icon`` ViewHelper of :guilabel:`EXT:academic_base`. Replace one by registering a file of your own under its identifier in the :file:`Configuration/FrontendIcons.php` of your site package, which has to depend on the extension so that its entry is read last. The other properties keep their icons, also those that show the same glyph: .. code-block:: php :caption: EXT:mysitepackage/Configuration/FrontendIcons.php [ 'provider' => CurrentColorSvgIconProvider::class, 'source' => 'EXT:mysitepackage/Resources/Public/Icons/Location.svg', ], ]; :php:`CurrentColorSvgIconProvider` inlines a file drawn in `currentColor`, like the shipped icons. A file in other colours is registered with the :php:`\TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider` of TYPO3, which renders it as an image of 16 by 16 pixels. An entry in :file:`Configuration/Icons.php` does not reach the job views. An override of :file:`Job/Item.html`, :file:`Job/Information.html` or :file:`Job/Contact.html` renders these icons with ``ab:icon`` and declares ``xmlns:ab="http://typo3.org/ns/FGTCLB/AcademicBase/ViewHelpers"`` in its :html:`` tag. With ``core:icon`` it shows TYPO3's not-found icon, see :ref:`breaking-jobs-job-icons-moved-to-the-frontend-icon-registry`. The content element icon and the job record icon both draw the Font Awesome Free briefcase of the shared set, :file:`EXT:academic_base/Resources/Public/Icons/info/employment.svg`, see :ref:`third-party-icons`. .. index:: Templates; Images The image of a job ------------------ The job list item renders the job image through the shared partial :file:`Academic/Image.html` of `EXT:academic_base`, whose arguments and presets are documented in the `Templates` chapter of that extension. It asks for the preset `card` with the crop variant `default`. This extension defines no crop variants, so `default` stays free-ratio and an employer logo is not cut; an SVG logo is passed through unprocessed whatever the preset says. Two consequences for an override: * Overriding :file:`Job/Item.html` alone changes where the image sits, not how it is rendered. To change the markup, the breakpoints or the widths, place an :file:`Academic/Image.html` of your own in the partial root path above. * The partial root path of `EXT:academic_base` is registered below the constant above, so the copy wins. A view of your own that renders :file:`Job/Item.html` has to list that path itself, or the rendering fails on a partial it cannot resolve. Pick a key of your own rather than the one this extension uses, and list it under `paths` too if your page object is a :typoscript:`PAGEVIEW`, which reads no `partialRootPaths`: .. code-block:: typoscript # TypoScript setup page.10 { partialRootPaths.-1700000001 = EXT:academic_base/Resources/Private/Partials/ paths.-1700000001 = EXT:academic_base/Resources/Private/ } .. index:: Templates; Form fields .. _templates-override-form-fields: Change the fields of the new job form ------------------------------------- Every field of the :guilabel:`New job form` is rendered by a partial below :file:`Job/Forms/`: :file:`Textfield.html`, :file:`Textarea.html`, :file:`Select.html`, :file:`Checkbox.html`, :file:`DateTime.html` and :file:`Upload.html`, each wrapped by :file:`FieldWrapper.html`, and the alert above the form by :file:`Errors.html`. Override these names. They render the shared form partials of :guilabel:`EXT:academic_base`, described in its :guilabel:`Templates` chapter, and pass :file:`Job/Forms/FieldWrapper` on as the wrapper, so an override of :file:`Job/Forms/FieldWrapper.html` changes the label and the required mark of every field at once. .. index:: Templates; New job form .. _templates-override-new-job-form: Add a field to the new job form ------------------------------- The :guilabel:`New job form` renders the partial :file:`Job/Forms/AdditionalFields.html` between the job properties and the submit button. The partial the extension ships renders nothing, so a field such as a captcha is added by placing a :file:`Job/Forms/AdditionalFields.html` of your own in the partial root path above, without copying :file:`Templates/Job/New.html` or :file:`Partials/Job/Properties/Job.html`. The partial receives every variable of the form template. Name such a field outside the ``job`` argument of the form. The field below is submitted as ``tx_academicjobs_newjobform[captcha]`` and is not mapped to the job. A field bound to the job with ``property`` must name a property the job model has: the property mapping rejects any other one and the submission fails. .. code-block:: html
The partial only renders the field. The extension neither checks its value nor dispatches an event before the job is stored, so a site checks a captcha answer before the request reaches the plugin, in a middleware for example. .. index:: Templates; New job form confirmation .. _templates-override-new-job-form-confirmation: Keep the confirmation in a copy of the form template ---------------------------------------------------- A visitor who returns to the form after a saved job sees the confirmation above the form. :file:`Templates/Job/New.html` renders it, inside the element with the class `academic-jobs-new`, from a queue of its own: .. code-block:: html :caption: The line of :file:`Templates/Job/New.html` that renders the confirmation A copy of the template in a site package takes this line over. Without it the confirmation waits in the session of the visitor, and the visitor sees the empty form. The confirmation for a redirect page is queued elsewhere, see :ref:`integrator-job-form-flash-messages`.