Table of Contents

  1. Ext: sg_forms

Ext: sg_forms

License: GNU GPL, Version 2

Repository: https://gitlab.sgalinski.de/typo3/sg_forms

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_forms

About

This extension provides additional functionality for the forms extension

The backend Form Submissions module provides:

  • a form overview with submission counts
  • a root selection view listing pages that contain form submissions
  • an explicit empty state when no form submissions exist on any accessible page
  • grouped submission list view per form (paginated)
  • single submission detail view
  • in-context actions (back, export CSV, delete)
  • filter-aware empty states
  • CSV exports with contextual filenames (sgforms-*.csv)
  • per-form configurable visible columns in submission list
  • "new since last visit" indicators in form overview
  • language-aware frontend page links in submission detail views
  • translation-aware submission grouping by main form identifier
  • restoring a deleted main form definition also restores related deleted translation files

Legacy submissions without a stored language context continue to link to the default language version of the frontend page in the submission detail view.

Database Schema

The internal submission table is declared in TCA. ext_tables.sql remains the authoritative source for its existing primary key, parent index, and legacy signed integer columns until the project-wide schema migration is verified.

Setup

Setup custom forms storage

All you need to be able to store the form yaml files in our project theme is to create the following folder: * web/typo3conf/ext/project_theme/Resources/Private/Forms*

Don't forget to include the Typoscript in your template!

CAPTCHA protection

Enable CAPTCHA for an individual form with the Enable CAPTCHA checkbox in the form editor. The globally enabled provider, its credentials, rendering and server-side validation are configured exclusively by sg_captcha. Failed requests are redisplayed with the shared CAPTCHA validation message, including programmatic submissions without browser constraint validation.

PDF Finisher

The PdfFinisher can fill an existing PDF form with submitted form values and optionally attach it to admin/user mails. Filling PDF forms requires mikehaertl/php-pdftk and a working pdftk binary on the server.

For local DDEV environments, make sure pdftk is installed in the web container via .ddev/config.yaml:

webimage_extra_packages: [ build-essential, python3, pdftk]

In the form editor:

  1. Add the Fill PDF with form values finisher.
  2. Select a PDF template file (sys_file with AcroForm fields).
  3. Click Load PDF fields to import all PDF field names into the mapping table.
  4. Map each imported PDF field to a TYPO3 form field identifier (Text, Textarea, Email, Checkbox, LinkedCheckbox, RadioButton, SingleSelect, MultiSelect, CountrySelect) or to a virtual value (CURRENT_DATE, CURRENT_TIME, CURRENT_DATETIME, CURRENT_TIMESTAMP).
  5. Optionally enable Start generated PDF download on confirmation page (one-time, deletes file after first access) to automatically trigger the PDF download after submit.
  6. Flatten generated PDF (make it non-editable) is enabled by default. Disable it if you want to keep output fields editable/highlighted.

For checkbox/radio/select mappings, the PDF field name and PDF export value definitions must match the TYPO3 values you submit (for example the selected radio option value). The editor currently does not enforce type compatibility, so integrators/editors need to ensure the mapping is semantically correct.

Generated PDFs are stored in fileadmin/sg_forms/Temp/PdfAttachments. The frontend download link uses a temporary token (default TTL: 1 hour) and is consumed on first valid access. On this first access, the generated PDF is streamed and then deleted. Integrators should still schedule cleanup for this directory, because generated PDFs can remain there when no frontend download is rendered/clicked, for example when PDFs are only attached to emails. Schedule the dedicated form submission PDF cleanup command for this:

vendor/bin/typo3 sgforms:cleanup:form-submission-pdfs --retention-period=24

The retention period is specified in hours. Adjust it to the project's retention requirements. Form Framework upload folders in 1:/form_uploads/ are cleaned up by TYPO3 core's form:cleanup:uploads command.

The one-time download URL is GET /api/public/v1/forms/pdf-download?token={token}. Invalid or expired tokens return a 404 RFC 7807 Problem JSON response; valid downloads are streamed with no-store cache headers.

Extension Configuration

Toggle Translation Grouping

By default, the backend module groups translated form definitions under their parent form. If you want to disable this behavior and see all form definitions as separate entries (e.g., in multi-site setups with separate language handling), you can toggle this behavior in the extension configuration of sg_forms in the TYPO3 Backend.

The setting groupTranslations can be found in the extension configuration under the "general" category.

Search in Form Manager

The overridden Form Manager view includes a search field above the form list. It filters forms by:

  • form name (label)
  • form persistenceIdentifier