/docs/index.rst
ReStructuredText | 314 lines | 238 code | 76 blank | 0 comment | 0 complexity | 3d0bdcd3b244bf3bc031b43c29d99b09 MD5 | raw file
- 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>`_