picpins for TYPO3: Embed hotspots in the content element

In three steps to your embedded image

1

Build the picpins image

Upload a photo, place markers, fill tooltips. Auto-save active.

2

Get the embed code

Copy the two-line HTML from the picpins dashboard.

3

"Plain HTML" content element

In the Page module choose "New content element → Plain HTML", paste the code, save.

How to embed picpins

TYPO3 clearly separates RTE content (with HTML filter) from raw HTML elements. For embeds always pick "Plain HTML" — that bypasses the filter completely. Alternatively you can configure RTE profiles to let embed tags through.

1. Create a "Plain HTML" content element

In the backend under Web → Page open the target page. In the desired column click + Content element. In the wizard under Special you find Plain HTML.

In the editor field paste the embed code. Save and check on the frontend page.

Note: The "Plain HTML" content element is by default only available for backend users with the appropriate rights. If it is missing in the wizard, enable it in the User TSconfig.

2. In the RTE of a standard text element

If you want to embed within the running text of a standard "Text" or "Text & Media" component, you have to adjust the RTE HTML filter. In TYPO3 configuration under page TSconfig or the RTE YAML profile, extend the processing rule so that script and div.picpins-embed are allowed.

For a standard CKEditor configuration in the YAML file (e.g. EXT:rte_ckeditor/Configuration/RTE/Default.yaml) extend the allowedContent list.

Note: This is power-user territory. If you have no admin access or TSconfig experience: better use the "Plain HTML" element — faster, cleaner.

3. Build into the backend layout

For embeds that are the same on many pages (e.g. maps in the footer): adjust the TypoScript or Fluid template. In the template module or the corresponding Fluid file (Resources/Private/Templates/Page/Default.html) place the embed directly.

The embed then lives in the theme, not in the content area — no per-page maintenance.

4. With your own extension (custom plugin)

For larger setups (e.g. picpins image as a database field of a custom record) building your own extension pays off. In the extension code put the embed markup in a Fluid partial and maintain it via the CMS backend.

Overkill for 2–3 embeds, but clean for complex sites with many interactive images.

Embed code to copy

<div class="picpins-embed" data-token="dein-token-hier"></div>
<script src="https://picpins.com/embed.js" async></script>

What picpins is great for on TYPO3

University or college sites

Campus map or building photo, hotspots on lecture halls, library, cafeteria, administration.

Government and administration sites

Photo of city hall or admin building, hotspots on contact points, office hours, elevators.

Industry and machinery

Machine photo with hotspots on components, safety notes, maintenance documents.

Tourism and culture

City map, sights as polygon markers with photo, opening hours, audio guide link.

Tips and gotchas

Always use the "Plain HTML" element, not the RTE — saves hours on filter configuration.
If the element is missing: check User TSconfig and unlock the wizard item.
Exclude script optimizations (concatenation, minify) for the picpins script if the site uses those.
For global embeds: prefer a Fluid template override over a content element on every page.
Before TYPO3 major updates: backup, then update, then spot-check "Plain HTML" elements.

Frequently asked questions

Does picpins work in TYPO3 v11 and v12?

Yes, in both. The "Plain HTML" content element is unchanged in both versions. In v12 the RTE configuration is a bit more accessible, the workflow stays the same.

Do I need an extension?

No. "Plain HTML" is a core content element, not a plugin. As long as you have backend edit rights for this element type, it works without further setup.

My "Plain HTML" element is missing in the wizard — why?

The element is locked for non-admin users in some backend configurations. Solution: in User TSconfig or Page TSconfig check and enable the mod.wizards.newContentElement.wizardItems.special.elements.html rule. Admin role has it by default.

Can I paste picpins directly in the RTE?

Theoretically yes, practically the most painful path. The CKEditor in TYPO3 has strict filters that strip <script> and some <div> attributes. You would have to adjust the RTE profile in YAML. Rule of thumb: use the "Plain HTML" element.

Multiple embeds on one page — does it work?

Yes. Every "Plain HTML" content element can hold its own embed. Reusable any number of times on the same page.

Does it work with the TYPO3 cache and with the static file cache?

Yes, both cache strategies store the HTML output that already contains the embed. The embed script runs client-side, independent of the cache. With aggressive script optimization, exclude the picpins script from bundling if needed.

Can picpins integrate with TYPO3 backend workflows?

If you need structured data — e.g. one image per entry in a news extension — building your own extension or a custom field that stores the picpins embed ID pays off. In the Fluid template render the embed per record.

What happens on TYPO3 updates?

Content elements stay stable across updates. "Plain HTML" content is just database strings — they are not touched. Theme embeds (Fluid templates) should always be overrides so they survive template updates.

Embed interactive images in TYPO3