> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# DC- (loops)

> Custom loops in the template: repeat a block a fixed number of times or iterate over a list you put together yourself.

Most loops in the shop run on their own: `{@PR-Data}` iterates over the products of a category, `{@BASKET-PR-Data}` over the items in the basket. Sometimes, however, you need a loop for which there is no ready-made tag, for example five rating stars or a list that you put together yourself.

There are three loop families for this.

| Family | Iterates over | Position counts |
| - | - | - |
| `DC-Loop1…3` | a fixed number of iterations | from 1 |
| `DC-ZeroLoopX` | a fixed number of iterations | from 0 |
| `DC-DynamicLoop1…3` | the entries of a list that you pass | from 1 |

> [!NOTE]
>
> The only difference between `DC-Loop` and `DC-ZeroLoop` is the way they count. With five iterations, `DC-Loop1_position` returns the values 1 to 5, and `DC-ZeroLoopX_position` returns the values 0 to 4. Use `DC-ZeroLoop` if the position is used as an index in another count that starts at 0.

## The structure of a custom loop

Each of the three families is used according to the same pattern.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~DC-Loop1_set(7)~          <!-- Anzahl festlegen -->

{DC-Loop1}                 <!-- nur ausgeben, wenn überhaupt etwas zu tun ist -->
   {@DC-Loop1}             <!-- der eigentliche Schleifenkörper -->
      <img src="stern.svg" alt="">
   {/@DC-Loop1}
{/DC-Loop1}
```

> [!NOTE]
>
> The outer bracketing is not an end in itself. It only applies if the count is greater than 0, and thus keeps headings, table frames, and list structures out of the page when there is nothing to show.

| Notation | Meaning |
| - | - |
| `~DC-Loop1~` | outputs the specified count |
| `{DC-Loop1}…{/DC-Loop1}` | applies if the count is greater than 0 |
| `{!DC-Loop1}…{/!DC-Loop1}` | applies if the count is 0 |
| `{@DC-Loop1}…{/@DC-Loop1}` | repeats the content |
| `~DC-Loop1_position~` | outputs the current iteration within the loop body |

## A fixed number of iterations

`DC-Loop1_set()` specifies the count. The argument supports tag-in-tag, so the count can come from another tag.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~DC-Loop1_set($PR-Rating$)~

{DC-Loop1}
   {@DC-Loop1}
      <img src="stern-voll.svg" alt="">
   {/@DC-Loop1}
{/DC-Loop1}

{!DC-Loop1}
   <span class="hinweis">Noch nicht bewertet</span>
{/!DC-Loop1}
```

> [!WARNING]
>
> A negative value becomes 0, and a very large value is capped. The loop therefore does not abort, but silently runs with a different count than intended. Check the value if it comes from a data source.

### DC-ZeroLoop

`DC-ZeroLoopX` works in the same way, but counts from 0.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~DC-ZeroLoop1_set(5)~

{@DC-ZeroLoop1}
   Position ~DC-ZeroLoop1_position~   <!-- 0, 1, 2, 3, 4 -->
{/@DC-ZeroLoop1}
```

> [!NOTE]
>
> Unlike with `DC-Loop`, the `X` in `DC-ZeroLoop` is not a placeholder for a digit from 1 to 3, but a freely selectable name, just like with the free parameters. `DC-ZeroLoopSpalten` and `DC-ZeroLoopZeilen` are two independent loops. A maximum of 50 different names is possible per page request; beyond that, the shop does not create any further loops and writes a critical error to the log. The previous documentation lists the tag as `DC-ZeroLoop1…3`.

## Iterating over a custom list

`DC-DynamicLoop1…3` is passed a list and iterates over its entries.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~DC-DynamicLoop1_set(Tom Waits,Michael Jackson,Nina Hagen)~

{DC-DynamicLoop1}
   <label for="top3">Künstlerin oder Künstler</label>
   <select id="top3" name="top3" size="3">
      {@DC-DynamicLoop1}
         <option>~DC-DynamicLoop1_data~</option>
      {/@DC-DynamicLoop1}
   </select>
{/DC-DynamicLoop1}
```

| Tag | Effect |
| - | - |
| `DC-DynamicLoop1…3_set()` | passes the list |
| `DC-DynamicLoop1…3` | as a single tag, the number of entries; as a range tag, the check for entries; as a loop tag, the iteration |
| `DC-DynamicLoop1…3_data` | outputs the current entry within the loop body |
| `DC-DynamicLoop1…3_position` | outputs the sequential number within the loop body |

The following are permitted as the argument of `_set()`: a fixed list in the template, another tag as tag-in-tag, or a text variable.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~DC-DynamicLoop1_set(%%Musiker%%)~
~DC-DynamicLoop2_set($CAT-SubCatIndexList$)~
```

> [!NOTE]
>
> Empty entries are dropped, and spaces at the beginning and end of each entry are trimmed. `a, ,b , c` therefore becomes the three entries `a`, `b` and `c`.

> [!WARNING]
>
> `_set()` must not be placed within its own loop. In this case, the shop discards the tag. Set the list before `{DC-DynamicLoop1}`.

> [!NOTE]
>
> The 128-character limit of WEBSALE tags does not apply to the list itself, provided it comes in via tag-in-tag. If it is fixed text in the tag, the limit does apply. Therefore, build long fixed lists with `DC-FPX_append()` and pass them as tag-in-tag.

Reference: DC-FPX\_append

### A different separator

If the entries themselves contain commas, you need a different separator. `_setseparator()` specifies it.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~DC-DynamicLoop1_setseparator(-)~
~DC-DynamicLoop1_set(Tom Waits, amerikanischer Sänger-Michael Jackson, King of Pop-Nina Hagen, deutsche Sängerin)~

{@DC-DynamicLoop1}
   <option>~DC-DynamicLoop1_data~</option>
{/@DC-DynamicLoop1}
```

> [!WARNING]
>
> `_setseparator()` must come before `_set()`. If set afterwards, it no longer has any effect, because the list has already been split at that point.

> [!NOTE]
>
> The separator can also be several characters long, for example `||`. Upper and lower case do not matter.

### Entries with markers

If the list comes from a third-party system and the entries there are enclosed by markers instead of separated by a character, use `_setSeparatorTags()` and `_settaggeddata()`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~DC-DynamicLoop1_setSeparatorTags(<c>,</c>)~
~DC-DynamicLoop1_settaggeddata(<c>EUR</c><c>USD</c><c>CHF</c>)~

{@DC-DynamicLoop1}
   - ~DC-DynamicLoop1_data~
{/@DC-DynamicLoop1}
```

> [!WARNING]
>
> The order also matters here: `_setSeparatorTags()` specifies the two markers and must come before `_settaggeddata()`.

> [!NOTE]
>
> `_settaggeddata()` supports tag-in-tag. This allows you to turn the response of an interface directly into a loop without reformatting it first.

* Guide: Displaying products and categories anywhere in the shop
* Guide: Vouchers with multiple currencies

## Overview of the tags

| Tag | Single tag | Range tag | Negative range tag | Loop tag |
| - | - | - | - | - |
| `DC-Loop1…3` | yes | yes | yes | yes |
| `DC-Loop1…3_set()` | yes | – | – | – |
| `DC-Loop1…3_position` | yes | – | – | – |
| `DC-ZeroLoopX` | yes | yes | yes | yes |
| `DC-ZeroLoopX_set()` | yes | – | – | – |
| `DC-ZeroLoopX_position` | yes | – | – | – |
| `DC-DynamicLoop1…3` | yes | yes | yes | yes |
| `DC-DynamicLoop1…3_set()` | yes | – | – | – |
| `DC-DynamicLoop1…3_data` | yes | – | – | – |
| `DC-DynamicLoop1…3_position` | yes | – | – | – |
| `DC-DynamicLoop1…3_setseparator()` | yes | – | – | – |
| `DC-DynamicLoop1…3_setSeparatorTags()` | yes | – | – | – |
| `DC-DynamicLoop1…3_settaggeddata()` | yes | – | – | – |

All tags are permitted in all templates. `_data` and `_position` only output something within the associated loop.

## Related topics

* Guide: Displaying products and categories anywhere in the shop
* Guide: Vouchers with multiple currencies
* Reference: DC- (counters and calculations)
* Basics: Tag basics


## Related topics

- [DC- (counters and calculations)](https://dokumentation.websale.de/en/v8s/referenz/tags/dc/rechnen.md)
- [DC- (free parameters and session parameters)](https://dokumentation.websale.de/en/v8s/referenz/tags/dc/parameter.md)
- [EJD- (JSON interface)](https://dokumentation.websale.de/en/v8s/referenz/tags/ejd.md)
- [Basics of tags](https://dokumentation.websale.de/en/v8s/grundlagen-zu-tags.md)
- [DC- (cookie data)](https://dokumentation.websale.de/en/v8s/referenz/tags/dc/cookie-daten.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.