# Einführung & Grundlagen

Konzepte, Tag-Grundlagen, Filter, Datums-Patterns, Redakteurs-Tags.

# Filter

<!-- last_modified: 29. Jun 2021 -->
<p class="callout info">Um mittels Code einfacher zu filtern, gibt es die Hilfsklasse <code>Records</code> (<a href="/books/cms-handbuch-entwickler/page/records-hilfsklasse-fur-einfaches-filtern">siehe Beschreibung</a>).</p>

Filter können z.B. in Zusammenhang mit [bx:containerfilter](/books/cms-handbuch-entwickler/page/bxcontainerfilter) oder [Container-Filteraction](/books/cms-handbuch-entwickler/page/container-filteraction) verwendet werden, um bestimmte Datensätze anzuzeigen.

## Aufbau eines Filters

Filter werden in XML angegeben. Der grundlegende Aufbau ist folgender:

```xml
<filter>
  <filter-object>
    ...
  </filter-object>
  <filter-object>
    ...
  </filter-object>
  <order/> <!-- ab Version 2.5.7 -->
  <limit/> <!-- ab Version 2.5.7 -->
  <status/> <!-- ab Version 2.6.1 -->
</filter>


```

Eine Mehrfachverwendung von "filter-object" bewirkt eine UND-Verknüpfung dieser Objekte.

## Objekte

Ein "filter-object" ist folgendermaßen aufgebaut:

```xml
<filter-object [required="true"]>
  <field>...</field>
  <field>...</field>
  <type>...</type>
  [
   <request-value>...</request-value>
  |<static-value>...</static-value>
  |<special-value>...</special-value>
  |<request-attribute>...</request-attribute>
  |<session-attribute>...</session-attribute>
  ]
</filter-object>


```

Eine Mehrfachverwendung von "field" bewirkt eine ODER-Verknüpfung der Felder.
Die optionale Angabe von required="true" bewirkt, dass ein Wert, der zum Vergleichen übergeben wird (z.B. bei "request-value") auch vorhanden sein muss, d.h. wenn nichts übergeben wird, wird die Bedingung auch nicht erfüllt.

### field

Der Name des zu überprüfenden Feldes wird angegeben.
Falls das Feld eine Verknüpfung darstellt (Untercontainer, Einzelverknüpfung, Mehrfachverknüpfung), kann auch der Wert eines Feldes der Verknüpfung abgefragt werden, dazu einfach das gesuchte Unter-Feld mit einem Schrägstrich anfügen.

```xml
<field>feldname</field>
<field>feldname/unterfeld</field>     <!-- Untercontainerfeld -->
```

### type

Hier wird die Art des Vergleiches angegeben. Je nach Typ des Feldes, das geprüft wird, sind verschiedene Vergleiche möglich. Diese sind der folgenden Tabelle zu entnehmen.
Verglichen wird dabei der Feldwert mit dem Testwert, so ließt sich z.B. die erste Zeile der Tabelle "*Feldwert enthält Testwert*" oder die Zeile bei Bildern/Dokumenten *"Feldwert ist leer"*.

| Feld-Typ | `Type` | Art des Vergleiches:<br>Feldwert ... [Testwert] |
|----------|--------|--------------------------------------------------|
| einzeiliger oder mehrzeiliger Text | 1 | enthält |
| | 2 | beginnt mit |
| | 3 | endet mit |
| | 4 | ist gleich |
| | 5 | ist leer (Feld soll leer sein: static-value: 1, Feld soll nicht leer sein: static-value: 0) |
| | 6 | Mustervergleich (Regex) |
| | 7 | enthält eines der Wörter von<br>(Wörter durch Leerzeichen oder Kommas trennen, findet auch Teilstrings) |
| | 8 | ist eines der Wörter von<br>(Wörter durch Leerzeichen oder Kommas trennen, nur ganze Wörter) |
| | 9 | enthält alle Wörter<br>(Wörter durch Leerzeichen oder Kommas trennen) |
| | 11 - 19 | <span style="color: rgb(0,0,0);">**leer ODER Bedingung**<br>Bedingung auch erfüllen, falls Feld leer ist (außer für type 5)</span><br><span style="color: rgb(0,0,0);">z.B.: type 14 für "ist gleich oder leer"</span> |
| | 21 - 29 | **NICHT-Bedingung**<br>kehrt die Bedingung um (außer für type 5)<br>z.B.: type 23 für "endet nicht mit" |
| | 31 - 39 | <span style="color: rgb(0,0,0);">**leer ODER NICHT-Bedingung**<br>Kombination von 11 - 19 und 21 - 29</span><br><span style="color: rgb(0,0,0);">z.B.: type 32 für "beginnt nicht mit oder ist leer"</span> |
| Datum mit oder ohne Zeit | 1 | Feld ist größer (neuer) als übergebener Wert |
| | 2 | Feld ist kleiner (älter) als übergebener Wert |
| | 3 | ist gleich (Uhrzeit wird ignoriert) |
| | 4 | ist ungleich (Uhrzeit wird ignoriert) |
| | 5 | ist leer (Feld soll leer sein: static-value: 1, Feld soll nicht leer sein: static-value: 0) |
| | 6 | ist im Jahr (vierstellig angeben) |
| | 7 | ist im Monat (gültige Werte: 1-12) |
| | 8 | ist am Tag (gültige Werte: 1-31) |
| | 11 | Feld ist größer oder gleich als übergebener Wert |
| | 12 | Feld ist kleiner oder gleich als übergebener Wert |
| | 21 | Feld ist leer oder größer/gleich als übergebener Wert |
| | 22 | Feld ist leer oder kleiner/gleich als übergebener Wert |
| | 31 | Feld ist größer/gleich als heute + Testwert Tage |
| | 32 | Feld ist kleiner/gleich als heute + Testwert Tage |
| nur (Uhr)Zeit | 1 | <span style="color: rgb(0,0,0);">Feld ist größer (später)</span> |
| | 2 | <span style="color: rgb(0,0,0);">Feld ist kleiner (früher)</span> |
| | 3 | <span style="color: rgb(0,0,0);">Feld ist gleich</span> |
| | 4 | <span style="color: rgb(0,0,0);">Feld ist ungleich</span> |
| | 11 | <span style="color: rgb(0,0,0);">Feld ist größer/gleich</span> |
| | 12 | <span style="color: rgb(0,0,0);">Feld ist kleiner/gleich</span> |
| | 21 | <span style="color: rgb(0,0,0);">Feld ist leer oder größer/gleich</span> |
| | 22 | <span style="color: rgb(0,0,0);">Feld ist leer oder kleiner/gleich</span> |
| | 6 | <span style="color: rgb(0,0,0);">Feld ist in Stunde (0-23)</span> |
| | 7 | <span style="color: rgb(0,0,0);">Feld ist in Minute (0-59)</span> |
| | 8 | <span style="color: rgb(0,0,0);">Feld ist in Sekunde (0-59)</span> |
| | 5 | <span style="color: rgb(0,0,0);">Feld ist leer (Feld soll leer sein: static-value: 1, Feld soll nicht leer sein: static-value: 0)</span> |
| Zahl oder Preis | 1 | Feld ist größer gleich als übergebener Wert |
| | 2 | Feld ist kleiner gleich als übergebener Wert |
| | 11 | Feld größer als übergebener Wert |
| | 12 | Feld kleiner als übergebener Wert |
| | 3 | ist gleich |
| | 4 | ist ungleich |
| | 5 | ist leer (Feld soll leer sein: static-value: 1, Feld soll nicht leer sein: static-value: 0) |
| | 21 - 24 | **leer ODER Bedingung** (1 bis 4) |
| | 31 - 32 | **leer ODER Bedingung** (11 und 12) |
| Wahrheitswert (Boolean) | 4 | ist angehakt/gesetzt |
| | 5 | ist leer (null) |
| Bild | 1 | bestimmte ID ist verknüpft |
| | 4 | nicht-gelöschtes Bild ist verknüpft *(ab v2.6.2)* |
| | 5 | ist leer (Feld soll leer sein: static-value: 1, Feld soll nicht leer sein: static-value: 0) |
| Dokument | 5 | ist leer |
| | 8 | bestimmte ID ist verknüpft |
| Kartenkoordinaten | 21 | x ist gleich |
| | 26 | y ist gleich |
| | 5 | ist leer (Feld soll leer sein: static-value: 1, Feld soll nicht leer sein: static-value: 0) |
| Einzelverknüpfung | 8 | Datensatz-ID ist gleich |
| | 10 | Datensatz-ID ist ungleich<br>Bei mehreren IDs, Filter mehrmals verwenden. |
| | 9 | Datenlisten-ID ist gleich (nur bei alten Containern) |
| | 12 | enthält eine der Datensatz-IDs von<br>(IDs durch Leerzeichen, Komma oder Semikolon trennen) |
| | 5 | ist leer (Feld soll leer sein: static-value: 1, Feld soll nicht leer sein: static-value: 0) |
| | 4 | ist verknüpft (ab 2.6.2) |
| | 3 | ist aktiviert (ab 2.6.2) |
| Mehrfachverknüpfung | 8 | enthält Datensatz-ID |
| | 10 | <span style="color: rgb(0,0,0);">enthält Datensatz-ID <u>nicht</u> (</span>*ab v2.6.2*<span style="color: rgb(0,0,0);">)</span> |
| | 12 | enthält eine der Datensatz-IDs von<br>(IDs durch Leerzeichen, Komma oder Semikolon trennen) |
| | 14 | enthält alle der angegebenen IDs |
| | 5 | ist leer (Feld soll leer sein: static-value: 1, Feld soll nicht leer sein: static-value: 0) |
| Untercontainer | 5 | ist leer (Feld soll leer sein: static-value: 1, Feld soll nicht leer sein: static-value: 0) |

### value

Der gesuchte Wert kann auf unterschiedliche Weise übergeben werden. Für `<value>...</value>` können die folgenden Abfragen eingesetzt werden.

#### request-value

Der Vergleich findet mit dem Wert eines Request-Parameters statt.

```xml
<request-value>Request-Parameter-Name</request-value>
```

#### request-attribute

Der Vergleich findet mit dem Wert eines Request-Attributes statt.

```xml
<request-attribute>Request-Attribut-Name</request-attribute>
```

#### session-attribute

Ein Session-Attribut wird mit dem Feld verglichen.

```xml
<session-attribute>Session-Attribut-Name</session-attribute>
```

#### static-value

Der Wert zum Vergleichen wird direkt übergeben.

```xml
<static-value>gesuchter Wert</static-value>
```

#### special-value

Es wird ein spezieller Wert zum Vergleich herangezogen.

| | |
|--|--|
| TODAY | Es wird mit dem heutigen Datum im Format dd.MM.yyyy verglichen. Um Tage dazu zu addieren (oder abzuziehen) kann das Attribut days verwendet werden (ganze Zahl, die auch negativ sein kann).<br>`<special-value [days="n"]>TODAY</special-value>` |
| NOW | Es wird mit der aktuellen Zeit im Format dd.MM.yyyy mm:HH verglichen. Um Tage, Stunden oder Minuten dazu zu addieren (oder abzuziehen) können die Attribute days, hours oder minutes verwendet werden (ganze Zahl, die auch negativ sein kann).<br>`<special-value [days="n"] [hours="n"] [minutes="n"]>NOW</special-value>` |
| USERID | Es wird mit der UserID des aktuellen (eingeloggten) Betrachters verglichen.<br>`<special-value>USERID</special-value>` |
| SESSIONID | Die aktuelle SessionID wird abgeglichen.<br>`<special-value>SESSIONID</special-value>` |
| USERGROUPS | Dieser Spezialwert erzeugt eine Zeichenkette, welche die ID des Users sowie die IDs der Gruppen, denen er angehört, enthält (jeweils durch Leerzeichen getrennt).<br>`<special-value>USERGROUPS</special-value>` |
| PARENTCONTAINER | Es wird mit der ID des übergeordneten Containers verglichen.<br>`<special-value>PARENTCONTAINER</special-value>` |

#### clipboard-value

Es wird ein spezieller Clipboard-Wert zum Vergleich herangezogen.

#### system-value

Es wird der Wert einer Systemvariablen zum Vergleich herangezogen. Die Systemvariable wird unter "<a href="/books/cms-handbuch-redakteure/page/systemeinstellungen">Systemeinstellungen</a>" angelegt und gespeichert.

## order

Hier wird ein Sortierfeld definiert.

```xml
<order field="{Feldname}" [direction="{ascending|descending}"] />
```

Bei "field" wird der Feldname angegeben, nach dem sortiert wird. Sortiert werden kann nach einzeiligen Text, Datumtypen und Zahlentypen.
Bei "direction" wird "ascending" für aufsteigende Sortierung, und descending für absteigende Sortierung angegeben. Bei weglassen der Sortierrichtung wird aufsteigend sortiert.

*Diese Funktion ist ab v2.5.7 verfügbar*

## limit

Hier wird eine Startposition und ein überlauf in der Ergebnisliste definiert

```xml
<limit [index="{feste Startposition}"] [max="{Anzahl bis überlauf}"] />
```

Bei "index" wird die Startposition in der Ergebnisliste angegeben. Standardwert ist 0 für den ersten Datensatz.
Bei max wird angegeben, wie viele Datensätze maximal (je Seite) angezeigt werden. Standardwert ist -1 für keine Einschränkung.
Bei Angabe von max im [bx:containerfilter](/books/cms-handbuch-entwickler/page/bxcontainerfilter) wird diese Einstellung überschrieben.

*Diese Funktion ist ab v2.5.7 verfügbar*

## status

Es kann angegeben werden, ob aktive und/oder inaktive Datensätze gefiltert werden sollen.

```xml
<status active="{false| true}" inactive="{false| true}" />
```

Erklärt sich - glaube ich - von selbst.

*Diese Funktion ist ab v2.6.1 verfügbar*

## ID-Filter

zum Filtern der Datensatz-ID oder mehrerer IDs - getrennt durch Komma

```xml
<filter-id type="include" request-value="paramname" />
<filter-id type="include" request/session-attribute="paramname" />
<filter-id type="include" system/clipboard-value="paramname" /> <!-- ab v2.6.2 -->
<filter-id type="include">feste_id</filter-id>
```

Gegenteil von include: exclude (schließt diese ID(s) aus) *(weitere Erläuterungen folgen noch)*

## Beispiele

**Datumsvergleich**

```xml
<filter>
  <filter-object>
    <field>Datum</field>
    <type>11</type>
    <special-value days="-1">TODAY</special-value>
 </filter-object>
</filter>
```

Es werden nur Datensätze angezeigt, die maximal einen Tag alt sind.

**Suche**

```xml
<filter>
  <filter-object>
    <field>Kategorie</field>
    <type>8</type>
    <request-value>kat</request-value>
  </filter-object>
  <filter-object>
    <field>Titel</field>
    <field>Text</field>
    <type>1</type>
    <request-value>search</request-value>
  </filter-object>
  <filter-object>
    <field>Archiv</field>
    <type>4</type>
    <static-value>0</static-value>
  </filter-object>
</filter>
```

Nur Datensätze, die folgenden Kriterien entsprechen werden ausgegeben:

- Kategorie-ID (Einzel- oder Mehrfachverknüpfung) ist die selbe wie im Request-Parameter `kat`
- Felder Titel oder Text enthalten den Suchbegriff aus dem Request-Parameter `search`
- Haken bei Archiv (Wahrheitswert) ist nicht gesetzt

# Parameter-Werte (Präfixe)

<!-- last_modified: 30. May 2014 -->
Mit den folgenden Präfixen kann man auf verschiedene Variablen zugreifen:

- **request**:Name - der Wert wird aus dem Request-Parameter "Name" geholt
- **attribute**:Name - der Wert wird aus dem Request-Attribut "Name" geholt
- **session**:Name - der Wert wird aus dem Session-Attribut "Name" geholt
- **clipboard**:Name - der Wert wird aus dem Clipboard "Name" geholt
- **static**:Wert - es wird direkt "Wert" verwendet
- **system**:Wert - es wird auf die Systemvariable "Wert" zugegriffen

Diese Präfixe können als Wert jedes Tag-Attributes verwendet werden.

### Nur bei [bx:containerfilter](/books/cms-handbuch-entwickler/page/bxcontainerfilter):

- **special**:PARENTCONTAINER - ID des übergeordneten Datensatzes
- **special**:USERID - ID des angemeldeten Users
- **special**:SESSIONID - Sessionid wird geholt
- **special**:NOW - Vergleich mit "jetzt"
- **special**:TODAY - Vergleich mit "heute"

ab 2.6.2.

- **requests**:IDs - IDs mit Leerzeichen getrennt werden aus dem Request genommen
- **requestc**:IDs - IDs mit Komma getrennt werden aus dem Request genommen

# Pattern bei Datum

<!-- last_modified: 10. Jan 2018 -->
| Pattern | Entsprechung |
|---------|-------------|
| d | Tages im Monat ohne vorangestellter 0 bei einstelligen Zahlen (z.B. <span style="color: rgb(255,0,0);">5</span>.12.2013) |
| dd | Tages im Monat mitvorangestellter = (z.B. <span style="color: rgb(255,0,0);">05</span>.12.2013) |
| M | Monatsangabe ohne vorangestellter 0 bei einstelligen Zahlen (z.B. 12.<span style="color: rgb(255,0,0);">5</span>.2016) |
| MM | Monatsangabe mit vorangestellter 0 (z.B. 12.<span style="color: rgb(255,0,0);">05</span>.2016) |
| MMM | Monatsangebe als Text (z.B. 12.<span style="color: rgb(255,0,0);">Mai</span>.2016) |
| yy | Zahresangabe zweistellig (z.B. 12.05.<span style="color: rgb(255,0,0);">16</span>), führt evtl. zu Missverständnissen (2016 oder 1916?) |
| yyyy | Jahresangabe vierstellig (z.B. 12.05.<span style="color: rgb(255,0,0);">2016</span>) |
| EE | Wochentagsausgabe als Text gekürzt (z.B. Mo, Di, Mi...) |
| EEE | Wochentagsausgabe als Text ungekürzt (z.B. Montag, Dienstag, Mittwoch...) |
| H | Ausgabe der Stunde ab 0 Uhr ohne vorangestellter 0 bei einstelligen Zahlen (z.B. <span style="color: rgb(255,0,0);">3</span>:40 Uhr) |
| HH | Ausgabe der Stunde ab 0 Uhr mit vorangestellter 0 (z.B. <span style="color: rgb(255,0,0);">03</span>:40 Uhr) |
| mm | augabe der minuten (z.B. 03:<span style="color: rgb(255,0,0);">40 </span>Uhr) |
| ss | Ausgabe der Sekunden (z.B. 03:23:<span style="color: rgb(255,0,0);">34</span><span style="color: rgb(255,0,0);"> </span>Uhr) |

Weitere Infos und Ausgabemöglichkeiten auf der <a href="https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html" target="_blank">offiziellen JavaDoc-Seite</a>

## Beispiele

```xml
<bx:tools.datum pattern="dd.MM.yyyy HH:mm:ss"/>
```

Ausgabe eines Zeitstempels, z.B. 13.03.2016 13:48:33

```xml
Angebote im Monat <bx:recordfield.Datum pattern="MMM"/>
```

Ausgabe des Monatsnamen

# Redakteurs-Tags

<!-- last_modified: 23. Mar 2015 -->
## Titel

```xml
<bx:tag.{titel} />
```

Alle Unterstriche / Underscores ( _ ) im `{titel}` Platzhalter werden in der Verwaltung durch Leerzeichen ersetzt. Zum Beispiel wird dann aus

```xml
<bx:text.Haupt_Titel />
```

dieses Feld in der Verwaltung:

![image2014-1-26 23:12:4.png](https://batix.help/uploads/images/gallery/2026-05/ElAXpUfteo28Vx7S-1572874.png)

## Mehrfachverwendung

Wird der gleiche `{titel}` mehrfach in einem Template oder in mehreren Templates im selben Menüpunkt verwendet, so stellt sich das Tag in der Verwaltung nur einmal dar. Der Redakteur muss den gewünschten Inhalt also nur an einer Stelle einpflegen. Alle gleichnamigen Tags werden dann mit diesem Inhalt versorgt.

<p class="callout warning">Es ist darauf zu achten, nur gleichartige Tags mit dem selben <code>{titel}</code> zu versehen. So machen z.B. <code>&lt;bx:text.Titel /&gt;</code> und <code>&lt;bx:bild.Titel /&gt;</code> im selben Menüpunkt keinen Sinn.</p>

Rechts neben dem Titel in der Verwaltung wird angezeigt, in welchen Templates ein Tag mit diesem Titel verwendet wird. Wird ein Tag in mehreren Templates verwendet, sieht dies z.B. so aus:

![image2014-1-26 23:12:14.png](https://batix.help/uploads/images/gallery/2026-05/WMnozcefYFFCakYP-1572875.png)

Es wird versucht etwaige Parameter der Tags sinnvoll zusammenzufassen. So wird z.B. bei bx:text der maximale Wert aller Tags für `maxlength` genommen.

## Kommentar

```xml
<bx:tag.{titel} [comment="{kommentar}"] />
```

In `{kommentar}` kann ein zusätzlicher Beschreibungstext angegeben werden, der in der Verwaltung unterhalb des Titels angezeigt wird. Beispiel:

**Eingabefeld mit Kommentar**

```xml
<bx:text.Titel comment="Dies ist der große Titel direkt unter dem Headerbild." />
```

![image2014-1-26 0:26:36.png](https://batix.help/uploads/images/gallery/2026-05/H4NkLn4khXnrCDhc-1572871.png)

## Admin-Mode

```xml
<bx:tagname.Titel admin-mode="config" /> 
```

Erzwingt, daß das Tag bei den Tageinstellungen (anstatt bei Dateneingabe) angezeigt wird. So sehen es die Redakteure nicht mehr und können es nicht mehr kaputtmachen.
Bei \<bx:containerfilter\> wird das schon automatisch so gemacht. Jetzt lässt es sich auch per Parameter bei anderen Tags steuern.

### Beispiele

```xml
<bx:text.farbcode admin-mode="config"/>
<bx:textarea.xml type="plain" wrap="off" admin-mode="config"/>
<bx:pageinclude.teaserpfad admin-mode="config"/>
```

Einige Beispiele, wo dies sinnvoll sein könnte.

## Admin-Titel

```xml
<bx:tagname.Titel admin-title="{anderer Titel}" /> 
```

In Verwaltung wird ein anderer Titel ausgeben als der beim Tag angegebene.

### Beispiele

```xml
<bx:bild.picture admin-title="Großes Logo"/>
```

genauere Bezeichnung des "picture"

```xml
<bx:textarea.Haedline admin-title="Headline"/>
```

im Nachhinein einen Schreibfehler zu korrigieren, wenn das Design schon oft in Gebrauch ist

Diese Tags können sich in der Verwaltung darstellen:

- [bx:bild](/books/cms-handbuch-entwickler/page/bxbild)
- [bx:cmpageinclude](/books/cms-handbuch-entwickler/page/bxcmpageinclude)
- [bx:datum](/books/cms-handbuch-entwickler/page/bxdatum)
- [bx:dezimal](/books/cms-handbuch-entwickler/page/bxdezimal)
- [bx:document](/books/cms-handbuch-entwickler/page/bxdocument)
- [bx:email](/books/cms-handbuch-entwickler/page/bxemail)
- [bx:optional](/books/cms-handbuch-entwickler/page/bxoptional)
- [bx:text](/books/cms-handbuch-entwickler/page/bxtext)