Company form in the Management plugin
New in version 10.0.0
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: in its action
perform. Logged-in frontend users of the user group of the site setting
yellowpages2. create new companies with it. The owner of a
company and moderators (see Moderation of companies of the company form) edit existing
companies with the same form.
Table of contents
Requirements of the company form
- The system extension EXT:form (
typo3/cms-form
). The site
set
jweiland/depends on the site setyellowpages2 typo3/, which provides the frontend configuration of EXT:form (form plugin.). Without it, the form can not be rendered.tx_ form - EXT:maps2 12.3.0 or higher (
jweiland/maps2
) with its form
element
Maps2Poi. The site setPosition jweiland/depends on the site setyellowpages2 jweiland/, which provides the form element.maps2- default - Optional: EXT:rte_ckeditor ( typo3/cms-rte-ckeditor ) for the rich text editor of the description, see Rich text editor in the frontend form.
Steps of the company form
- Company data (page
company-): name, address, district, contact data, opening times, description, trades, social media links, logo and images.data - Position on the map (page
map): the form elementMaps2Poiof EXT:maps2 shows a marker at the position of the address. The user can move the marker, if the position is not correct.Position
When the first step is submitted, the address (street, house number, zip
and city) is geocoded by the Geocode with the
Geo 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
address of the element position:
- type: Maps2PoiPosition
identifier: position
properties:
dbMapping:
column: tx_maps2_uid
dataType: poiPosition
addressElements:
- street
- house-number
- zip
- city
Saving the company
The company is saved by the finishers of the form, after the second step was submitted:
Save: 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 typeCompany Finisher Point, which is stored in the folder of the extension setting poiCollectionPid or else next to the company. The POI collection of an edited company is updated.Email: informs the moderator, see Moderation of companies of the company form.To Receiver Flash: tells the user, that the company will be visible after it was activated.Message Redirect: redirects to the page of the site settingyellowpages2.(the list of the own companies) or else to the current page.pid Of Management Page
New companies are stored in the page of the site setting
yellowpages2.. If it is empty, the first storage page of
the plugin (yellowpages2.) 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
Each company created or edited with the form is hidden, until a moderator
activates it. The Email finisher sends a mail to the recipient
of the extension settings (emailToAddress) with all values of the form and two signed
links:
- Edit record: opens the company form with this company. The link
contains a
moderation, so no frontend login is needed.Token - Activate record: opens a confirmation page with a summary of the
company (action
confirmof theActivation Management). Its button activates the company via POST (actionController 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.), which shows
a success message. Without a valid moderation, 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:
and Company. The template name and its root path are
options of the finisher in Company., so they apply to the
company form only and not to other forms of the installation. The finisher
Save provides the UID of the company and the token of the
links as finisher variables Save and
Save. Rich text elements like the description are
rendered with the Format, see
Rich text elements in the mail of the company form.
Access rules of the company form
| Action | Allowed for |
|---|---|
| Create a company | Logged-in frontend users of the user group of
yellowpages2. |
| Edit a company | The owner (frontend user of the company), a
backend administrator or everyone with a valid
moderation of the mail |
The company to edit is taken from the query parameter
tx_ of the form URI. The rules are
checked by the perform action, while prefilling the form and again by the
Save.
Configuration of the company form
The site set jweiland/ registers the form setup
EXT: and
overrides some values of the form definition with TypoScript
plugin.:
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:.
Markup of the company form
The company form renders the markup of Bootstrap 5. It uses the template
variant version2 of EXT:form, which sets classes like form-,
form-, form-, form- and mb-. Fields with
validation errors get the class is-, the error messages are
rendered with invalid-. The navigation buttons of the two steps
are rendered by the partial of EXT:form.
Company. 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:
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:
is based on the partial of the template variant version2 and renders the
element description (properties.) as small text
below the field:
<small id="yellowpages2Company-trades-desc" class="form-text text-muted">Choose up to two further trades</small>
Hooks of EXT:form and other forms
The hooks of EXT:form are called for all forms of the installation.
yellowpages2 registers the hooks before (rich text editor, see
Rich text editor in the frontend form) and after (geocoding of the
address). They only act on forms, which are built by the
JWeiland of
yellowpages2. The factory sets the rendering option form to
yellowpages2 (see JWeiland).
Other forms, e.g. contact forms or the forms of other extensions, are not
changed, even if they contain elements with data or
an element Maps2Poi.
If you render your own copy of Company., use the factory
of yellowpages2, as the Management plugin does:
<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
The uploads of logo and images are plain EXT:form elements of type
Image. To add the rights checkbox of EXT:checkfaluploads (6.0.0 or
higher), add a checkbox with checkbox and
reference to your copy of the form definition, as
described in the documentation of EXT:checkfaluploads.