--- title: "Configuration" manual: "Academic Projects" version: "3.0" permalink: "https://docs.typo3.org/permalink/fgtclb/academic-projects:configuration@3.0" source: "Configuration/Index.rst" rendered: "2026-10-26T17:55:40+00:00" --- # 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 [Do not combine both](https://docs.typo3.org/permalink/fgtclb/academic-projects:one-mechanism-per-site@3.0) for what happens otherwise. The content elements and the options of their backend forms are described in [For integrators](https://docs.typo3.org/permalink/fgtclb/academic-projects:integrator@3.0). ## What the sets contain {#configuration-components} This extension ships two content elements, so it ships two component sets and one aggregate set that depends on all of them. Both content elements are driven by one Extbase plugin, so they share one TypoScript block, `plugin.tx_academicprojects`. That block is shipped once, in `Configuration/TypoScript/`, 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. | Set | Delivers | | --- | --- | | `fgtclb/academic-projects-project-list` | The [Projects](https://docs.typo3.org/permalink/fgtclb/academic-projects:integrator-project-list@3.0) content element. | | `fgtclb/academic-projects-project-list-single` | The [Selected Projects](https://docs.typo3.org/permalink/fgtclb/academic-projects:integrator-project-list-single@3.0) content element. | | `fgtclb/academic-projects` | Everything above. This is the set to use unless you deliberately want a subset, and it is the name this extension published before the sets were cut per component — a site configuration that depends on it needs no change. | Every content element set depends on `fgtclb/academic-base-ctype-group`, the set of **EXT:academic_base** that labels the content element group all academic extensions sort their elements into. ## The content elements are hidden by default {#configuration-hidden-by-default} **EXT:academic_projects** hides both 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, both elements were selectable on > every page of every installation. Read [Breaking: Site sets and static > templates have been restructured](https://docs.typo3.org/permalink/fgtclb/academic-projects:breaking-site-sets-and-static-templates-restructured@3.0) 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 > **(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. ## What the sets do not control {#what-the-sets-do-not-control} The page type **Academic project** (doktype 30) and its backend layout **AcademicProject** are **not** part of any set, and enabling or not enabling a set never changes them. That is deliberate, not an oversight. Both are values stored on `pages` records: a page carries `doktype = 30` and `backend_layout = pagets__AcademicProject` long before any site configuration is read. Were they delivered by an opt-in set, every page tree on a site that does not use that set would show **\[ MISSING LABEL \]** for the layout, the layout could not be picked for a new page, and the page type would disappear from the page tree wizard. They are therefore registered installation-wide — the page type in TCA ([`Configuration/TCA/Overrides/pages.php`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/TCA/Index.html#file-extension-configuration-tca-overridessomefile-php)), the backend layout in the always-included [`Configuration/page.tsconfig`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/PageTsconfig.html#file-extension-configuration-page-tsconfig) — and stay available on every site of the installation. What a set does deliver for that page type is its **frontend rendering**: the `page` object that picks the Fluid template of the page type is part of the shared TypoScript block, so a site that includes no set of this extension renders such a page with whatever its own site package defines. ## The content of a project page {#project-page-content} A project page renders the content elements of its main column (`colPos = 0`) below the project data, in their manual order and in the language of the page. Any set of this extension, or the static template of the shared block, delivers that, and no other set is needed for it. The content is the variable `projectContent` of the page object, defined inside the condition on the project page type, so it exists on project pages only. It is a `CONTENT` object that renders the records through the `tt_content` object of the site, and it works for a `FLUIDTEMPLATE` and a `PAGEVIEW` page object alike. To render another column, or to slide the content from the parent pages, change the variable inside the same condition: **EXT:my_sitepackage/Configuration/TypoScript/setup.typoscript** ```typoscript [page && traverse(page, "doktype") == 30] page.10.variables.projectContent { select.where = {#colPos}=1 } [END] ``` A page template of your own renders it as `{projectContent -> f:format.raw()}`. Up to 2.x the page template rendered the global object styles.content.getContent, which only the set fgtclb/academic-projects-content-load defined for the whole site. The set and its static template are removed, see Breaking: Project pages render their content without a global path. > [!NOTE] > The page type renders the short description and the funders of a project, > and the project list its short description, through > `` and therefore through the site's > `lib.parseFunc_RTE`. TYPO3 defines that path for every site, so > it needs no configuration; a site that refines it changes how links, allowed > tags and paragraphs of these fields are rendered, exactly as for every other > rich text field. ## The layout of a project page {#project-page-layout} A project page renders inside the page layout of the site package, the way the other pages of the site do: the page template declares a layout and fills its section `Main`. The layout is `Default` unless a setting names another one, which is what [`bk2k/bootstrap-package`](https://packagist.org/packages/bk2k/bootstrap-package) and most site packages provide. | Site setting / constant | Default | Meaning | | --- | --- | --- | | `plugin.tx_academicprojects.page.layout` | `Default` | The Fluid layout of the site package the project page renders its section `Main` into. An empty value is read as `Default`. | It is a site setting of the aggregate set `fgtclb/academic-projects`, and a constant of the same name for a site on the static templates. A site that depends on a component set alone gets the default, but the site settings editor does not offer the setting there. Depend on the aggregate set to configure it. The page template reaches it as the variable `projectPageLayout` of the page object, so it works on a `FLUIDTEMPLATE` and a `PAGEVIEW` page object alike. A site package without a layout `Default` gets the fallback layout of this extension, which renders the section `Main` and nothing else: the page renders without the header, navigation and footer of the site, as it did up to 2.x, rather than failing. A layout `Default` of the site package wins over it. The fallback exists for `Default` only: a layout the setting names has to exist in the site package, or the project page fails as any page with a missing Fluid layout does. ### The parts of a project page {#project-page-partials} The section `Main` renders five partials, each of which can be replaced on its own: | Partial | Renders | | --- | --- | | `Project/Page/Header.html` | The project title, or the title of the page without one, the subtitle of the page and the short description, in one element `
`. | | `Project/Page/Media.html` | The first image of the page, through the shared image partial of **EXT:academic_base**. | | `Project/Page/Categories.html` | The categories assigned to the page, grouped by category type. | | `Project/Page/Facts.html` | The runtime, the budget and the funders of the project. | | `Project/Page/Content.html` | The content elements, the variable `projectContent` described above. | Every partial receives all variables of the page: `{project}`, `{images}`, `{projectContent}`, `{pageRecord}` and those of the site package's page object. `{pageRecord}` is the record of the page on both page object types, `{data}` of a `FLUIDTEMPLATE` page object and `{page.pageRecord}` of a `PAGEVIEW` one. The subtitle is its field `{pageRecord.subtitle}`. The templates and partials of the page type are registered at the key `50` of the page object. Register a directory of your own with a higher key, and its files win: **EXT:my_sitepackage/Configuration/TypoScript/setup.typoscript** ```typoscript # FLUIDTEMPLATE: a directory holding Project/Page/Header.html page.10.partialRootPaths.75 = EXT:my_sitepackage/Resources/Private/Partials/ # PAGEVIEW: a directory holding Partials/Project/Page/Header.html page.10.paths.75 = EXT:my_sitepackage/Resources/Private/ ``` A site package that registers its own paths above `50` needs no line at all - a `PAGEVIEW` site package at `paths.100`, for example: a `Partials/Project/Page/Header.html` of its own wins already. An override of the whole `Pages/AcademicProject.html` keeps working the same way, and renders without a layout, as before. Up to 2.x the page template declared no layout and rendered every part inline, and its paths used the key 100. See Breaking: Project pages render inside the site layout. ## Include the site set {#site-set} Add the set to the `config.yaml` of the site that should offer the content elements: **config/sites/my-site/config.yaml (diff)** ```diff base: 'https://example.com/' rootPageId: 1 +dependencies: + - fgtclb/academic-projects ``` See also [TYPO3 Explained, Using a site set as dependency in a site](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/SiteSets/Index.html#site-sets-usage). ## Include static templates {#static-templates} For an installation that still configures its frontend through `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 **Create a root TypoScript record** on that > site. The `sys_template` record it creates carries the flag > **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. ### Include static TypoScript {#static-typoscript} Edit the `sys_template` record of the site root and add the entry to **Include static (from extensions)**: | Entry | Delivers | | --- | --- | | **Academic Projects: Projects (academic_projects)** | The TypoScript of the **Projects** content element. | | **Academic Projects: Projects (selected) (academic_projects)** | The same for **Selected Projects**. | | **Academic Projects: All components (academic_projects)** | Every component this extension ships, in one entry. | | **Academic Projects: Shared plugin settings and page rendering (academic_projects)** | The shared `plugin.tx_academicprojects` block and the `page` object of the page type, on their own. This is the entry an installation stored before the configuration was cut per component, and it keeps working — but it does not make any content element selectable, which the page TSconfig below does. | ### Include static page TSconfig {#static-pagetsconfig} Edit the page record of the site root, tab **Resources**, field **Page TSconfig**, and add the entry: | Entry | Delivers | | --- | --- | | **Academic Projects: Projects (academic_projects)** | Makes the **Projects** content element selectable, and configures its entry in the new content element wizard. | | **Academic Projects: Projects (selected) (academic_projects)** | The same for **Selected Projects**. | | **Academic Projects: All components (academic_projects)** | Every component this extension ships, in one entry. | The setting is inherited by every page below the one it is set on. ## The category filters {#configuration-list-filter} The filter form of the **Projects** and the **Selected Projects** content elements offers one select per category type of the group `projects`. Three settings change which of them it offers and how, for the whole site: | Site setting and constant | Default | Meaning | | --- | --- | --- | | `plugin.tx_academicprojects.filter.categoryTypes` | empty | The category types to offer, in this order, as a comma separated list of type identifiers, for example `project_department,competence_field`. Empty offers every type that has a category, in the order of the category types of the group. | | `plugin.tx_academicprojects.filter.visibleCount` | 0 | How many filters the form shows right away. The others follow in a **More filters** section the visitor opens, which is open already while one of its filters has a value. 0 shows every filter. | | `plugin.tx_academicprojects.filter.hideDisabledOptions` | 0 | Leaves out a category no listed project carries, instead of offering it as a disabled option. A selected category is always offered. A filter whose categories are all left out still renders, with its "All" option only. | **config/sites/my-site/settings.yaml** ```yaml plugin: tx_academicprojects: filter: categoryTypes: 'project_department,competence_field' visibleCount: 1 hideDisabledOptions: true ``` The settings are site settings of the aggregate set `fgtclb/academic-projects` and constants of the same names for a site on static templates. A site that depends on one of the component sets alone gets the defaults, but the site settings editor does not offer the settings there — both content elements read them, and a set declares settings only for itself. A type is offered only when at least one category of that type exists, and an identifier that is no type of the group is ignored. The settings decide what the form offers, not what the list accepts: a link that filters by a category of a type the form does not offer still filters the list. ### The "All" option of a filter {#the-all-option-of-a-filter} The first option of each filter, the one that selects no category, reads the label `sys_category.projects.allOptions.` of this extension, and falls back to `sys_category.projects.allOptions` ("All options") where a type has none. The extension ships no label per type; a site adds them in TypoScript, for every content element of the extension or for one plugin: **EXT:my_sitepackage/Configuration/TypoScript/setup.typoscript** ```typoscript plugin.tx_academicprojects._LOCAL_LANG { default.sys_category.projects.allOptions.competence_field = All competence fields de.sys_category.projects.allOptions.competence_field = Alle Kompetenzfelder } # Only in the Projects content element: plugin.tx_academicprojects_projectlist._LOCAL_LANG.default.sys_category.projects.allOptions.competence_field = All competence fields ``` A language file override works as well, as for any label of this extension: `$GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride']` on TYPO3 v13, `$GLOBALS['TYPO3_CONF_VARS']['LANG']['resourceOverrides']` on TYPO3 v14, each pointing from [`EXT:academic_projects/Resources/Private/Language/locallang.xlf`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Resources/Private/Language.html#file-extension-resources-private-language-locallang-xlf) to a file of the site package. ### Templates {#templates} The partial `Project/DemandCategories.html` renders the selects from the variable `{filterTypes}`: `{filterTypes.visible}` and `{filterTypes.more}` hold the identifiers of the offered types, in their order, before and behind **More filters**. Where that variable does not reach the partial, in a template that renders the partial with arguments of its own instead of `{_all}`, it offers every type with a category, as before, and the filter types and the visible count have no effect there. To use them, pass `filterTypes` on in a template that renders the partial. Up to 2.3 the form offered every type with a category, all of them right away and with one "All" label, and anything else needed an override of the partial. ## Active filters, reset link and result count {#configuration-active-filters} Three switches add to the filter form of the **Projects** and **Selected Projects** content elements, for the whole site. All three are off by default. | Site setting and constant | Default | Meaning | | --- | --- | --- | | `plugin.tx_academicprojects.filter.showActiveFilters` | 0 | One tag per selected category and one for an active state other than "All", below the form. Each tag links to the list without that selection, every other selection and the sorting kept. The state tag links to the state "All". | | `plugin.tx_academicprojects.filter.showReset` | 0 | A **Reset all filters** link to the page without any list argument, so the list shows what the content element presets. Offered after the visitor selected something, while a category or an active state other than "All" is selected or preset by the content element, also once the visitor removed the preset. On the page as the editor preset it, the link would lead to the page shown. | | `plugin.tx_academicprojects.filter.showResultCount` | 0 | The number of projects found, for example "12 projects found". | **config/sites/my-site/settings.yaml** ```yaml plugin: tx_academicprojects: filter: showActiveFilters: true showReset: true showResultCount: true ``` The settings are site settings of the aggregate set `fgtclb/academic-projects` and constants of the same names, like the filter settings above. - A tag shows a category in the language of the page. - A tag stays a tag when the editor preset its category or state: removing it shows the list without it, and the reset link brings the preset back. - The category tags are shown only while the category filter is, and the state tag only while the state select is: a tag removes what the visitor could change. Where the content element hides both, neither tags nor the reset link are shown. The count is. - Every selected category is a tag, also one whose type the form does not offer (see the filter types above), for example a preset one. Removing it works like for any other tag. - The tags and the reset link come from the partial `Project/ActiveFilters.html`, the count from `Project/ResultCount.html`. Both are rendered by `Project/SortingAndFilters.html`, so a project that overrides that partial does not show them until it renders them as well. The partials use the classes `ace-active-filters` on the list of tags, `ace-active-filter` on a tag, `ace-link` on the links and `ace-count` on the count, and bring no styles. - The reset link needs the variable `{visitorSelection}`, which the list action assigns. A template that renders the partials with arguments of its own has to pass it on, or the list offers no reset link. - The labels are `filter.activeFilters.label`, `filter.activeFilters.remove`, `filter.reset`, `list.resultCount.singular` and `list.resultCount.plural` of this extension. The count labels take the number as `%d`, the remove label the category title as `%s`. The three settings and the two partials. ## The options of the content elements {#configuration-plugin-options} What the **Projects** and the **Selected Projects** content elements show, every option of their backend forms, the state of a project and the state badge on the project cards are described in [For integrators](https://docs.typo3.org/permalink/fgtclb/academic-projects:integrator@3.0). ## The crop variants of the project page media {#configuration-crop-variants} The image cropper of the media of a project page offers three crop variants. A template requests one by its name, through the `cropVariant` argument of `` or of the image partial of **EXT:academic_base**: | Name | Aspect ratio | | --- | --- | | `default` | Free, 16:9, 3:2, 4:3 and 1:1 | | `landscape` | 16:9 | | `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. A crop an editor stored before the update is stored under that name and keeps its meaning. The variants belong to the project page type. The media of a standard page keeps what TYPO3 offers. 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 `landscape` or `portrait` renders the image uncropped. Where the image already has a crop for `default`, the cropper starts `landscape` 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. The extension configures the variants in its own TCA overrides, so the site package has to depend on academic_projects for its line to load later: **Configuration/TCA/Overrides of the site package** ```php $GLOBALS['TCA']['pages']['types'][30]['columnsOverrides']['media']['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 project page media 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 the media field of every page, or on `sys_file_reference` for every image, are merged with these on the project page: 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 project pages again, and the free ratio preselected on an image without a crop. ## The header of the content elements {#configuration-content-element-header} The header and the subheader an editor enters on a **Projects** or **Selected Projects** content element are rendered by the content element layout of the site, as for any other content element. The layouts of **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: **TypoScript constants** ```typoscript plugin.tx_academicprojects.renderContentElementHeader = 1 ``` On a site that uses the site set, that is the site setting **Project lists | Render the content element header** of `fgtclb/academic-projects`. The templates then render the header partial of **EXT:fluid_styled_content** above their output, for every header layout except **Hidden**. Do not switch it on where the layout renders the header: the header then appears twice. The extension does not require **EXT:fluid_styled_content**. It adds the partial path of that extension below every other one, so a site package that ships a `Header/All.html` of its own renders that one instead, and a site without **EXT:fluid_styled_content** provides the partial that way. For the header layout **Default**, the partial takes the heading level from `plugin.tx_academicprojects.settings.defaultHeaderType`, which is mapped from the constant `styles.content.defaultHeaderType` of **EXT:fluid_styled_content**. A site that does not include the TypoScript of **EXT:fluid_styled_content** sets the setting itself; without it, such a header renders as an empty `
` element. ## Do not combine both {#one-mechanism-per-site} A site that uses the site set **and** the static template reads the shipped files twice. The site set is applied before the `sys_template` record, so the second read happens after the site settings and after `config/sites//constants.typoscript` — and it resets every constant the extension ships a default for back to that default. For this extension that is the `plugin.tx_academicprojects` constants block: the three Fluid root paths, the settings of [the category filters](https://docs.typo3.org/permalink/fgtclb/academic-projects:configuration-list-filter@3.0) and the [content element header](https://docs.typo3.org/permalink/fgtclb/academic-projects:configuration-content-element-header@3.0) switch. Nothing else is damaged: the **Constants** and **Setup** fields of the `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. ## Search, permissions and the wizard {#configuration-integration} The [Integration chapter of academic_base](https://docs.typo3.org/p/fgtclb/academic-base/main/en-us/Integration/Index.html#integration) covers what an installation runs beside the academic extensions: an index queue for project pages 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. - [General configuration](https://docs.typo3.org/permalink/fgtclb/academic-projects:general-configuration@3.0) - [Route enhancers](https://docs.typo3.org/permalink/fgtclb/academic-projects:route-enhancers@3.0) - [Labels](https://docs.typo3.org/permalink/fgtclb/academic-projects:labels@3.0)