..  _configuration:

=============
Configuration
=============

Extension configuration
=======================

..  list-table::
    :header-rows: 1

    *   -   Setting
        -   Meaning
    *   -   :code:`apiId`, :code:`apiKey`
        -   ProvenExpert API credentials
    *   -   :code:`cacheLifetime`
        -   how long a response is reused, default 3600 seconds
    *   -   :code:`timeout`
        -   how long to wait for the API, default 5 seconds
    *   -   :code:`autoInsert`
        -   place the rating before :code:`</body>` on every page, default on
    *   -   :code:`ratingStyle`
        -   layout of the visible rating, see below
    *   -   :code:`strokeColor`, :code:`fillColor`, :code:`fontColor`
        -   colour overrides for the stars, exactly like the official PHP script

..  _configuration-layout:

Layout
======

ProvenExpert always returns the layout selected in the account under
:guilabel:`Google stars > Display of the rich snippet`; its API offers no
parameter for it. The extension therefore builds the visible output itself,
from the :code:`ratingValue` and :code:`reviewCount` fields of the same API
response – a route ProvenExpert explicitly allows. The JSON-LD block is always
taken over from ProvenExpert **unchanged**, so the structured data stays
exactly as intended.

..  list-table::
    :header-rows: 1

    *   -   :code:`ratingStyle`
        -   Output
    *   -   :code:`starsInline` (default)
        -   stars next to "N reviews on ProvenExpert.com"
    *   -   :code:`stars`
        -   stars above the review count
    *   -   :code:`text`
        -   "Company has 4.67 out of 5 stars" above the review count
    *   -   :code:`textInline`
        -   both in one line, separated by a pipe
    *   -   :code:`account`
        -   untouched markup from ProvenExpert, i.e. whatever the account is set to

Per site
========

The same keys can be set per site below :code:`settings.bm1_provenexpert`,
which takes precedence over the extension configuration:

..  code-block:: yaml
    :caption: config/sites/<identifier>/config.yaml (v10-v12), settings.yaml (v13+)

    settings:
      bm1_provenexpert:
        apiId: '...'
        apiKey: '...'
        ratingStyle: 'starsInline'

On TYPO3 v13 and above you can add the shipped site set
:code:`bm1/provenexpert`, which makes the settings editable in the backend.

Keeping credentials out of the repository
=========================================

Any string setting may hold a placeholder such as
:code:`%env(PROVENEXPERT_API_KEY)%`, which is resolved from the server
environment. In site YAML files TYPO3 resolves such placeholders on its own.