README

GSB 11 Extension gsb_solr

About

The extension gsb_solr extends the standard solr extension to make it work in the context of gsb11.

It provides a custom PageIndexerRequest object that does not use an external http request to fill the solr index. This is necessary due to limitations in the hosting environment. also the TitleTagSearchViewHelper adds te Searchword to the title tag.

Learn more about the GSB 11.

Installation

The best way to install this extension is to start with the GSB Sitepackage Kickstarter extension.

Quick installation without GSB Sitepackage Kickstarter

In a composer-based TYPO3 installation you can install the extension EXT:gsb_solr via composer:

  composer config -g gitlab-domains gitlab.opencode.de && \
  composer config -g repositories.gsb-solr vcs https://gitlab.opencode.de/bmi/government-site-builder-11/extensions/gsb_solr.git

  composer require itzbund/gsb-solr

Upgrade Wizard

There is TYPO3 upgrade wizard gsbsolr_verifyConfigurationWizard to add essential configuration for solr to work. The official documentation for TYPO3 describes how you can run an upgrade wizard.

This upgrade wizard will

• Add scheduler task for reindexing each site and working the solr queue
• Add the typoscript configuration for EXT:gsb_solr to root templates

Configuration

To set up the TypoScript configuration with sane defaults include the GSB Solr Package TypoScript record in your websites root Template Record. There is an upgrade wizard that setups up this configuration if it is missing.

Typoscript: allowedSites

⚠️ Warning: if allowedSites are not configured properly solr will seem eratic: you might see no search results, ever,you might see search results that don't change when content is changed. You cannot delete any index in the solr server from the backend except for the index for (primary) frontend domains either.

If your site is being served on different domains for backend and frontend it's best to add the frontend domain explicitly to the root plugin.tx_solr.search.query.allowedSite typoscript configuration, e.g.:

plugin.tx_solr.search.query.allowedSites = frontend.domain.de

otherwise if indexing for frontend.domain.de the index will not be available to users of the backend domain. This is due to EXT:solr siteHash mechanism and the default value __current_site. If you add both the backend and the frontend domain you might see duplicate results, depending on how the indexing was triggered (backend vs cli/task).

⚠️ Note: allowedSites is configured automatically when using EXT:gsb_solr to use the primary (non-variant) domain of a site (which can differ from what __current_site means). If you want to configure it differently, you have to do it explicitly in Typoscript (e.g. for search accross sites in a multi-site setup)

Scheduler Tasks

For the EXT:solr to work properly in TYPO3 you need to set up at least one scheduler task (Index Queue Worker and Force Re-Indexing of a site).

Take a good look at the scheduler task documentation for solr.

⚠️ Warning: The worker should only be configured to index 5-10 documents per run. This is due to our indexer needing a lot of memory as everything is processed in the same request context.

Extension configuration: Indexer modes

This extension provides three indexer modes, which can be configured in the extension settings

⚠️ Note: on readonly systems this can only be configured via environment variables

Feature Flags

This document explains how to use feature flags. We separate between two different kinds of feature flags:

Feature

Feature flags allow you to enable or disable specific features in your installation. \ This is of particular importance to disable features that have not passed the approval process.

Optional

Optional flags allow you to (de-)activate specific features for your installation. \ A practical use for these is the (de-)activation of an extension.

For more information about feature flags in TYPO3, please refer to the official TYPO3 Documentation on Feature Flags.

Feature Flag Configuration

Feature and Optional flags are configured in the .env or the local-dev/.ddev/docker-compose.environment.yaml file on ddev machine. To add a feature flag, use the following syntax:

# FEATURE FLAG
- TYPO3__SYS__features__GSB11_FEATURE_123_NEW_FEATURE=%const(bool:true)%
# OPTIONAL FLAG
- TYPO3__SYS__features__GSB11_OPTION_123_ENABLE_EXTENSION=%const(bool:true)%

In this example, both feature flags, GSB11_FEATURE_123_NEW_FEATURE and GSB11_OPTION_123_ENABLE_EXTENSION, are set to true. To disable the feature, change the value to false or delete the setting.

Feature Flag Truth Table

This table illustrates the behavior of feature flags in various states.

Usage in PHP Code

To use a feature flag in your PHP code, you can check the flag's value with the isFeatureEnabled() method of the Features class:

if (GeneralUtility::makeInstance(Features::class)->isFeatureEnabled('GSB11_FEATURE_123_NEW_FEATURE')) {
    echo 'Feature is enabled';

    // Feature-specific code
    ...
}

Usage in Fluid Templates

Feature flags can also be checked in your Fluid templates with TYPO3's Feature ViewHelper.

Basic usage

<f:feature name="GSB11_FEATURE_123_NEW_FEATURE">
   This is being shown if the flag is enabled
</f:feature>

Feature > then > else

<f:feature name="GSB11_OPTION_123_ENABLE_EXTENSION">
    <f:then>
        Flag is enabled
    </f:then>
    <f:else>
        Flag is undefined or not enabled
    </f:else>
</f:feature>

Current feature flags of gsb_solr

Usage

Nothing to do.

Contribute

As with TYPO3, we encourage you to join the project by submitting changes. Development of the GSB 11 happens mainly in the GSB 11 TYPO3 extension repositories.

To get started, have a look at our detailed contribution walkthrough.