: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 ===================== 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-contacts4pages-list` - The :guilabel:`Person’s Contacts on the Page` content element: its TypoScript (`plugin.tx_academiccontacts4pages`), the data processor that assigns the contacts of a page to the page template, and the page TSconfig that makes the content element selectable in the backend. * - `fgtclb/academic-contacts4pages` - Everything above. This is the set to use unless you deliberately want a subset. Both depend 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. What the content element shows, and the options an editor sets on it, is described in :ref:`integrator`. .. note:: The setup of this extension reads :typoscript:`{$plugin.tx_academicpersons.detailPid}` — a constant this extension does not declare and that belongs to :guilabel:`EXT:academic_persons`. Further constants of that extension are mapped the same way, because the partials rendering a contact read them: whether the names link to the detail view :typoscript:`{$plugin.tx_academicpersons.detailLink}`, the crop variant of the lists :typoscript:`{$plugin.tx_academicpersons.image.list.cropVariant}`, the image placeholders :typoscript:`{$plugin.tx_academicpersons.image.placeholder.default}`, :typoscript:`{$plugin.tx_academicpersons.image.placeholder.mr}`, :typoscript:`{$plugin.tx_academicpersons.image.placeholder.ms}` and :typoscript:`{$plugin.tx_academicpersons.image.placeholder.diverse}`, and the phone link prefix :typoscript:`{$plugin.tx_academicpersons.phoneNumbers.telPrefix}`. Nothing has to be done about it. The component names that extension's TypoScript in its own :file:`include_static_file.txt`, and both delivery mechanisms read that file, so the constant resolves whether this extension arrives through its site set or through its static template. The site set deliberately does *not* depend on a set of :guilabel:`EXT:academic_persons`. Such a dependency would not deliver the constant, and it would make that extension's content element selectable wherever this one is enabled. .. _configuration-hidden-by-default: The content element is hidden by default ======================================== :guilabel:`EXT:academic_contacts4pages` 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:`Person’s Contacts on the Page` selectable in the backend again — without one of them the content element is not offered, and existing records keep rendering. .. _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-contacts4pages 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 Contacts4Pages: Contact list (academic_contacts4pages)` - The TypoScript of the :guilabel:`Person’s Contacts on the Page` content element. * - :guilabel:`Academic Contacts4Pages: All components (academic_contacts4pages)` - Every component this extension ships, in one entry. * - :guilabel:`Academic Contacts4Pages: Path up to 2.3 (deprecated, use All components) (academic_contacts4pages)` - The same as :guilabel:`All components` without the TypoScript of EXT:academic_persons, 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 Contacts4Pages: Contact list (academic_contacts4pages)` - Makes the :guilabel:`Person’s Contacts on the Page` content element selectable, and configures its entry in the new content element wizard. * - :guilabel:`Academic Contacts4Pages: All components (academic_contacts4pages)` - Every component this extension ships, in one entry. The setting is inherited by every page below the one it is set on. .. _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. For this extension those are the three Fluid root paths of the plugin and the :ref:`content element header ` switch. 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-contact-list: The contact list ================ The options of the content element, :guilabel:`Show hidden records` and :guilabel:`Group by role`, are described on its page, :ref:`integrator-contacts-list`. .. _configuration-contact-item-partial: The contact item partial ------------------------ :file:`Contacts/List.html` arranges the contacts and renders each of them through :file:`Contacts/Item.html` of this extension — in the role groups, below them and in the list that is not grouped. The grid column around the partial belongs to the list template. By default the partial renders the profile item of `EXT:academic_persons`. To change the card of a contact, override this partial rather than the list template: .. code-block:: typoscript :caption: TypoScript setup plugin.tx_academiccontacts4pages.view.partialRootPaths.20 = EXT:my_sitepackage/Resources/Private/Extensions/academic_contacts4pages/Partials/ .. list-table:: :header-rows: 1 * - Argument - Holds * - `contact` - The contact. * - `role` - The role of the contact, or nothing when it has none. * - `profile` - The profile behind the contract of the contact. * - `contract` - The contract the contact names. * - `settings` - The plugin settings. * - `data` - The content element record, as an array. * - `grouped` - Set when the contact renders below the heading of its role. The default partial then renders the profile name one heading level lower and leaves out the role name, which the heading already shows. The list template also receives `record`, the content element as a record object. A project list template that renders the header partial of `EXT:fluid_styled_content` itself needs it on TYPO3 v14 — which only makes sense where the layout of the content element leaves the header out, as it is rendered twice otherwise. See :ref:`the changelog entry ` for what such a template needs. The shipped template renders the header itself while :ref:`the switch below ` is on, so a copy made for the header alone is no longer needed. .. _configuration-page-contacts: The contacts in a page template =============================== The data processor of this extension hands the contacts of a page to a page template, for a page layout that shows them outside the content area, as a sidebar or a slide-in panel. The shipped TypoScript attaches it to :typoscript:`page.10`, where most site packages, the bootstrap package among them, put their page template, by its identifier `academic-page-contacts`. The contacts are the ones the content element shows: a contact whose contract or profile is not visible is left out, and a listener of the :ref:`page contacts event ` reaches both outputs. .. list-table:: :header-rows: 1 * - Variable - Holds * - `contacts` - The contacts of the page, in the order they are sorted on the page. * - `roles` - The roles at least one of those contacts has, keyed by the uid of the role. * - `contactsWithoutRole` - The contacts that have no role, which the grouped list of the content element renders below the role groups. The processor takes three options, each with :typoscript:`stdWrap`: .. list-table:: :header-rows: 1 * - Option - Default - Effect * - :typoscript:`as` - empty - The variable that holds `contacts`, `roles` and `contactsWithoutRole`. Without it, the three are written at the top level of the page template. * - :typoscript:`showHiddenRecords` - `0` - `1` shows hidden contacts and the hidden e-mail addresses, phone numbers and addresses of a contact, as the :guilabel:`Show hidden records` option of the content element does. The page is cached with them, so every visitor sees them. * - :typoscript:`pageUid` - the page that is rendered - The page whose contacts are read. Without it, the processor does nothing when it is attached to an object whose current record is not a page, a content element for example. Contacts are edited in the form of their page and stored on it, so saving them clears the cache of that page. A page that shows the contacts of another page through :typoscript:`pageUid` is not cleared with it and keeps the old contacts until its own cache is cleared. The page TSconfig of the page the contacts belong to can clear it as well: .. code-block:: typoscript :caption: Page TSconfig of the page whose contacts are shown elsewhere TCEMAIN.clearCacheCmd = 42 The options go on the shipped entry: .. code-block:: typoscript :caption: TypoScript setup page.10.dataProcessing.400 { as = pageContacts showHiddenRecords = 0 } A site package that defines its page object after this extension's TypoScript is included, or that renders a further page object, a page type of its own for example, attaches the processor there by the same identifier. Assigning a new content object to :typoscript:`page.10` keeps the properties set before, the shipped :typoscript:`dataProcessing.400` included, so clear it first, or the processor runs twice. A processor attached twice to one page object on purpose needs a variable name for at least one of them, or the second overwrites the first: .. code-block:: typoscript :caption: TypoScript setup page.10 > page.10 = PAGEVIEW page.10 { paths.10 = EXT:my_sitepackage/Resources/Private/Templates/ dataProcessing { 40 = academic-page-contacts 40.as = pageContacts } } .. code-block:: html :caption: A page template reading the contacts below `pageContacts`

{role.name}

{contact.contract.profile.firstName} {contact.contract.profile.lastName}

{contact.contract.profile.firstName} {contact.contract.profile.lastName}

 A page template that renders the contacts through the :file:`Profile/Item` partial of :guilabel:`EXT:academic_persons` needs the partial root paths of that extension and of :guilabel:`EXT:academic_base` in its view, see :ref:`breaking-contacts4pages-profile-images-render-as-picture`. The partial reads the detail page and whether the names link from the settings the page template passes to it. The data processor provides no settings, so the mapping of the content element described in :ref:`configuration-components` does not reach a page template. The class name :php:`\FGTCLB\AcademicContacts4pages\DataProcessing\ContactsProcessor` in place of the identifier keeps working, for TypoScript written before the identifier existed. .. _configuration-content-element-header: The header of the content elements ================================== The header and the subheader an editor enters on a :guilabel:`Person’s Contacts on the Page` 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_academiccontacts4pages.renderContentElementHeader = 1 The extension declares no site settings, so a site that uses the site set sets the constant in :file:`config/sites//constants.typoscript`. 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_academiccontacts4pages.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.