..  _usage:

=====
Usage
=====

Automatic placement
===================

After installing the extension and entering the credentials, the rating is
rendered before :code:`</body>` on every page, centred. Nothing else to do.

Switch it off with :code:`autoInsert` in the extension configuration if you
want to place the snippet yourself.

Content element
===============

Add the content element :guilabel:`ProvenExpert rating` where it should appear
and choose what it shows:

Rating
    Stars, link and rich snippet. The automatic placement then holds back, so
    there is never more than one review snippet on a page.

Seal
    The ProvenExpert seal as an image - portrait, landscape, square or circle,
    up to 250 pixels wide. The image is stored below
    :code:`typo3temp/assets/bm1_provenexpert/` and delivered from your own
    domain. It keeps its aspect ratio and shrinks to the available width on
    narrow screens. The seal carries no structured data, so it can sit on the same page
    as the rating.

The ProvenExpert widget type :code:`bar` is not offered on purpose: its API
response is a :code:`<script>` tag pointing at ProvenExpert, which would require
consent again.

Google grants stars only for a snippet that is fully visible, and expects
**one** review snippet per page.

TypoScript
==========

Add the static template :guilabel:`ProvenExpert (server-side)` to your root
template, then place the rating wherever you need it:

..  code-block:: typoscript

    # e.g. below the footer, on every page
    page.footerData.950 < lib.provenExpertRating

    # optional: override the configured layout
    page.footerData.950.style = stars

Fluid
=====

..  code-block:: html

    {namespace pe=Bm1\ProvenExpert\ViewHelpers}

    <pe:rating />
    <pe:rating style="textInline" />

Caching
=======

Rating data is cached for an hour by default. If the API is unreachable, the
last successful response keeps being served and the API is retried after a
minute, so the rating never disappears because of a network hiccup.

Changes made in the ProvenExpert account show up with a delay: this extension
caches, and ProvenExpert caches on its own servers as well.

What is sent where
==================

Only the web server talks to ProvenExpert. The visitor's browser loads nothing
from ProvenExpert: no script, no image, no font. No cookies and no
:code:`sessionStorage` entries are created, and no visitor data reaches
ProvenExpert.

This covers the display of the rating. Collecting reviews through ProvenExpert
is a separate processing activity.