---
title: "Company form in the Management plugin"
manual: "Yellowpages2"
version: "10.0"
permalink: "https://docs.typo3.org/permalink/jweiland/yellowpages2:company-form@10.0"
source: "AdministratorManual/CompanyForm/Index.rst"
rendered: "2026-11-20T15:36:35+00:00"
---

[https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt)

# Company form in the Management plugin {#company-form}

<!-- TODO: no Markdown rendering for "versionadded" -->

Companies are created and edited in the frontend with a form based on
EXT:form. The form has two steps: the company data and the position of
the company on the map.

The `Management` plugin renders the form definition
`EXT:yellowpages2/Configuration/Form/Company.form.yaml` in its action
`perform`. Logged-in frontend users of the user group of the site setting
`yellowpages2.userGroup` create new companies with it. The owner of a
company and moderators (see [Moderation of companies of the company form](https://docs.typo3.org/permalink/jweiland/yellowpages2:company-form-moderation@10.0)) edit existing
companies with the same form.

**Table of contents**

-   [Requirements of the company form](https://docs.typo3.org/permalink/jweiland/yellowpages2:requirements-of-the-company-form@10.0)
-   [Steps of the company form](https://docs.typo3.org/permalink/jweiland/yellowpages2:steps-of-the-company-form@10.0)
-   [Saving the company](https://docs.typo3.org/permalink/jweiland/yellowpages2:saving-the-company@10.0)
-   [Moderation of companies of the company form](https://docs.typo3.org/permalink/jweiland/yellowpages2:moderation-of-companies-of-the-company-form@10.0)
-   [Access rules of the company form](https://docs.typo3.org/permalink/jweiland/yellowpages2:access-rules-of-the-company-form@10.0)
-   [Configuration of the company form](https://docs.typo3.org/permalink/jweiland/yellowpages2:configuration-of-the-company-form@10.0)

## Requirements of the company form {#company-form-requirements}

-   The system extension EXT:form ([`typo3/cms-form`](https://packagist.org/packages/typo3/cms-form)). The site
    set `jweiland/yellowpages2` depends on the site set `typo3/form`, which
    provides the frontend configuration of EXT:form
    (`plugin.tx_form`). Without it, the form can not be
    rendered.
-   EXT:maps2 12.3.0 or higher ([`jweiland/maps2`](https://packagist.org/packages/jweiland/maps2)) with its form
    element `Maps2PoiPosition`. The site set `jweiland/yellowpages2`
    depends on the site set `jweiland/maps2-default`, which provides the
    form element.
-   Optional: EXT:rte_ckeditor ([`typo3/cms-rte-ckeditor`](https://packagist.org/packages/typo3/cms-rte-ckeditor)) for the
    rich text editor of the description, see
    [Rich text editor in the frontend form](https://docs.typo3.org/permalink/jweiland/yellowpages2:frontend-rich-text-editor@10.0).

## Steps of the company form {#company-form-steps}

1.  **Company data** (page `company-data`): name, address, district,
    contact data, opening times, description, trades, social media links,
    logo and images.
1.  **Position on the map** (page `map`): the form element
    `Maps2PoiPosition` of EXT:maps2 shows a marker at the position of the
    address. The user can move the marker, if the position is not correct.

When the first step is submitted, the address (street, house number, zip
and city) is geocoded by the `GeocodeAddressHook` with the
`GeoCodeService` of EXT:maps2. The marker of the second step is placed
at the found position. If the address can not be found, the user stays on
the first step and gets an error at the field "Street".

The address is only geocoded again, if it was changed. So a corrected
position is kept, if the user goes back to the first step. When an
existing company is edited, the second step shows the stored position of
its POI collection, as long as the address is not changed.

The identifiers of the address fields are configured in the property
`addressElements` of the element `position`:

**EXT:yellowpages2/Configuration/Form/Company.form.yaml (excerpt)**

```yaml
- type: Maps2PoiPosition
  identifier: position
  properties:
    dbMapping:
      column: tx_maps2_uid
      dataType: poiPosition
    addressElements:
      - street
      - house-number
      - zip
      - city
```

## Saving the company {#company-form-saving}

The company is saved by the finishers of the form, after the second step
was submitted:

1.  `SaveCompanyFinisher`: stores the company, its trades (categories),
    its logo and images and the corrected position. A company without POI
    collection gets a new POI collection of type `Point`, which is stored
    in the folder of the extension setting
    [poiCollectionPid](https://docs.typo3.org/permalink/jweiland/yellowpages2:confval-confval-poicollectionpid@10.0) or else next to
    the company. The POI collection of an edited company is updated.
1.  `EmailToReceiver`: informs the moderator, see
    [Moderation of companies of the company form](https://docs.typo3.org/permalink/jweiland/yellowpages2:company-form-moderation@10.0).
1.  `FlashMessage`: tells the user, that the company will be visible after
    it was activated.
1.  `Redirect`: redirects to the page of the site setting
    `yellowpages2.pidOfManagementPage` (the list of the own companies) or
    else to the current page.

New companies are stored in the page of the site setting
`yellowpages2.form.storagePid`. If it is empty, the first storage page of
the plugin (`yellowpages2.storagePid`) or else the current page is used.
They get the current frontend user as owner and a path segment. An edited
company keeps its page, owner and path segment.

The values of selects and checkboxes are restricted to their options. So a
manipulated request can not relate other categories or districts.

## Moderation of companies of the company form {#company-form-moderation}

Each company created or edited with the form is hidden, until a moderator
activates it. The `EmailToReceiver` finisher sends a mail to the recipient
of the extension settings ([emailToAddress](https://docs.typo3.org/permalink/jweiland/yellowpages2:confval-confval-emailtoaddress@10.0)) with all values of the form and two signed
links:

-   **Edit record**: opens the company form with this company. The link
    contains a `moderationToken`, so no frontend login is needed.
-   **Activate record**: opens a confirmation page with a summary of the
    company (action `confirmActivation` of the `ManagementController`). Its
    button activates the company via POST (action `activate`). Mail
    security scanners and link previews open the links of a mail
    automatically, so the link itself never activates the company.

After the activation, the moderator is redirected to the list of the
`Directory` plugin (site setting `yellowpages2.pidOfListPage`), which shows
a success message. Without a valid `moderationToken`, e.g. for owners of
the company, the company is not activated and an error message is shown.
If the company is activated already, an information is shown. A request of
the action `activate` via GET is redirected to the confirmation page.

The mail is rendered with the templates
`EXT:yellowpages2/Resources/Private/FormFramework/Templates/Finishers/Email/CompanyModeration.html`
and `CompanyModeration.txt`. The template name and its root path are
options of the finisher in `Company.form.yaml`, so they apply to the
company form only and not to other forms of the installation. The finisher
`SaveCompanyFinisher` provides the UID of the company and the token of the
links as finisher variables `SaveCompany.companyUid` and
`SaveCompany.moderationToken`. Rich text elements like the description are
rendered with the `FormatRichTextViewHelper`, see
[Rich text elements in the mail of the company form](https://docs.typo3.org/permalink/jweiland/yellowpages2:frontend-rich-text-editor-mail@10.0).

## Access rules of the company form {#company-form-access}

| Action | Allowed for |
| --- | --- |
| Create a company | Logged-in frontend users of the user group of `yellowpages2.userGroup` |
| Edit a company | The owner (frontend user of the company), a backend administrator or everyone with a valid `moderationToken` of the mail |

The company to edit is taken from the query parameter
`tx_yellowpages2_management[company]` of the form URI. The rules are
checked by the `perform` action, while prefilling the form and again by the
`SaveCompanyFinisher`.

## Configuration of the company form {#company-form-configuration}

The site set `jweiland/yellowpages2` registers the form setup
`EXT:yellowpages2/Configuration/Form/OverrideFormSettings.yaml` and
overrides some values of the form definition with TypoScript
`plugin.tx_yellowpages2.settings.overrideForm`:

**EXT:yellowpages2/Configuration/Sets/Yellowpages2/setup.typoscript (excerpt)**

```typoscript
plugin.tx_yellowpages2.settings.overrideForm {
  # Upload folder of logo and images ("settings.new.uploadFolder")
  renderables.0.renderables.19.properties.saveToFileMount < plugin.tx_yellowpages2.settings.new.uploadFolder
  # Storage page of new companies
  finishers.1.options.databaseColumnMappings.pid.value = {$yellowpages2.form.storagePid}
  # Page of the links in the mail of the moderator
  finishers.2.options.variables.pidOfManagementPage = {$yellowpages2.pidOfManagementPage}
  # Page of the redirect after saving
  finishers.4.options.pageUid = {$yellowpages2.pidOfManagementPage}
}
```

Labels and descriptions of the form elements are translated with
`EXT:yellowpages2/Resources/Private/Language/locallang_form.xlf`.

### Markup of the company form {#company-form-markup}

The company form renders the markup of Bootstrap 5. It uses the template
variant `version2` of EXT:form, which sets classes like `form-control`,
`form-select`, `form-label`, `form-check-input` and `mb-3`. Fields with
validation errors get the class `is-invalid`, the error messages are
rendered with `invalid-feedback`. The navigation buttons of the two steps
are rendered by the partial of EXT:form.

`Company.form.yaml` activates the template variant and adds the
partial root path of yellowpages2 to this form only, so the partial does
not change other forms of the installation:

**EXT:yellowpages2/Configuration/Form/Company.form.yaml (excerpt)**

```yaml
renderingOptions:
  templateVariant: version2
  partialRootPaths:
    1763380800: 'EXT:yellowpages2/Resources/Private/FormFramework/Partials/'
```

Keep both options in an own copy of the form definition. To override the
partial, add your own path with a higher key. The partial
`EXT:yellowpages2/Resources/Private/FormFramework/Partials/Field/Field.html`
is based on the partial of the template variant `version2` and renders the
element description (`properties.elementDescription`) as small text
below the field:

```html
<small id="yellowpages2Company-trades-desc" class="form-text text-muted">Choose up to two further trades</small>
```

### Hooks of EXT:form and other forms {#company-form-hooks}

The hooks of EXT:form are called for all forms of the installation.
yellowpages2 registers the hooks `beforeRendering` (rich text editor, see
[Rich text editor in the frontend form](https://docs.typo3.org/permalink/jweiland/yellowpages2:frontend-rich-text-editor@10.0)) and `afterSubmit` (geocoding of the
address). They only act on forms, which are built by the
`JWeilandYellowpages2DomainFactoryArrayFormFactory` of
yellowpages2. The factory sets the rendering option `formOwner` to
`yellowpages2` (see `JWeilandYellowpages2FormFormOwner`).
Other forms, e.g. contact forms or the forms of other extensions, are not
changed, even if they contain elements with `dataType: richText` or
an element `Maps2PoiPosition`.

If you render your own copy of `Company.form.yaml`, use the factory
of yellowpages2, as the `Management` plugin does:

```html
<formvh:render persistenceIdentifier="EXT:my_sitepackage/Configuration/Form/Company.form.yaml"
               factoryClass="JWeiland\\Yellowpages2\\Domain\\Factory\\ArrayFormFactory"/>
```

The form options, the prefill of an edited company and the configuration
of the rich text elements are part of this factory, too.

### Rights checkbox of EXT:checkfaluploads {#company-form-checkfaluploads}

The uploads of logo and images are plain EXT:form elements of type
`ImageUpload`. To add the rights checkbox of EXT:checkfaluploads (6.0.0 or
higher), add a checkbox with `checkboxType: uploadRights` and
`referenceUploadIdentifier` to your copy of the form definition, as
described in the documentation of EXT:checkfaluploads.
