Typo3 Powermail Conditions

Powermail Conditions (powermail_cond)

Compatibility: TYPO3 v13.x with Powermail 13.x and powermail_cond 13.x Requires: in2code/powermail: ^13.0

1. Overview

powermail_cond adds dynamic conditional visibility to powermail forms. Fields or entire pages (fieldsets) can be shown/hidden based on user input, evaluated via AJAX in real-time.

Installation

composer require in2code/powermail_cond

Include the static TypoScript template from powermail_cond.

Architecture

ConditionContainer (tx_powermailcond_domain_model_conditioncontainer)
 └── Condition (tx_powermailcond_domain_model_condition)
      └── Rule (tx_powermailcond_domain_model_rule)

• ConditionContainer: Links to one powermail Form (1:1)
• Condition: Defines a target (field or page) and action (hide/unhide), contains rules with AND/OR conjunction
• Rule: Single comparison against a field value

2. Operators

Operators 0-7 compare against a static string (cond_string). Operators 8-9 compare against another form field (equal_field).

3. Backend Configuration

Step 1: Create Condition Container

1. Go to a sysfolder (or the page with the form)
2. Create new record: Condition Container
3. Set Title and select the Form
4. Add Conditions

Step 2: Configure Conditions

Each condition defines:

Step 3: Configure Rules

Each rule defines:

Targeting Pages (Fieldsets)

To show/hide an entire page (fieldset), set the target field to the page. Pages appear in the target dropdown with a fieldset: prefix. When a page is hidden, all its fields are excluded from validation.

4. AJAX Endpoint

Conditions are evaluated server-side via TypeNum 3132.

TypoScript Setup (auto-included)

# TypeNum for AJAX condition evaluation
powermailCondition = PAGE
powermailCondition {
    typeNum = 3132
    config {
        disableAllHeaderCode = 1
        no_cache = 1
        additionalHeaders.10.header = Content-type: application/json
    }
    10 = USER
    10 {
        userFunc = TYPO3\CMS\Extbase\Core\Bootstrap->run
        extensionName = PowermailCond
        vendorName = In2code
        controller = Condition
        pluginName = Pi1
    }
}

Route Enhancer for Clean URLs

routeEnhancers:
  PageTypeSuffix:
    type: PageType
    default: /
    index: ''
    suffix: /
    map:
      condition.json: 3132

JSON Response Format

{
    "todo": {
        "42": {
            "1": {
                "email": {
                    "#action": "hide",
                    "matching_condition": { "5": "5" }
                },
                "#action": "un_hide"
            }
        }
    },
    "loops": 3,
    "loopLimit": 100
}

Structure: todo[formUid][pageUid][fieldMarker] or todo[formUid][pageUid] for page-level actions.

5. Reducing Flickering (Server-Side Prerendering)

By default, conditions are loaded via AJAX after page load, causing visible flickering. Prerender conditions server-side to avoid this.

ViewHelper for Prerendering

Add to your copy of EXT:powermail/Resources/Private/Templates/Form/Form.html:

{namespace pc=In2code\PowermailCond\ViewHelpers}

<!-- Prerender conditions as inline JSON -->
<script type="application/json" id="form-{form.uid}-actions">
    {pc:conditions(form:form) -> f:format.raw()}
</script>

<!-- Hide fieldsets until conditions are applied -->
<style type="text/css">
    .powermail_fieldset {
        opacity: 0;
        visibility: hidden;
        transition: opacity 0.5s, visibility 0.5s;
    }
</style>

The JavaScript detects the prerendered JSON and skips the initial AJAX call.

6. File Upload Optimization

File upload fields send all selected files with every AJAX condition request. If you don't need conditions based on file uploads, exclude them:

<f:form
    action="{action}"
    name="field"
    enctype="multipart/form-data"
    additionalAttributes="{vh:validation.enableJavascriptValidationAndAjax(
        form:form,
        additionalAttributes:{
            data-powermail-cond-excluded-fields: '.powermail_file'
        }
    )}"
>

7. Validator Integration (XCLASS)

powermail_cond XCLASSes powermail's InputValidator with ConditionAwareValidator to skip validation on hidden fields.

// Registered in ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['Objects'][
    \In2code\Powermail\Domain\Validator\InputValidator::class
] = [
    'className' => \In2code\PowermailCond\Domain\Validator\ConditionAwareValidator::class,
];

Hidden field state is stored in the frontend user session under key tx_powermail_cond. The validator checks this session data before validating each field.

8. Extension Configuration

Loop Count Safety

The condition container iterates until no changes occur. A safety limit prevents infinite loops.

Configure via Extension Manager or ext_conf_template.txt.

9. JavaScript Behavior

The frontend JavaScript (PowermailCondition.min.js) is auto-included via TypoScript:

page.includeJSFooter.powermailCond = EXT:powermail_cond/Resources/Public/JavaScript/PowermailCondition.min.js
page.includeJSFooter.powermailCond.defer = 1

Behavior

• Listens to change events on all form fields (input, textarea, select)
• Sends form data to the condition endpoint via fetch()
• Applies hide/show actions via CSS classes (powermail-cond-hidden)
• Manages required attribute (removes on hidden fields, restores on show)
• Handles multi-step forms (powermail_morestep)
• Supports pageshow event (back/forward cache)

CSS for Hidden Fields

/* Applied by JavaScript */
.powermail-cond-hidden {
    display: none !important;
}

10. Known Limitations

• Multi-step forms: Cannot use powermail multi-step forms with powermail_cond
• One container per form: Each form can have exactly one condition container
• XCLASS approach: Only one extension can XCLASS InputValidator -- conflicts possible with other extensions modifying the same class
• jQuery not required: Since powermail_cond 10.0.0, vanilla JS is used (no jQuery dependency)

11. Common Patterns

Show Field Based on Select Value

Scenario: Show "Other" text input when user selects "Other" in a dropdown.

1. Create Condition Container for the form
2. Add Condition:
   • Target: other_details field
   • Action: hide (hidden by default)
3. Add Rule:
   • Start field: category (the select field)
   • Operator: is (4)
   • Condition string: Other

The "other_details" field is hidden by default and only shown when "Other" is selected.

Hide Page Based on Checkbox

Scenario: Hide an entire page/fieldset unless a checkbox is checked.

1. Add Condition:
   • Target: Page (fieldset) containing the additional fields
   • Action: hide
2. Add Rule:
   • Start field: accept_terms (checkbox)
   • Operator: is not set (1)

Field-to-Field Comparison

Scenario: Show a warning field when two email fields don't match.

1. Add Condition:
   • Target: email_mismatch_warning field
   • Action: unhide (show when rule matches)
2. Add Rule:
   • Start field: email
   • Operator: contains not value from field (9)
   • Equal field: email_repeat

12. Database Structure

Note: powermail_cond uses l18n_parent (not l10n_parent) for its translation pointer. Powermail core uses l10n_parent. Be careful with the naming difference.

TYPO3 Standard Columns

All powermail_cond tables include these TYPO3-managed columns (not listed per table below):

tx_powermailcond_domain_model_conditioncontainer

Relations: form -> tx_powermail_domain_model_form.uid

tx_powermailcond_domain_model_condition

Indexes: conditioncontainer, target_field(20) Hidden table: Yes (hideTable => 1) -- only editable inline inside container

tx_powermailcond_domain_model_rule

Indexes: conditions, start_field, equal_field Hidden table: Yes (hideTable => 1) -- only editable inline inside condition

ER Diagram (Condition Relations)

tx_powermail_domain_model_form
  │ 1
  └──── 1 tx_powermailcond_domain_model_conditioncontainer (via form)
           │ 1
           └──── * tx_powermailcond_domain_model_condition (IRRE via conditioncontainer)
                    │ 1
                    └──── * tx_powermailcond_domain_model_rule (IRRE via conditions)
                              │
                              ├── start_field -> tx_powermail_domain_model_field.uid
                              └── equal_field -> tx_powermail_domain_model_field.uid (ops 8-9)

target_field Format

The target_field column uses two formats:

13. Full Example: Multi-Step Shop with Conditions

For a comprehensive example with Austrian legal types (Gesellschaftsformen), conditional fields per legal type, and two implementation approaches (DDEV SQL + DataHandler CLI command), see SKILL-EXAMPLES.md.