added loop email tokens for CustomObjectsBundle which helps to send e…

[Ravi-topchunks]

…mails with the list of custom items from an Object

Q	A
Bug fix? (use the a.b branch)	[ ]
New feature/enhancement? (use the a.x branch)	[ ]
Deprecations?	[ ]
BC breaks? (use the c.x branch)	[ ]
Automated tests included?	[ ]
Related user documentation PR URL	mautic/mautic-documentation#...
Related developer documentation PR URL	mautic/developer-documentation#...
Issue(s) addressed	Fixes #...

Description:

DOCS

Custom object loop tokens

Custom items can be rendered in emails (or other content) using loop tokens.

Basic syntax

{custom-object-loop object=product-views | where=segment-filter | order=latest | limit=10}
  {custom-object-loop-value object=product-views | field=name | default=jhon}
{/custom-object-loop}

• {custom-object-loop ...}: Opens the loop and defines which custom items to load.
• {/custom-object-loop}: Closes the loop. Everything between the opening and closing tags is repeated for each matching custom item.
• HTML inside the loop: You can place any HTML (or other tokens) between the loop tags; that block will be repeated.

Loop parameters (custom-object-loop)

• object: Custom object name (e.g. product-views). Required.
• where:
  • Only segment-filter is implemented so far (and it is the default if omitted).
  • It takes the first segment of a segment email, or the first campaign source segment of a campaign email.
  • All custom-object-related filters from that segment are converted into WHERE conditions.
• order:
  • Only latest is supported (and is the default if omitted).
  • Items are ordered from newest to oldest by their creation date.
• limit:
  • Default is 1 if not provided.
  • If greater than 1, multiple items are rendered.

Loop-value parameters (custom-object-loop-value)

• object: Must match the object used in the surrounding custom-object-loop. If it does not match, it is ignored.
• field: Field alias of the custom object whose value should be rendered (for example name, price, color).
• default: Fallback value if the field is empty (for example default=Unknown).

Examples

List product names bought by the contact:

{custom-object-loop object=product-views | where=segment-filter | order=latest | limit=3}
  {custom-object-loop-value object=product-views | field=name | default=Unknown product}<br>
{/custom-object-loop}

Rendered example:

Mautic T-shirt<br>
Mautic Hoodie<br>
Mautic Cap<br>

Render a small HTML block per product:

{custom-object-loop object=product-views | where=segment-filter | order=latest | limit=2}
  <div class="product">
    <strong>{custom-object-loop-value object=product-views | field=name | default=Unknown}</strong><br>
    Price: {custom-object-loop-value object=product-views | field=price | default=0}<br>
    Color: {custom-object-loop-value object=product-views | field=color | default=Unknown}
  </div>
{/custom-object-loop}

Rendered HTML (for 2 products):

<div class="product">
  <strong>Mautic T-shirt</strong><br>
  Price: 123<br>
  Color: Blue
</div>
<div class="product">
  <strong>Mautic Hoodie</strong><br>
  Price: 153<br>
  Color: Red
</div>

Warnings and limitations

• Multiple segments: If multiple segments are used for segment emails or campaign sources, each segment must have identical custom object filters. Only the filters of the first segment are used during token replacement when sending emails.
• No OR conditions: Do not use OR conditions in the source segments for custom object filters.
• No include/exclude membership filters: Do not use include/exclude segment membership filters when relying on these tokens. Token replacement only considers filters on the root segment, not on all included/excluded segments.

Steps to test this PR:

1. Open this PR for testing locally (see docs on testing PRs here)

[Ravi-topchunks]

this PR contains email tokens which provides loop tokens this helps to add top products into the email with LIMIT. Please have a look at emailtokens.md

[escopecz]

I think I'm commenting on the same things as our CI will. I let it run first.

[escopecz]

Can you please also provide functional tests for this feature? You can reuse these instructions for your AI agent:

https://github.com/mautic/mautic/blob/7.x/.github/prompts/write-test.prompt.md