Meta Infos
==========

Das MetaInfo AddOn dient dazu, Sally-Artikel (und Kategorien, Medien und
Benutzern) mit weiteren Informationen zu versehen. Die Metainfos können
mehrsprachig und mit verschiedenen
`Datentypen <http://docs.webvariants.de/devutils/latest/>`_ verwaltet werden.
Die Konfiguration erfolgt über YAML-Dateien.

.. image:: /_static/slice.png

Konzept
-------

Jeder Artikel in Sally gehört zu genau einem Artikeltyp. Dieser steuert, welche
Metainfos für den jeweiligen Artikel verfügbar sind (d.h., dass nicht jeder
Artikel jede Metainfo erhalten muss). Damit ist es möglich, für "Jobs" andere
Infos zu vergeben als für "News-Artikel".

Außerdem werden Metainfos entweder direkt auf der Content-Seite (dort, wo auch
die Module gepflegt werden) oder auf der Meta-Seite angezeigt.

Systemvoraussetzungen
---------------------

* SallyCMS 0.5+
* Developer Utils

Konfiguration
-------------

Nachdem das AddOn installiert wurde, sollte unbedingt der **Entwicklermodus**
eingeschaltet werden, damit Änderungen an der Konfiguration sofort im Backend
sichtbar sind.

Metainfos können über beliebig viele Dateien hinweg konfiguriert werden. Es
können also die Projekt-Metainfos in einer :file:`metainfos.yml` abgelegt
werden, während die Metainfos eines AddOns in :file:`addonX.yml` abgelegt
werden. Für Multi-Domain-Projekte könnte man eine YAML-Datei pro Domain
verwenden. Für diese Dokumentation soll eine einzelne Datei verwendet werden.

Wir legen also eine neue Datei namens :file:`metainfos.yml` im Verzeichnis
:file:`develop/config/` an. Dort werden nun die Metainfos wie folgt definiert:

.. sourcecode:: yaml

  metainfo:
    articles: []
    categories: []
    media: []

Wie schon oben erwähnt, gibt es Metainfos für Artikel, Kategorien, Dateien und
Benutzer. Daher werden sie hier auch getrennt definiert.

.. sourcecode:: yaml

  metainfo:
    articles:
      author:
        title: Autor
        datatype: stringline
        params:
          maxlength: 50
        helptext: Geben Sie hier Ihren Namen an.
        metapage: false
        types: [default, news]
      keywords:
        title: Schlüsselwörter
        datatype: stringline
        helptext: Schlüsselwörter für den HTML-Kopf
        metapage: true
        types: [default, news]

Die obige YAML-Datei definiert zwei Metainfos: **author** und **keywords**. Die
beiden Keys werden als "interne Namen" bezeichnet und dienen dazu, die Metainfos
dann später programmseitig anzusprechen.

**author** wird direkt auf der Slice-Seite angezeigt (``metapage: false``) und
bietet ein einzelnes Eingabefeld für den Autor des Artikels an. Der ``helptext``
wird direkt unter dem Eingabefeld angezeigt (siehe auch `sly_Form
<http://docs.webvariants.de/sallycms/latest/>`_). Außerdem wird die Metainfo für
Artikel der Typen ``default`` und ``news`` verfügbar sein. Dies wird über die
``types``-Angabe geregelt.

**keywords** wird im Gegensatz zu author auf der Meta-Seite angezeigt und hat
keine weiteren Parameter für den stringline-Datentyp (was für ihn soviel
bedeutet wie "Länge ist egal").

Nachdem die Datei angelegt und gespeichert wurde, wird MetaInfo beim nächsten
Aufruf der Website (Frontend oder Backend) die Änderungen erkennen und die
Datenbank entsprechend anpassen.

.. note::

  Es ist klug, Änderungen an Metainfos und Artikeltypen nach und nach
  vorzunehmen. Das erhöht die Chancen, dass die Änderungen an der Datenbank
  problemlos verlaufen. Also lieber erst Artikeltypen anpassen, dann Backend
  aufrufen, dann Metainfos anpassen, Backend aufrufen, usw. -- je mehr
  Änderungen an YAML-Dateien Sally bzw. die AddOns auf einmal verarbeiten
  müssen, desto komplizierter wird die Angelegenheit.

.. warning::

  Ändert man den internen Namen (den Key) einer Metainfo, wird dies als
  "Metainfo X wurde gelöscht und Metainfo Y wurde neu hinzugefügt" gewertet. Bei
  diesem Vorgang werden alle bestehenden Metadaten gelöscht.

Die Konfiguration für Kategorien und Medien ist identisch, bis auf die Tatsache,
dass dort der Key ``metapage`` keine Bedeutung hat.

Datentypen
----------

Metainfos werden primär über die Datentypen konfiguriert. Eine vollständige
Liste aller zur Verfügung stehenden Typen und ihrer Optionen ("Parameter")
befindet sich in der `Dokumentation der Developer Utils
<http://docs.webvariants.de/devutils/latest/>`_.

Da Datentypen AddOn-unabhängig implementiert sind, können neue AddOns problemlos
neue Datentypen mitbringen, die direkt auch für Metainfos zur Verfügung stehen.
So bringt zum Beispiel varisale einen Datentyp "Produktliste" mit, der auch für
Artikel verwendet werden kann.

API
---

Die größte Stärke von MetaInfo ist die umfangreiche API, die es ermöglicht,
Artikel zu filtern und auf die Daten zuzugreifen.

Ich habe einen Artikel/Kategorie/Datei und will den Autor haben!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. sourcecode:: php

  <?
  $article = sly_Util_Article::findById(1);
  $author  = $article->getMeta('author', 'default');

  // falls der Wert in einer anderen Sprache benötigt wird
  $author = $article->getMeta('author', 'default', 2);

  // dito für Kategorien
  $category = sly_Util_Category::findById(1);
  $metainfo = $category->getMeta('metainfo', 'default');

  // und seit Sally 0.5 auch für Dateien
  $medium   = sly_Util_Medium::findByFilename('joo.jpg');
  $metainfo = $medium->getMeta('metainfo', 'default');

Ich brauche alle Metainfos für einen Artikeltyp!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. sourcecode:: php

  <?
  $metainfos = WV2_MetaProvider::getMetaInfosForArticleType('type');
  // {name: Metainfo-Objekt, name: Metainfo-Objekt, ...}

Ich brauche alle Artikel eines Typs!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. sourcecode:: php

  <?
  $articles = WV2_MetaProvider::getArticlesByType('type', $onlineOnly = true);
  // [sly_Model_Article, sly_Model_Article, ...]

Die o.g. Methode hat noch ein paar weitere Parameter zur Sortierung der Artikel.

Wie viele Artikel gibt es für einen Artikeltyp!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Diese Methode ist effizienter, als eine Liste aller Artikel zu holen und darauf
``count()`` anzuwenden.

.. sourcecode:: php

  <?
  $count = WV2_MetaProvider::getArticleCountByType('type', $onlineOnly = true);

Gib mir alle Artikel, bei denen der Autor gleich 'blub' ist!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. sourcecode:: php

  <?
  $articles = WV2_MetaProvider::getArticlesWithMetaData('author', $onlineOnly, 'blub');
