Configuration

Chapters of this Documentation

Everything is configured per site, in config/sites/<identifier>/settings.yaml. There is no extension configuration and no global switch: two sites in one installation can use two VG Wort accounts, or one, or only one of them the API at all.

Settings

Setting	Default	What it does
`vgwort.api.enabled`	`false`	Turns on everything that talks to VG Wort: ordering pixels, verifying authors, reporting, syncing. Off, the module still manages pools, texts and authors locally.
`vgwort.api.username`	`''`	T.O.M. portal login.
`vgwort.api.password`	`''`	T.O.M. portal password.
`vgwort.api.testMode`	`false`	Sends to `tom-test.vgwort.de` instead of `tom.vgwort.de`.
`vgwort.publisher`	`false`	Declares this site’s account a publisher account (Verlagskonto). Shows the Publisher not involved checkbox in page properties.

What comes from the free extension

b13/vgwort is always installed alongside this one, and four of its settings decide how this extension behaves. They are listed here because nobody looking for "why is nothing counted" thinks to read a second README.

vgwort.domain

Default	`vg08`

The counting server, vg01 to vg09. The correct value is on your VG Wort pixel order, and it is not the same for every account. Pointing at the wrong server means the pixel resolves to a host that does not know it: the page delivers a pixel, the module shows a green check, and nothing is ever counted.

Set it next to the API settings:

settings:
  vgwort:
    domain: 'vg05'

Nothing in TYPO3 can verify this for you—check it against the order confirmation once, per account.

contentDoktypes

Which page types get the VG Wort fields, and therefore which pages can carry a pixel at all. See below.

The tx_vgwort_ignore field

A checkbox on every page, from the free extension: exclude this page from VG Wort. This extension reads it in two places—an ignored page is not offered for registration, and it cannot become part of a bundled text, because a page that shows no pixel must not appear in a report’s URL list.

How the pixel reaches the page

Through the site set, and with this extension installed, only through the site set.

The free extension renders the pixel by reading tx_vgwort_pixel off the page. That is right for a text on one page and wrong for a text on several: the member pages of a bundle store no pixel of their own, they have to deliver the entry page’s. So the Pro set replaces that output (page.1 >, then its own renderer), which is also what makes tx_vgwort_ignore take effect.

The VgwortTracking partial from the free extension is therefore not an alternative here. Placing the pixel yourself with it brings back exactly the behaviour the Pro set replaced: every member page of a bundled text delivers nothing, and every text spread over several pages counts only its first one.

What matters either way is that the pixel arrives, and that is the single most common thing to get wrong. See How It Works.

The two that cost you

testMode. A report sent in test mode is accepted, looks exactly like a real one in the backend, and reaches nothing. Nothing distinguishes it afterwards. This is the single most expensive setting in the list, because the mistake is silent and the deadline passes anyway.

publisher. It decides whether a share of the royalty goes to the publisher. Set it true on a personal account and every report claims a participation that does not exist; set it false on a publisher account and the publisher’s share is gone. It is not a display option.

Credentials

Keep them out of version control:

settings:
  vgwort:
    api:
      enabled: true
      username: '%env(VGWORT_USERNAME)%'
      password: '%env(VGWORT_PASSWORD)%'

Several sites, several accounts. Use distinct environment variable names per site and reference them in each site’s settings.yaml:

# config/sites/site-a/settings.yaml
settings:
  vgwort:
    api:
      enabled: true
      username: '%env(VGWORT_SITE_A_USERNAME)%'
      password: '%env(VGWORT_SITE_A_PASSWORD)%'

Credentials are resolved through the root page of the site a page belongs to, so each site’s pool, texts and API calls always use its own account. Sites that share one VG Wort account can reference the same variables.

Publisher or personal account

Account	`vgwort.publisher`	Behaviour
Personal (Urheber)	`false`	The publisher never participates. The checkbox is hidden.
Publisher (Verlag)	`true`	The publisher participates by default; opt out per page with Publisher not involved.

API access differs too: a publisher account has webservice access by default, a personal account has to request Optionale Zusatzfunktionen in the T.O.M. portal before any call works.

Permissions

Six actions are gated by Page TSconfig. See Backend Module for what each one lets an editor do and what stays possible without any of them.

Which page types get the fields

By default the VG Wort fields appear on standard pages (doktype 1). Custom page types that carry reportable text are added in your site package’s ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vgwort']['contentDoktypes'][] = 116;

The array lives in the free extension, so your site package must declare b13/vgwort as a Composer dependency for it to exist when your line runs.

This list is also what the bundle rules check. A page whose type is not in it cannot become part of a bundled text—see Bundled Texts.