---
title: "Developer Guide"
manual: "Connetation Elements"
version: "3.1"
permalink: "https://docs.typo3.org/permalink/connetation/t3wtk-elements:developer-guide@3.1"
source: "DeveloperGuide/Index.rst"
rendered: "2026-10-16T12:46:53+00:00"
---

# Developer Guide {#developer-guide}

## Adding a new content element {#adding-content-element}

Use the scaffold CLI — it generates every required file and patches all
registration files automatically.

Local (Node.js installed on host), from `vendor/connetation/t3wtk-elements`:

```
npm run make-element

```

This works out of the box wherever the package is installed, since the
script (`bin/make-element.mjs`) ships inside `connetation/t3wtk-elements`
itself.

### Optional: a DDEV host command {#optional-a-ddev-host-command}

> [!IMPORTANT]
> Unlike `npm run make-element`, the `ddev make-element` shortcut is
> **not** part of the `connetation/t3wtk-elements` package — it is a project-level
> DDEV host command that must exist in *your own* project's
> `.ddev/commands/host/make-element`. Installing `connetation/t3wtk-elements`
> via Composer into a fresh project does not give you this command; you
> need to add the script yourself before `ddev make-element` will
> work.

To add it:

1.  Create the file `.ddev/commands/host/make-element` at the root
    of your TYPO3 project (create the `host` directory too if it
    doesn't exist yet — note this is a project-level DDEV directory, not
    part of `connetation/t3wtk-elements`).
1.  Paste in the following script:

    ```bash
    #!/usr/bin/env bash
    ## Description: Scaffold a new content element in connetation/t3wtk-elements
    ## Usage: make-element ["Element Name"]
    ## Example: ddev make-element
    ## Example: ddev make-element "Hero Banner"

    set -euo pipefail

    ARGS="$*"
    if [ -n "$ARGS" ]; then
        ddev exec bash -c "cd /var/www/html/vendor/connetation/t3wtk-elements && node bin/make-element.mjs '$ARGS'"
    else
        ddev exec bash -c "cd /var/www/html/vendor/connetation/t3wtk-elements && node bin/make-element.mjs"
    fi
    ```
1.  Make it executable — DDEV silently ignores host commands that aren't:

    ```
    chmod +x .ddev/commands/host/make-element
    ```
1.  Restart DDEV so it picks up the new command:

    ```
    ddev restart

    ```

    (`ddev restart` is only needed the first time you add a new host
    command; editing an existing one afterwards does not require a
    restart.)

`/var/www/html` is DDEV's default in-container path for the project
root, so this script works unmodified on any standard DDEV setup. If your
project customises the web container's document/project root, adjust that
path accordingly.

Once that host command is in place, you can run:

```
ddev make-element

```

Or pass the element name directly to skip the first prompt:

```
ddev make-element "Hero Banner"

```

The host command itself is a thin wrapper that opens an interactive
terminal inside the web container (`ddev exec -it`) and runs
`node bin/make-element.mjs` from `vendor/connetation/t3wtk-elements`, so
readline prompts work correctly; running plain `ddev exec` without
`-it` would hang waiting for input.

Either way you invoke it, the scaffold CLI asks three questions:

1.  **Element name** — e.g. `Hero Banner`, `Testimonial`, `Pricing Table`
1.  **Type** — Simple (FlexForm settings only) or With inline child records
    (like Accordion / Cards)
1.  **CE group** — `conn_bootstrap`, `conn`, or `conn_swiper`

### What gets generated {#what-gets-generated}

| File | Purpose |
| --- | --- |
| `Configuration/FlexForms/<Name>.xml` | Display settings form |
| `Configuration/TypoScript/ContentElements/<Name>.typoscript` | Frontend rendering setup |
| `Configuration/TCA/tx_conn_t3wtk_elements_domain_model_<name>_item.php` | Child record TCA (with-items only) |
| `Classes/DataProcessing/<Name>ItemsProcessor.php` | DB query + FlexForm resolver (with-items only) |
| `Resources/Private/Templates/ContentElements/<Name>.html` | Main Fluid template |
| `Resources/Private/Partials/<Name>/Item.html` | Item partial (with-items only) |
| `Resources/Private/Components/<Name>/index.scss` | SCSS entry point |
| `Resources/Private/Components/<Name>/_<name>.scss` | SCSS component |
| `Resources/Private/Components/<Name>/<name>.ts` | TypeScript component |
| `Resources/Public/Icons/<name>-ce.svg` | Icon placeholder (replace with real SVG) |

### What gets patched automatically {#what-gets-patched-automatically}

[`Configuration/Icons.php`](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ExtensionArchitecture/FileStructure/Configuration/Icons.html#file-extension-configuration-icons-php), `build.mjs`, [`ext_tables.sql`](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ExtensionArchitecture/FileStructure/ExtTablesSql.html#file-extension-ext-tables-sql),
[`ext_localconf.php`](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ExtensionArchitecture/FileStructure/ExtLocalconf.html#file-extension-ext-localconf-php), [`Configuration/TCA/Overrides/tt_content.php`](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ExtensionArchitecture/FileStructure/Configuration/TCA/Index.html#file-extension-configuration-tca-overridessomefile-php),
`Resources/Private/Language/locallang_be.xlf`,
[`Configuration/TypoScript/setup.typoscript`](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ExtensionArchitecture/FileStructure/Configuration/TypoScript/Index.html#file-extension-configuration-typoscriptsetup-typoscript).

All patches are idempotent — re-running the script on an existing element
name is safe.

### After running the scaffold {#after-scaffold}

These steps must be done **in order** — skipping or reordering them
causes an "Unknown column" SQL error when saving the element in the
backend.

1.  **Build assets** — `npm run build` locally, or via DDEV as above.
1.  **Flush TYPO3 caches** — Admin Tools > Maintenance > Flush all caches,
    so TYPO3 picks up the new TCA and SQL definitions.
1.  **Apply database schema** *(with-items elements only)* — Admin Tools >
    Maintenance > Analyze Database Structure > apply changes. Skipping
    this step leaves the new column missing from the database, causing a
    `SQL error: Unknown column '...' in 'INSERT INTO'` when saving.
1.  **Verify** — the element should now appear in the "New Content
    Element" wizard under the chosen group.

### Customising the generated element {#customising-the-generated-element}

-   **FlexForm** — edit `Configuration/FlexForms/<Name>.xml` to add or
    change display settings.
-   **Child record fields** — extend
    `Configuration/TCA/tx_conn_t3wtk_elements_domain_model_<name>_item.php` and
    `ext_tables.sql`, then re-run database analysis.
-   **Data Processor** — extend `resolveSettings()` and the `$rows`
    enrichment in the generated processor.
-   **Template** — edit the Fluid template and partial freely.
-   **SCSS** — edit `_<name>.scss`; uses `var(--conn-*)` design tokens
    for consistent theming.
-   **TypeScript** — edit `<name>.ts`; the `registry.register()` call
    at the bottom wires it to the DOM.
-   **Icon** — replace `Resources/Public/Icons/<name>-ce.svg` with your
    SVG (16×16 viewBox recommended).