Datentyp-Liste
==============

Die Developer Utils liefern eine Reihe von Datentypen mit, mit denen sich die
meisten Probleme bereits lösen lassen. In den folgenden Abschnitten ist in der
Überschrift jeweils der Key des Datentyps mit angegeben. Die Konfiguration
erfolgt (cf. :doc:`Properties </properties>`) wie folgt:

.. sourcecode:: yaml

  <?
  meine_eigenschaft:
     title: Mein Titel
     datatype: KEY # z.B. stringline, stringtext, select, ...
     params:
        param1: value
        param2: value
        # ...

.. note::

  Ab Version **3.3** sind die Bezeichner für Widgets, die ``button`` enthalten,
  deprecated. Es heißt also ab dieser Version ``linklist`` und nicht mehr
  ``linklistbutton``. Die alten Bezeichner funktionieren noch, werden aber in
  einer kommenden Version entfernt.

Einzeiliger Text (stringline)
-----------------------------

==============  ======================================================
Key             Beschreibung
==============  ======================================================
``minlength``   Mindestlänge (Zahl)
``maxlength``   Maximallänge (Zahl)
``width``       Breite (als CSS-Wert)
``align``       Ausrichtung (right, left, center)
``css``         beliebige weitere CSS-Angaben
``annotation``  Text, der rechts neben dem Eingabefeld angezeigt wird.
==============  ======================================================

Mehrzeiliger Text (stringtext)
------------------------------

Stellt eine ``<textarea>`` dar.

============= =============================
Key           Beschreibung
============= =============================
``minlength`` Mindestlänge (Zahl)
``maxlength`` Maximallänge (Zahl)
``css``       beliebige weitere CSS-Angaben
============= =============================

Auswahlfeld (select)
--------------------

Auswahlfelder werden in zwei Arten unterteilt: Diejenigen, die auf einer festen
Liste von Werten basieren, und diejenigen, die auf einer SQL-Abfrage basieren.
Diese Unterscheidung findet im Parameter ``source`` statt.

Feste Werteliste
^^^^^^^^^^^^^^^^

========== ===================================================================================
Key        Beschreibung
========== ===================================================================================
``source`` muss ``values`` sein
``values`` YAML-kodierte Liste von Werten (z.B. ``{key: value, key2: value 2, key3: value3}``)
========== ===================================================================================

Query
^^^^^

Die angegebene Query **muss genau zwei Spalten** selektieren.

========== =======================================================
Key        Beschreibung
========== =======================================================
``source`` muss ``query`` sein
``query``  SQL-Query (z.B. ``SELECT key, value FROM sly_mytable``)
========== =======================================================

In der Query werden die beiden Platzhalter ``%%PREFIX%%`` mit dem Tabellenpräfix
(z. B. ``sly_``) und ``%%CLANG%%`` mit der aktuellen Sprach-ID ersetzt.

Allgemeine Eigenschaften
^^^^^^^^^^^^^^^^^^^^^^^^

========= ==========================================================================================
Key       Beschreibung
========= ==========================================================================================
``style`` Anzeigestil (``select``, ``checkbox`` oder ``readiobox``)
``size``  Größe des ``<select>``-Elements (nur wenn ``style = select``)
``min``   Mindestmenge an Werten, die ausgewählt werden müssen (irrelevant bei ``style = radiobox``)
``max``   Höchstmenge an Werten, die ausgewählt werden müssen (irrelevant bei ``style = radiobox``)
========= ==========================================================================================

Beispiele
^^^^^^^^^

.. sourcecode:: yaml

  # einfache Selectbox mit zwei möglichen Werten
  params:
    source: values
    values:
      a: Wert 1
      b: Wert 2
    min: 1
    max: 1
    size: 1
    style: select

  # Checkbox-Gruppe auf Basis einer SQL-Query
  params:
    source: query
    query: 'SELECT id,name FROM %%PREFIX%%article WHERE 1 ORDER BY name'
    min: 1
    max: 5
    style: checkbox

Checkbox (boolean)
------------------

Stellt eine einzelne Checkbox dar. Der zurückgegebene Wert ist immer entweder
``true`` oder ``false`` (es gibt keinen "nicht angegeben"-Zustand).

=============== ==========================================================
Key             Beschreibung
=============== ==========================================================
``description`` Beschreibungstext, der hinter der Checkbox erscheinen soll
=============== ==========================================================

.. note::

  In den Developer Utils bis einschließlich Version 3.0.x war es möglich, den
  Beschreibungstext direkt als Parameter anzugeben (``params: text text text...``).
  Dies ist ab Version 3.1 nicht mehr möglich.

Sally Link Button (link)
------------------------

Gibt bei Abruf die gespeicherte Artikel-ID oder ``null``, falls kein Artikel
ausgewählt oder der gewählte Artikel nicht existiert, zurück.

============== ===================================================
Key            Beschreibung
============== ===================================================
``required``   ``true`` oder ``false``
``types``      Liste von Artikeltypen, die zugelassen sind
``categories`` Liste von Kategorie-IDs, die zugelassen sind
``recursive``  wenn true, werden die Kategorien rekursiv behandelt
============== ===================================================

Sally Linklist Button (linklist)
--------------------------------

Gibt bei Abruf ein Array von Artikel-IDs zurück. Der Datentyp prüft selber, ob
die Artikel vorhanden sind und wird fehlende Artikel nicht mit zurückgeben.

============== ===================================================
Key            Beschreibung
============== ===================================================
``min``        minimale Anzahl von Artikeln
``max``        maximale Anzahl von Artikeln
``types``      Liste von Artikeltypen, die zugelassen sind
``categories`` Liste von Kategorie-IDs, die zugelassen sind
``recursive``  wenn true, werden die Kategorien rekursiv behandelt
============== ===================================================

Sally Media Button (media)
--------------------------

Gibt bei Abruf den gespeicherte Dateinamen oder ``null``, falls keine Datei
ausgewählt oder die gewählte Datei nicht existiert, zurück.

============== ===================================================
Key            Beschreibung
============== ===================================================
``required``   ``true`` oder ``false``
``types``      Liste von Dateiendungen, die zugelassen sind
``categories`` Liste von Kategorie-IDs, die zugelassen sind
``recursive``  wenn true, werden die Kategorien rekursiv behandelt
============== ===================================================

Sally Medialist Button (medialist)
----------------------------------

Gibt bei Abruf ein Array von Dateinamen zurück. Fehlende Dateien sind dabei
nicht enthalten (man muss also nicht noch einmal von Hand die Existenz der
Dateien prüfen).

============== ===================================================
Key            Beschreibung
============== ===================================================
``min``        minimale Anzahl von Dateien
``max``        maximale Anzahl von Dateien
``types``      Liste von Dateiendungen, die zugelassen sind
``categories`` Liste von Kategorie-IDs, die zugelassen sind
``recursive``  wenn true, werden die Kategorien rekursiv behandelt
============== ===================================================

Datumsangabe (datetime)
-----------------------

Dieser Datentyp verwendet ``sly_Form_DateTime``, um die Eingabe eines Datums zu
ermöglichen. Er kann optional auch noch einen Timepicker anzeigen, der für
Zeitangaben geeignet ist. Der von ihm zurückgegebene Wert ist ein
UNIX-Timestamp.

============ ========================================================
Key          Beschreibung
============ ========================================================
``withtime`` ``true`` um einen Timepicker anzubieten, sonst ``false``
============ ========================================================

.. note::

  In den Developer Utils bis einschließlich Version 3.0.x war es möglich,
  ``withtime`` direkt als Wert der Parameter zu definieren (``params: withtime``).
  Dies ist ab Version 3.1 nicht mehr möglich.

*Beispiel*

.. sourcecode:: yaml

  datatype: datetime
  params:
    withtime: true
