/docs/index.rst

varilog
=======

varilog bietet ein einfaches Blogsystem für SallyCMS, das mittels Artikeltypen
und dem Gästebuch-AddOn die Grundfunktionen eines Blogs anbietet, aber bei
weitem nicht so umfangreich wie WordPress o.ä. ist. Support für Trackbacks und
Pingbacks ist integriert.

Installation
------------

Das AddOn sollte über Composer installiert werden, indem :file:`composer.json`
des Projekts um einen Eintrag erweitert wird:

.. sourcecode:: json

  {
     "require": {
        "webvariants/varilog": "*"
     }
  }

Nach einem ``composer install`` können dann varilog und dessen Abhängigkeiten
installiert werden. Damit steht ein Blog ohne Kommentarfunktion bereit.

Kommentare
""""""""""

Um die Beiträge kommentierbar zu machen, kann das Gästebuch-AddOn verwendet
werden. Es wird analog zu varilog eingerichtet:

.. sourcecode:: json

  {
     "require": {
        "webvariants/varilog": "*",
        "webvariants/guestbook": "*"
     }
  }

varilog und das Gästebuch kennen sich grundsätzlich nicht; der Projektentwickler
ist dafür verantwortlich, beide im Frontend miteinander zu kombinieren.

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

Der Grundgedanke bei varilog ist der, dass es über reguläre Sally-Artikel
arbeitet, die anhand ihres Artikeltyps identifiziert werden. So kann in varilog
angegeben werden, dass alles Artikel eines bestimmten Typs als Blogbeiträge
angesehen werden soll.

Bevor mit der Einrichtung begonnen wird, müssen die nötigen Konfigurationsdateien
noch nach ``develop/config`` kopiert werden. In beiden AddOns liegen jeweils
Vorgabedateien, die kopiert und deren Kopien dann nach Bedarf angepasst werden
können.

Ausgangssituation
"""""""""""""""""

Wir wollen einen Blog mit Kommentarfunktion (über das Gästebuch) und einer
Übersicht aller Beiträge erstellen. Dazu benötigen wir einige Module sowie etwas
Konfiguration, die im Folgenden beschrieben werden.

Blogübersicht
"""""""""""""

**Modul-Eingabe (blogoverview.input.php)**

Für die Moduleingabe sind meist keine besonderen Felder nötig. Man kann sich das
hier also sehr einfach machen und einfach eine kurze Infomeldung ausgeben. Damit
der Redakteur im Backend ein paar nützliche Informationen erhält, geben wir die
Liste aller Blogbeiträge im Backend aus.

Die Blogartikel holen wir uns über ``WV32_Provider::getArticles()``. Danach
laufen wir nur noch über das Array ``$articles`` und verlinken jeden Artikel.

.. sourcecode:: php

  <?
  /**
   * @sly name  blogoverview
   * @sly title Blogübersicht
   */

  $articles = WV32_Provider::getArticles(
     true,            // nur Beiträge, die online sind
     'updatedate',    // sortiert nach Aktualisierungsdatum
     'DESC'           // absteigend sortiert
  );

  print '<p style="padding:5px">Dieses Modul listet alle Blogeinträge auf.</p>';
  print '<ul>';

  foreach ($articles as $article) {
     $url  = $article->getUrl();
     $name = sly_html($article->getName());

     print '<li><a href="../'.$url.'">'.$name.'</a></li>';
  }

  print '</ul>';


**Modul-Ausgabe (blogoverview.output.php)**

Hier wollen wir unsere Blogbeiträge ausgeben.

.. sourcecode:: php

  <?
  /**
   * @sly name  blogoverview
   * @sly title Blogübersicht
   */

  $articles = WV32_Provider::getArticles(true, 'updatedate', 'DESC');

  // $articles ist keine Liste von sly_Model_Article-Objekten, sondern eine
  // Liste von WV32_Article-Objekten. Das sind spezielle Wrapper um die eigentlichen
  // Artikel und bieten Zusatzfunktionen zum Abrufen der Tags und dergleichen.

  foreach ($articles as $article) {
     $url     = $article->getUrl();
     $date    = $article->getCreateDate('%d. %m. %Y');
     $name    = sly_html($article->getName());
     $content = $article->getContent();

     // Hier findet die Integration mit dem Gästebuch statt. Für jeden
     // varilog-Beitrag gibt es potenziell ein Gästebuch namens 'article_X'
     // (X ist die Artikel-ID), das die Kommentare enthält. Wir wollen hier nur
     // die Gesamtanzahl von Kommentaren ermitteln.

     // Der Name des Gästebuchs (article_X) muss mit der Konfiguration des
     // Gästebuch-AddOns (develop/guestbook.yml) übereinstimmen!
     $comments = WV19_Provider::getCount(false, array(), 'article_'.$article->getId());

     ?>
     <div class="blog">
        <a href="<?= $url ?>">
           <h1><?= $name ?></h1>
           <span class="time"><?= $date ?></span>
        </a>
        <div class="wymeditor">
           <?
           print $content;

           if ($comments > 0) {
              echo '<div class="comments"><a href="'.$url.'">'.$comments.' Kommentar(e)</a></div>';
           }
           ?>
        </div>
     </div>
     <?
  }

Dass ``->getUrl()``, ``->getName()`` etc. auf ``$article`` funktionieren, liegt
daran, dass ``WV32_Article`` diese Methode entsprechend auf ``sly_Model_Article``
weiterleitet. Es gibt nicht für alle Methoden diese Proxies, sodass teils auch
der Zugriff auf den "echten" Artikel notwendig ist. Dieser kann über
``$article->getArticleModel()`` abgerufen werden.

Das war es schon. Jetzt haben wir eine "schöne" Blogübersicht, die unsere
Artikel nach Datum absteigend anzeigt. Das einzige was wir noch machen müssen,
ist eine Kategorie "Blog" zu erstellen und darin einen Artikel, dem wir dieses
Modul zuweisen. Der Name ist natürlich frei wählbar.

Blogartikel
"""""""""""

Kommen wir zu den eigentlichen Blogbeiträgen. Hier bauen wir uns unseren
eigentlichen Beitrag mit dem Gästebuch und den Einträgen auf. Den Beitrag selbst
zu holen entspricht dem Vorgehen aus der Blogübersicht. Da wir ja alle auflisten
können, können wir auch eines ausgeben. Das interessantere ist das Gästebuch.

Typischerweise gibt es zwar einen Blog-Artikeltyp und ein dazugehöriges Template,
allerdings keine speziellen Blog-Module. Es ist in den meisten Fällen falsch,
sich extra das CKEditor-Modul zu kopieren und es "Blogbeitrag" zu nennen.
Stattdessen sollten in Blogartikeln ganz normaler Content zum Einsatz kommen.

Das Blogbeitrag-Template unterscheidet sich also nicht großartig von den anderen
Templates eines Projekts, außer dass ggf. mehr, blogspezifische Informationen
wie die Trackback-URL oder ein Kommentarformular mit ausgegeben werden.

Kommentare
""""""""""

Weder varilog noch das Gästebuch-AddOn geben vor, welche Felder es für Kommentare
geben muss. Überlicherweise werden **Name**, **eMail-Adresse**, **Homepage**
sowie ein **Text** erfasst. Auf Wunsch können allerdings auch mehr oder weniger
Felder verwendet werden. Im Folgenden gehen wir von den o.g. Feldern aus.

Die dazu nötige Konfiguration des Gästebuchs (``develop/guestbook.yml``) sähe
damit in etwa so aus:

.. sourcecode:: yaml

  # ...

  -
     pattern: 'article_*'
     fields:
        name:     { name: 'Name',     type: 'input'    }
        email:    { name: 'eMail',    type: 'input'    }
        homepage: { name: 'Homepage', type: 'input'    }
        text:     { name: 'Text',     type: 'textarea' }
     display: ['name', 'email', 'homepage', 'text', 'wv19_edit_count', 'wv19_updated']
     format: '#text%short#'
     pause: 0
     visibility:
       default: false
       onedit: false

  # ...

Nun könnte der Code zum Anzeigen der Kommentare wie folgt gestaltet werden:

.. sourcecode:: php

  <?
  // printBlogArticle();
  // handleCommentFormSubmission();
  // printCommentForm();

  $guestbook = new WV19_Guestbook('article_'.$article->getId());
  $comments  = $guestbook->getEntries();

  print '<div id="comments">';

  foreach ($comments as $comment) {
     // auf keinen Fall sly_html() vergessen!
     $name = sly_html($comment->getValue('name'));
     $text = sly_html($entry->getValue('text'));
     $date = date('d.m.Y',strtotime($entry->getPosted()));

     ?>
     <div class="comment">
        <div class="title">von <strong class="autor"><?= $name ?></strong>, am <strong class="date"><?= $date ?></strong> geschrieben</div>
        <div class="content"><?= $text ?></div>
     </div>
     <?
  }

  print '</div>';

Ein dazu passenden Kommentar-Formular kann in einfachem HTML geschrieben oder
mittels Form-Evaluation-AddOn entwickelt werden. In HTML könnte es wie folgt
aussehen:

.. sourcecode:: html

  <div id="guestbook_form">
     <form class="commentform" action="<?= $article->getUrl() ?>" method="post">
        <div class="commentbox">
           <input type="text" name="name" placeholder="Name" />
           <input type="text" name="email" placeholder="eMail-Adresse eingeben" />

           <textarea name="commenttext" rows="5" cols="5" placeholder="Ihr Kommentar"></textarea>
        </div>

        <div>
           <input type="submit" name="send_comment" id="send_comment" value="Absenden" />
        </div>
     </form>
  </div>

Dieses Formular wird auf den Blogartikel selbst abgeschickt, sodass es sich
hier ganz gut macht, die Auswertung direkt im Blogtemplate vorzunehmen.

.. sourcecode:: php

  <?
  /**
   * @sly name  blog
   * @sly title Mein Blogtemplate
   */

  // der aktuelle, aufgerufene Artikel
  $article = WV32_Article::getInstance();

  // Kommentare könnten deaktiviert sein
  if (!empty($_POST) && $article->commentsEnabled()) {
     $guestbook = new WV19_Guestbook('article_'.$article->getId());
     $name      = sly_post('name', 'string');
     $email     = sly_post('email', 'string');
     $text      = sly_post('commenttext', 'string');

     try {
        // erstelle den Kommentar, 2. Argument ist die IP des Clients, damit
        // das AddOn vor Flooding schützen kann

        $entry = $guestbook->post(array(
           'name'  => $name,
           'email' => $email,
           'text'  => $text
        ), $_SERVER['REMOTE_ADDR']);

        // hier theoretisch noch den Seiteninhaber per Mail benachrichtigen
        // auf Wunsch kann jetzt entweder direkt der Artikel angezeigt oder
        // auf ihn weitergeleitet werden (um doppelte Form Submissions zu
        // vermeiden).
     }
     catch (Exception $e) {
        print '<p>Der Kommentar konnte nicht erstellt werden: '.sly_html($e->getMessage()).'</p>';
     }
  }

  // hier kann nun der Rest folgen: Artikel anzeigen, Kommentare anzeigen etc.

Weitere Informationen
---------------------

* `Repository <https://bitbucket.org/webvariants/varilog>`_
* `Bug Tracker <https://bitbucket.org/webvariants/varilog/issues>`_
* `Gästebuch-AddOn <https://bitbucket.org/webvariants/guestbook>`_