: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 ` for what happens otherwise. .. _configuration-components: What the sets contain ===================== This extension ships six content elements, so it ships six component sets and one aggregate set that depends on all of them. All six are driven by one Extbase plugin, so they share one TypoScript block, :typoscript:`plugin.tx_academicpersons`. That block is shipped once, in :file:`Configuration/TypoScript/Default/`, and every component includes it. Which component sets a site names therefore decides which content elements the backend offers, not how much TypoScript is loaded. .. list-table:: :header-rows: 1 * - Set - Delivers * - `fgtclb/academic-persons-list` - The :guilabel:`Person List` content element. * - `fgtclb/academic-persons-list-and-detail` - The :guilabel:`Person List and Details` content element. * - `fgtclb/academic-persons-detail` - The :guilabel:`Person Details` content element. * - `fgtclb/academic-persons-card` - The :guilabel:`Person Contact Card` content element, and the FlexForm restriction that hides the list, sorting and pagination fields for it. * - `fgtclb/academic-persons-selected-profiles` - The :guilabel:`Selected Person’s Profiles` content element. * - `fgtclb/academic-persons-selected-contracts` - The :guilabel:`Selected Person’s Contracts` content element. * - `fgtclb/academic-persons` - Everything above. This is the set to use unless you deliberately want a subset. * - `fgtclb/academic-persons-default` - The name this extension published before the sets were cut per component. It delivers exactly what `fgtclb/academic-persons` delivers, and is kept so that existing site configurations keep working. * - `fgtclb/academic-persons-standalone` - Everything the aggregate delivers, plus a :typoscript:`page` object that renders content on a plain Bootstrap page. Meant for an installation without a site package of its own — an alternative to `fgtclb/academic-persons`, never an addition to it. Every 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. The site settings of this extension are declared with the aggregate set: the detail page, whether the names link to it, the default grouping, sorting and pagination of a profile list, the selected letter of the letter navigation, the crop variants and placeholders of the profile image, the phone link prefix and the :ref:`content element header ` switch below. A site that depends on a single component set still gets the shipped defaults, but can only override them in :guilabel:`Site Settings` when it depends on `fgtclb/academic-persons`. .. _configuration-detail-link: Names without a detail link =========================== The name of every profile in the list, card, selected profiles and selected contracts elements links to the profile's detail view: on the detail page the element or the site names, or on the page of the element when neither names one. A site without profile detail pages, an A to Z directory or contact cards only, shows the names as text instead: .. confval:: plugin.tx_academicpersons.detailLink :name: plugin-tx-academicpersons-detaillink :type: string :Default: ``link`` `link` links the names to the detail view, `none` shows them as text, in the table view mode as well. The list-and-detail element always links its names, because it shows the detail view itself. A detail page a template passes to the item partial links as well, see :ref:`templates-item-partials-detail-page`. The contact list of :guilabel:`EXT:academic_contacts4pages` follows the setting, it has no option of its own. An element can choose otherwise with its option :guilabel:`Link the names to the detail view`, see :confval:`Link the names to the detail view `. On a site that uses the site set, the setting is :guilabel:`Link the names to the detail view` of `fgtclb/academic-persons`. It is declared for the site set and as a constant of the shared static template, with the same default in both. `link` without a detail page keeps linking the names to the page of their element, with the arguments of the detail view, because a site may place the detail plugin on the page of its list. .. _configuration-phone-link-prefix: The prefix of a phone link target ================================= Every phone number this extension renders is a link, and the number is written into its :html:`tel:` target without the spaces it is stored with. An installation that stores phone numbers as extensions only — the part that is the same for every number left out — has no dialable target that way, and this setting is what completes it. .. confval:: plugin.tx_academicpersons.phoneNumbers.telPrefix :name: plugin-tx-academicpersons-phonenumbers-telprefix :type: string :Default: empty Prepended to the :html:`tel:` target of every phone number, in the list, card and selection elements, in the profile detail view and in the contacts of a page. The spaces of prefix and number alike are removed from the target. The visible link text is not touched: it keeps the number as it is stored, without the prefix. The prefix is applied unconditionally, so an installation that stores full numbers, or a mixture of full numbers and extensions, leaves it empty. The setting is declared for the site set and as a constant of the shared static template, with the same default in both — see :ref:`Do not combine both `. .. _configuration-letter-navigation: The selected letter of the letter navigation ============================================ The letter navigation of the list elements is an option of the content element, see :confval:`Alphabetical Pagination `. What the selected letter does is a setting: .. confval:: plugin.tx_academicpersons.alphabet.activeLetterResets :name: plugin-tx-academicpersons-alphabet-activeletterresets :type: boolean :Default: ``0`` Off, the selected letter is marked as the current one and is not a link. On, it is still marked as the current one, and links back to the list without a letter — the target of :guilabel:`A-Z`. A visually hidden "show all profiles" tells assistive technology where the link leads. The setting is declared for the site set and as a constant of the shared static template, with the same default in both. .. _configuration-view-modes: View modes ========== The list, list-and-detail, selected profiles and selected contracts elements render their profiles in a view mode, which the options :guilabel:`View Mode Default` and :guilabel:`View Mode Toggle` of the content element choose, see :confval:`View Mode Default `. Two settings decide which modes exist and what the table shows: .. confval:: plugin.tx_academicpersons.viewMode.allowed :name: plugin-tx-academicpersons-viewmode-allowed :type: string :Default: ``list,table`` The modes the elements may render, comma separated. Neither the default of a content element nor the request of a visitor renders a mode outside this list: such a default falls back to the tiles - or to the first allowed mode where the tiles are not allowed - and such a request to the default. A mode is a plain name, a lowercase letter followed by letters and digits; an entry of any other shape is ignored. .. confval:: plugin.tx_academicpersons.table.columns :name: plugin-tx-academicpersons-table-columns :type: string :Default: ``name,position,emailAddresses,phoneNumbers,room`` The columns of the table, comma separated, in this order. The shipped columns are ``name``, ``position``, ``organisationalUnit``, ``emailAddresses``, ``phoneNumbers`` and ``room``. The name links to the detail view; the contract columns show the value of every contract the element shows for the profile, one per line. The fields of the content element (:guilabel:`Show only selected Fields`) apply to the table as they apply to the tiles: while the element names fields there, a contract column whose field it does not name - ``contracts.room`` for ``room`` - is left out. The name, and a column of your own, stay. Both settings are declared for the site set and as constants of the shared static template, with the same default in both. A mode of your own is a partial and an entry in the allowed modes, see :ref:`adding a view mode `; its URL is described in :ref:`the route enhancers `. .. _configuration-plugin-options: Options of the content elements =============================== The options an editor sets in a content element are described with the element, in :ref:`integrator`. That is where these two topics moved: * :ref:`Filters for visitors ` of the list elements. * :ref:`Which contracts a profile shows `, and how :ref:`the page cache follows the validity ` of a contract. .. _configuration-contract-select-storage-scope: Restrict the backend contract selects ===================================== Two backend fields let an editor pick a contract: the :guilabel:`Contract` of a page contact record of :guilabel:`EXT:academic_contacts4pages`, and :guilabel:`Selected contracts` of the :guilabel:`Selected Person’s Contracts` content element. Both offer every contract of the installation — in an installation with more than one site, that is every site's contracts, each labelled with a person's name. Page TSconfig restricts a field to the pages the contracts of that page tree are stored on. Page TSconfig is inherited down the page tree, so each site configures its own folders on its root page. The setting is opt-in, and without it nothing changes. Respecting the Extbase storage page instead is deliberately not done: a page tree without an explicitly configured storage page would get an empty select and no error. .. confval:: itemsProcFunc.storagePids :name: contract-select-storage-pids :type: string, a comma-separated list of page uids :Default: empty The pages a contract has to be stored on to be offered. Empty — the default — offers every contract of the installation. .. confval:: itemsProcFunc.recursive :name: contract-select-recursive :type: integer :Default: ``0`` How many levels below each listed page are included. The default ``0`` uses the listed pages themselves. A hidden folder is included as well, because a storage folder is regularly hidden. Set them on the page record of the site root, tab :guilabel:`Resources`, field :guilabel:`Page TSconfig`. The path of the FlexForm field is the longer one: it carries the data structure identifier and the sheet, and the dot in the element's name is escaped. .. code-block:: typoscript :caption: Page TSconfig of a site root # The "Contract" field of a page contact record. TCEFORM.tx_academiccontacts4pages_domain_model_contact.contract.itemsProcFunc { storagePids = 42,84 recursive = 1 } # The "Selected contracts" field of the content element. TCEFORM.tt_content.pi_flexform.academicpersons_selectedcontracts.sDEF.settings\.selectedContracts.itemsProcFunc { storagePids = 42,84 recursive = 1 } A contract the record already references stays selectable even when it is stored outside the listed pages. Without that, opening and saving the record would drop the relation, because a select offers no other source for its value. The restriction is applied before :php:`\FGTCLB\AcademicBase\Event\ModifyTcaSelectFieldItemsEvent` is dispatched, so a listener of that event still has the last word. .. _configuration-hidden-profiles: Profiles that are not public ============================ A profile whose :guilabel:`Visible` switch is off, the :sql:`hidden` field of the record, is left out of every public output: the lists with their counts, letters and pages, the selected profiles, and the detail page, which answers with the page-not-found response of the site. The field is shared by every language of the profile. With :composer:`fgtclb/academic-persons-edit` installed, owners switch it themselves in the profile editor, and the documentation of that extension describes how an installation takes the switch away from them. An internal directory, one that only logged-in visitors reach, lists those profiles as well. Put the list and the detail element on a page restricted to a frontend user group and switch :guilabel:`Show hidden records` on in both. Two limits apply: * The directory lists every hidden profile, whether its owner or an editor hid it. An installation that has to tell the two apart needs a field of its own. * :guilabel:`EXT:academic_contacts4pages` never shows a hidden profile as a contact of a page, whatever :guilabel:`Show hidden records` says. Start time, end time and the frontend user groups of a profile keep applying in both directories. .. _configuration-hidden-contracts: Contracts that are not public ============================= A contract has one visibility, its :guilabel:`Visible` switch, the :sql:`hidden` field of the record. A hidden contract is left out of the lists, the detail view and the selected contracts, together with its position, addresses, e-mail addresses and phone numbers, while the profile itself is still shown. The field is shared by every language of the contract. With :composer:`fgtclb/academic-persons-edit` installed, owners show and hide their contracts themselves with the hide action of each contract row. :guilabel:`Show hidden records` of the selected contracts element shows hidden contracts as well, for an internal directory. Until 3.0 a contract also had a :guilabel:`Show this contract online?` toggle, which no public view read. It is removed, see :ref:`breaking-contract-publish-field-removed`. .. _configuration-crop-variants: The crop variants of the profile image ====================================== The image cropper of a profile image offers three crop variants. A template requests one by its name, through the `cropVariant` argument of :html:`` or of the image partial of :guilabel:`EXT:academic_base`: .. list-table:: :header-rows: 1 * - Name - Aspect ratio * - `default` - Free, 16:9, 3:2, 4:3 and 1:1 * - `square` - 1:1 * - `portrait` - 3:4 `default` is the variant TYPO3 offers when a file field configures none, with the same ratios, and the templates of this extension render it unless a site chooses another one per view, see :ref:`templates-profile-image-crop-variant`. A crop an editor stored before the update is stored under that name and keeps its meaning. An image stores a crop for the new variants once an editor opens it in the backend form and saves the record. Until then a template that requests `square` or `portrait` renders the image uncropped. Where the image already has a crop for `default`, the cropper starts `square` from that crop, fitted into its ratio, and `portrait` from the whole image, fitted and centred; an image without a crop starts both from the whole image. A site that does not want a variant disables it in TCA, on this field only: .. code-block:: php :caption: Configuration/TCA/Overrides of the site package $GLOBALS['TCA']['tx_academicpersons_domain_model_profile']['columns']['image']['config']['overrideChildTca']['columns']['crop']['config']['cropVariants']['portrait']['disabled'] = true; Page TSconfig is not the way to do that. `TCEFORM.sys_file_reference.crop.config.cropVariants` reaches every image below the page it is set on, and on an image field that configures no variants of its own it leaves the cropper with no variant at all, not even `default`. A project that defines crop variants of its own for the profile image does so at the same path. A variant it sets by name replaces the one of the same name and leaves the others; assigning the whole array replaces all of them. Crop variants a project configures on `sys_file_reference` for every image are merged with these on the profile image: the values of this extension win key by key, and a ratio the project adds to a variant of the same name stays. A project that restricted `default` to a fixed ratio that way therefore finds all the ratios of the TYPO3 default offered on the profile image again, and the free ratio preselected on an image without a crop. .. _configuration-content-element-header: The header of the content elements ================================== The header and the subheader an editor enters on a :guilabel:`Person List`, :guilabel:`Person Details`, :guilabel:`Person List and Details`, :guilabel:`Person Contact Card`, :guilabel:`Selected Person’s Profiles` or :guilabel:`Selected Person’s Contracts` content element are rendered by the content element layout of the site, as for any other content element. The layouts of :guilabel:`EXT:fluid_styled_content` and of the bootstrap package do that, and the plugins render no header of their own. A site whose content element layout renders no header, because its element templates render it instead, lets the plugins render it: .. code-block:: typoscript :caption: TypoScript constants plugin.tx_academicpersons.renderContentElementHeader = 1 On a site that uses the site set, that is the site setting :guilabel:`Render the content element header in the plugins` of `fgtclb/academic-persons`. The templates then render the header partial of :guilabel:`EXT:fluid_styled_content` above their output, for every header layout except :guilabel:`Hidden`. Do not switch it on where the layout renders the header: the header then appears twice. The extension does not require :guilabel:`EXT:fluid_styled_content`. It adds the partial path of that extension below every other one, so a site package that ships a :file:`Header/All.html` of its own renders that one instead, and a site without :guilabel:`EXT:fluid_styled_content` provides the partial that way. For the header layout :guilabel:`Default`, the partial takes the heading level from :typoscript:`plugin.tx_academicpersons.settings.defaultHeaderType`, which is mapped from the constant :typoscript:`styles.content.defaultHeaderType` of :guilabel:`EXT:fluid_styled_content`. A site that does not include the TypoScript of :guilabel:`EXT:fluid_styled_content` sets the setting itself; without it, such a header renders as an empty :html:`
` element. .. _configuration-hidden-by-default: The content elements are hidden by default ========================================== :guilabel:`EXT:academic_persons` hides all six of its content elements for the whole installation and brings them back per component. Whichever of the two mechanisms below you use, it is what makes an element selectable in the backend again — without one of them the content element is not offered, and existing records keep rendering. .. warning:: This changed in version 2.4. Before it, all six elements were selectable on every page of every installation. Read :ref:`Breaking: Site sets and static templates have been restructured ` before upgrading. An existing content element on a page that does not enable its component keeps its type: the backend shows the stored type followed by :guilabel:`(not enabled on this page)`, and saving keeps it. Content elements whose type an earlier save already replaced are not repaired, the record history shows their former type. .. _site-set: Include the site set ==================== Add the set to the :file:`config.yaml` of the site that should offer the content elements: .. code-block:: diff :caption: config/sites/my-site/config.yaml (diff) base: 'https://example.com/' rootPageId: 1 +dependencies: + - fgtclb/academic-persons See also `TYPO3 Explained, Using a site set as dependency in a site `__. .. _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 Persons: All components (academic_persons)` - Every component this extension ships, in one entry. This is the entry to use. * - :guilabel:`Academic Persons: Shared plugin settings (academic_persons)` - The shared :typoscript:`plugin.tx_academicpersons` block on its own. This is what installations selected before version 2.4, then named :guilabel:`Academic Persons Settings`. The stored value did not change, so such a record keeps working untouched. * - :guilabel:`Academic Persons: Standalone page (academic_persons)` - Everything :guilabel:`All components` delivers, plus the :typoscript:`page` object of the standalone flavour. Do not select it on a site that has a site package of its own. There is one further entry per component — :guilabel:`Academic Persons: Profile list`, :guilabel:`Academic Persons: Profile list and detail`, :guilabel:`Academic Persons: Profile detail`, :guilabel:`Academic Persons: Profile card`, :guilabel:`Academic Persons: Selected profiles` and :guilabel:`Academic Persons: Selected contracts`. They exist so that the static mechanism has the same shape as the sets. Because all six components share one TypoScript block, each of them delivers the same thing, and selecting more than one of them changes nothing. .. _static-pagetsconfig: Include static page TSconfig ---------------------------- This is the half that decides which content elements the backend offers. Edit the page record of the site root, tab :guilabel:`Resources`, field :guilabel:`Page TSconfig`, and add the entries for the content elements the page tree should offer: .. list-table:: :header-rows: 1 * - Entry - Delivers * - :guilabel:`Academic Persons: All components (academic_persons)` - Every component this extension ships, in one entry. * - :guilabel:`Academic Persons: Profile list (academic_persons)` - Makes the :guilabel:`Person List` content element selectable, and configures its entry in the new content element wizard. * - :guilabel:`Academic Persons: Profile list and detail (academic_persons)` - The same for :guilabel:`Person List and Details`. * - :guilabel:`Academic Persons: Profile detail (academic_persons)` - The same for :guilabel:`Person Details`. * - :guilabel:`Academic Persons: Profile card (academic_persons)` - The same for :guilabel:`Person Contact Card`, plus the FlexForm restriction of that element. * - :guilabel:`Academic Persons: Selected profiles (academic_persons)` - The same for :guilabel:`Selected Person’s Profiles`. * - :guilabel:`Academic Persons: Selected contracts (academic_persons)` - The same for :guilabel:`Selected Person’s Contracts`. The setting is inherited by every page below the one it is set on. .. _configuration-javascript: Load the script or bring your own ================================= The :guilabel:`Profile detail` and the :guilabel:`Profile list and detail` content elements load the module :js:`@fgtclb/academic-persons/frontend/profile.js` on the page that shows a profile. It opens and closes the entries of the profile, keeps the section navigation below a sticky page header and marks the section in view when the site loads Bootstrap. No list of this extension loads a script. It is switched off per site, for an installation that brings its own: .. list-table:: :header-rows: 1 * - Site setting and constant - Default - Off means * - :yaml:`plugin.tx_academicpersons.assets.js` - :yaml:`true` - The page does not load the module. With the site set, it is a site setting of `fgtclb/academic-persons`, like every other setting of this extension: .. code-block:: yaml :caption: config/sites/my-site/settings.yaml plugin.tx_academicpersons.assets.js: false With the static template, it is the TypoScript constant of the same name: .. code-block:: typoscript :caption: Constants of the root sys_template record plugin.tx_academicpersons.assets.js = 0 **The profile does not work without a script.** The markup stays exactly as it is, and the entries of the profile are rendered folded: each panel carries the attribute :html:`hidden`, and only a script removes it. A script of your own addresses the same markup, starting from the element :html:`[data-academic-persons-detail]`: * a button :html:`[data-academic-persons-accordion-trigger]` per entry, whose :html:`aria-controls` names the panel it opens, and which has to set :html:`aria-expanded` and remove :html:`hidden` from that panel, * :html:`[data-academic-persons-sticky-navigation]` and :html:`[data-academic-persons-scrollspy-navigation]`, the section navigation, which works as plain anchor links without a script. A project that overrides :file:`Templates/Profile/Detail.html` keeps whatever its copy loads, until it wraps its own :html:`` in :html:``. The switch is about the script of the profile only. A site that includes the set `fgtclb/academic-persons-standalone` keeps loading the Bootstrap script and stylesheet that its page object takes from a content delivery network, whatever the switch says: that page object belongs to the page, not to the plugin. .. _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//constants.typoscript` — and it resets every constant the extension ships a default for back to that default. 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. .. _configuration-integration: Search, permissions and the wizard ================================== The :ref:`Integration chapter of academic_base ` covers what an installation runs beside the academic extensions: an index queue for the profiles of this extension with EXT:solr, the tables, fields and content types an editor group needs as a preset for b13/permission-sets, and how to move, rename or order the academic content elements in the new content element wizard. .. toctree:: :maxdepth: 5 :titlesonly: General/Index Sections/Index Validations/Index FrontendUserSync/Index ProfileCleanup/Index ManagedFields/Index RouteEnhancers/Index Labels/Index