=head1 NAME

Jifty::Manual::Tutorial_de - Einführung in Jifty

=head1 BESCHREIBUNG

Dieses Tutorial sollte Ihnen alles Wichtige mit auf den Weg geben, um
erfolgreich eine erste Applikation mit Jifty zu bauen.

=cut

=head1 WIE?

=head2 Anforderungen

Hier steht, was Sie installiert haben sollten -- wenigstens wenn wir
es schreiben.

=head2 Jifty installieren

Nicht wirklich eine große Sache. Wir glauben stark an das DRY (Don't
Repeat Yourself -- Keine Wiederholungen) Prinzip. Das ist einer der
großen Gründe, warum wir Perl und das CPAN lieben. Jifty benutzt viel
Code aus dem CPAN. Bei der letzten Zählung waren es wenigstens 60
Pakete. Die meisten Module sind auf vielen Plattformen einsetzbare
nur in Perl geschriebene Module und sollten ohne Probleme funktionieren.

Wir haben einige Anstrengungen unternommen, damit Sie nicht Ihre Zeit
damit verbringen müssen, Abhängigkeiten aufzulösen, nur um Jifty zu
installieren. Das Jifty Installationsprogramm stellt fest, welche
Module Ihr System benötigt und lädt bei Bedarf die erforderlichen
Module nach. Also machen Sie sich keine Sorgen, Sie werden immer
gefragt, bevor Änderungen vorgenommen werden.

Auf den meisten Systemen wird Perl mit dem CPAN Modul ausgeliefert,
womit die Jifty Installation einfach wird:

  # perl -MCPAN -e'install Jifty'       # auf Unix-ähnlichen Systemen
  # perl -MCPAN -e"install Jifty"       # auf Win32 Systemen

Falls Sie lieber eine C<.tar.gz> Datei von Jifty herunterladen wollen,
können Sie diese wie folgt installieren:

  # tar xzvf jifty-<version>.tgz
  # cd jifty-<version>
  # perl Makefile.PL
  # make
  # make test
  # make install

Falls die Tests nicht erfolgreich verlaufen, wäre eine Rückmeldung an
uns interessannt. Bitte melden Sie sich bei der Liste
C<jifty-devel@lists.jifty.org> und melden den Fehler. (Oder sehen Sie
nach unter L</HILFE> weiter unten wo beschrieben ist, wie Sie sich uns
anschließen können.)

=head2 Erstellung eines Rumpfes

Wenn Sie Jifty erfolgreich installiert haben, können Sie Ihre erste
Applikation erstellen.

Jifty ist geplantermaßen Minimalistisch. Wenn Sie eine Applikation
erstellen möchten, kopieren Sie einfach das F<jifty>
Kommandozeilenprogramm in das F<bin/> Unterverzeichnis in Ihr
Applikations-Verzeichnis.

OK, es ist natürlich hilfreich, ein wenig strukturierter
vorzugehen. Jifty wird mit Werkzeugen geliefert, die Ihnen helfen, die
notwendigen Strukturen anzulegen.

Wechseln Sie in ein sicheres Verzeichnis, in dem Sie Ihre Applikation
anlegen möchten (Jifty erstellt das notwendige Unterverzeichnis für Sie).

  # jifty app --name MyWeblog
  Can't guess application root from current path (/tmp) or bin path (/usr/bin)
  Creating new application MyWeblog
  Creating directory lib
  Creating directory lib/MyWeblog
  Creating directory bin
  Creating directory etc
  Creating directory doc
  Creating directory log
  Creating directory var
  Creating directory var/mason
  Creating directory share
  Creating directory share/po
  Creating directory share/web
  Creating directory share/web/templates
  Creating directory share/web/static
  Creating directory lib/MyWeblog/Model
  Creating directory lib/MyWeblog/Action
  Creating directory t
  Creating configuration file MyWeblog/etc/config.yml

Sehen wir uns die einzelnen Verzeichnisse genauer an.

=over

=item bin

Innerhalb des F<bin/> Verzeichnisses liegt F<jifty>, die Jifty
Kommandozentrale. Einige der wichtigsten Befehle sind C<schema>,
welches ein Datenbank-Schema erstellt oder erneuert und C<server>,
womit ein funktionsfähiger Webserver gestartet wird. Um die von
F<jifty> verstandenen Kommandos herauszufinden, tippen Sie:

    jifty help

=item etc

Konfigurationsdateien leben in F<etc/> und Jifty wird vernünftige
Standardwerte verwenden, sollte keine Konfigurationsdatei vorhanden
sein oder benötigte Einträge fehlen.

=item doc

Leider erstellt Jifty keine magische Dokumentation, aber wenn Sie
dokumentieren, dann bitte in das Verzeichnis F<doc/>.

=item log

Jifty setzt L<Log::Log4perl> ein, um
mitzuprotokollieren. Voreingestellt ist das Erstellen der Logs
F<server.log> und F<error.log> in das F<log/> Verzeichnis.

=item share/web/templates

Jifty nutzt L<HTML::Mason> als sein primäres Template System. Legen
Sie die Templates Ihrer Appkikation in F<share/web/templates/>. Von
Haus aus wird Jifty mit einer vordefinierten Applikation geliefert,
die im Verzeichnis F<share/web/templates/> installiert wird. Diese
vordefinierte Applikation ist ein bequemer Weg um eine einfache eigene
Applikation schnell zum Laufen zu bringen, jedoch sind sicher
Anpassungen notwendig, wenn Ihre Applikation komplexer wird.

Sie können schnell herausfinden, wo Jifty seine vordefinierten
Templates ablegt:

  perl -MJifty::Util -e 'print Jifty::Util->share_root'

=item share/web/static

Einige einfache Dinge, die zu Ihrer Applikation gehören, brauchen
nicht (oder I<sollten nicht>) durch das Template-System laufen.

Stecken Sie solche Dateien einfach in das F<share/web/static/>
Verzeichnis und Jifty wird diese verwenden, wenn es nicht gleichzeitig
ein Template mit identischen Namen gibt.

Von Hause aus wird Jifty mit einigen CSS Stilen, JavaScript
Bibliotheken und einem Pony geliefert. Sehen Sie einfach im
Verzeichnis F<share/web/static> der Jifty Distribution nach oder dort
wo Jifty seine Standard-Templates ablegt.

=item lib/MyWeblog

Eine nähere Beschreibung des Objekt Modells und der
Verzeichnishierarchie finden Sie unter L<Jifty::Manual::ObjectModel>

Zum Bau einer funktionsfähigen einfachen Applikation brauchen Sie sich
nur Gedanken über zwei Arten von Klassen, B<Models> und B<Actions> zu
machen.

=item lib/MyWeblog/Model

Die wirkliche Basis Ihrer Applikation lebt in
C<lib/B<AppName>/Model>. Alle Klassen hier definieren die
Daten(bank)strukturen Ihrer Applikation und wie diese miteinander
verbunden sind. Jifty benutzt diese Model-Klassen zum Erstellen oder
Aktualisieren des Datenbank-Schemas, wenn dies notwendig sein sollte.

=item lib/MyWeblog/Action

Als wir gesagt haben, daß Sie sich nur über B<Models> und B<Actions>
den Kopf zerbrechen müssen, haben wir nicht die ganze Wahrheit
gesagt. Jifty kümmert sich um grundlegende Datenbank Interaktionen
(C<CREATE (Anlegen), READ (Lesen), UPDATE (Aktualisieren), DELETE
(Löschen)>). Entsprechend benötigte B<Actions> werden für die
jeweiligen B<Models> automatisch erzeugt und können jederzeit
verändert werden, sollte dies notwendig werden.

=item t

Jifty legt bereits Test-Routinen für Ihre Applikation an, kann
allerdings nicht die Tests für Sie schreiben. (Es erstellt jedoch
einfache Tests für die Model-Klassen, die Sie anlegen.)

=item var

Jifty speichert Cache-Dateien hier, während der Server
läuft. Normalerweise werden Sie hier nichts tun müssen.

=back

=head2 Erstellung eines Datenmodells

Wie Sie sich aus der Tatsache, daß diese Tutorial-Applikation
B<MyWeblog> heißt, vorstellen können, ist das hier vorgestellte
Beispiel ein einfaches Weblog. Künftige Tutorials werden
Authentifizierung, Kommentare sowie RSS und Atom Feeds beschreiben.

=head3 Posts

Weblogs konzentrieren sich rund um Posts, daher ist es keine
Überraschung, daß unser erstes Model, das wir erzeugen werden, ein
C<Post> ist.

  # cd MyWeblog
  # jifty model --name Post
  Writing file /tmp/MyWeblog/t/00-model-Post.t
  Writing file /tmp/MyWeblog/lib/MyWeblog/Model/Post.pm

Großartig! Nun haben Sie ein B<Post> Model (Nur, daß es im Augenblick
noch nichts modelliert).

Öffnen Sie F<lib/MyWeblog/Model/Post.pm> in Ihrem Lieblings-Editor.

Sie sollten etwas sehen wie:

  use strict;
  use warnings;
  
  package MyWeblog::Model::Post;
  use Jifty::DBI::Schema;
  
  use MyWeblog::Record schema {
  
  };
  
  # Your model-specific methods go here.
  
  1;

Nun ist es an der Zeit, der Model Klasse etwas über Posts zu
erzählen. Fangen wir damit an, einem Post einen C<body> (Rumpf) und
einen C<title> (Titel) zu geben. (In einem kommenden Tutorial wird die
Applikation voll "Folksonomy"-tauglich werden, was wir durch Anfügen
einer C<category> (Kategorie) und Erweitern der C<category> zu einer
C<tags> (Indexierung, Etikett) Tabelle erreichen könnten.)

Editieren Sie unter dieser Zeile:

  use MyWeblog::Record schema {

Fügen Sie diese Zeilen an:

  column title =>
        type is 'text',
        label is 'Title',
        default is 'Ohne Titel';

  column body => 
        type is 'text',
        label is 'Content',
        render_as 'Textarea';

Abspeichern bitte nicht vergessen.

=head2 Erstellung der Datenbank

Gut. Nun ist es an der Zeit, die Datenbank zu erstellen. Standardgemäß
benutzt Jifty eine SQLite Datenbank. Wenn Sie lieber PostgreSQL oder
MySQL verwenden möchten, dann können Sie Anpassungen an
F<etc/jifty.yml> vornehmen. (Sehen Sie dazu in C<Jifty::Config> nach,
um mehr darüber zu erfahren.)

  # jifty schema --setup
  INFO - Generating SQL for application MyWeblog...
  INFO - Using MyWeblog::Model::Post
  INFO - Using Jifty::Model::Session
  INFO - Using Jifty::Model::Metadata
  INFO - Using Jifty::Model::Schema
  INFO - Set up version v0.0.1, jifty version 0.607280

=head2 Start des Jifty Application Server

OK. Nun haben Sie eine lauffähige, aber noch einfache
Applikation. Starten Sie den Webserver und schauen Sie sich um. Werfen
Sie einen Blick auf die AJAX gesteuerte Administrations-Umgebung, die
Online Dokumentation und das Pony.

  # ./bin/jifty server
  INFO - You can connect to your server at http://localhost:8888/

Starten Sie diese Kommandofolge immer im Hauptverzeichnis Ihrer Jifty
Applikation, andernfalls werden etliche Fehlermeldungen die Folge
sein.

Auf den meisten Plattformen wird ein einfaches "jifty server" Kommando
ebenfalls funktionieren. :)

=head2 Erstellung der Benutzeroberfläche

Die Administrations-Umgebung gibt Ihnen zwar alles, was Sie brauchen,
um mit den Daten der Applikation zu arbeiten, ist aber noch lange kein
Weblog.

=head3 Erstellung von Posts

Erstellen Sie eine Seite zum Posten eines neuen Weblog Eintrages:

  # cd share/web/templates/

Erstellen Sie eine neue Datei namens F<post> in Ihrem Editor. Stellen
Sie sicher, daß diese so aussieht:

  <%init>
  my $action = Jifty->web->new_action(class => 'CreatePost');
  </%init>

  <&| /_elements/wrapper, title => "Post Eintrag Erstellen" &>
  <% Jifty->web->form->start() %>
  <% Jifty->web->form->next_page( url => '/') %>
  <% $action->form_field('title') %>
  <% $action->form_field('body') %>
  <% Jifty->web->form->submit( label => 'Post' ) %>
  <% Jifty->web->form->end() %>
  </&>

Ja, dies ist eine Template Datei in L<HTML::Mason> Syntax. Wenn Sie
noch nicht genug über Mason wissen, empfehlen wir dessen Online
Dokumentation für mehr Details. I<Mason Templates> sollten jeweils in
der ersten Spalte der Datei beginnen. Besonders wichtig sind die
C<E<lt>%initE<gt>> und C<E<lt>/%initE<gt>> Blöcke, die unbedingt
lingsbündig geschrieben werden müssen.

=head3 Anzeige

Es ist relativ einfach, eine I<einfache> Auflistung von Einträgen zu
erhalten und ein wenig aufwändiger, eine AJAX gesteuerte seitenweise
Darstellung zu bekommen. Hier beschreiben wir, wie man beides macht;
Sie können entscheiden, welches Ihnen besser gefällt.

(Falls Sie per Kopieren und Einfügen den Beispiel-Code von unten
übertragen, stellen Sie sicher, daß er in einer Spalte erscheint,
ansonsten wird es nicht funktionieren.)

=head4 Der schnelle Weg

Erstellen Sie eine neue Datei F<index.html> im F<share/web/templates>
Verzeichnis in Ihrem Editor. (Der Webserver wird die URL
C</index.html> als die I<Standard> Seite für Ihre Applikation
annehmen.) Befüllen Sie die Datei wie folgt:

  <%init>
  my $posts = MyWeblog::Model::PostCollection->new();
  $posts->unlimit();
  </%init>

  <&| /_elements/wrapper, title => Jifty->config->framework('ApplicationName') &>
  <dl>
  % while (my $post = $posts->next) {
   <dt><% $post->title %></dt>
   <dd><% $post->body %></dd>
  % }
  </dl>
  </&>

(Entfernen Sie die Leerzeichen am Zeilenanfang!)

=head4 Die aufwändige Art, mit der Sie viele coole Dinge bekommen

Die I<aufwändige Art> benutzt eines von Jifty's fortgeschrittenen
Eigenschaften: I<PageRegions> (Seitenbereiche). Diese Bereiche
erlauben Ihrer Applikation einzelne Bestandteile einer Seite
unabhängig voneinander neu zu laden. Das funktioniert sowohl unter
Benutzung von AJAX auf modernen Browsern, als auch mit GET Requests
auf nicht JavaScript fähigen Browsern wie C<lynx>, C<w3m> oder dem
Browser Ihres Handys.

Der Nachteil dieser Methode ist, daß jeder Seiten-Bereich in einer
eigenen I<Fragment> Datei vorliegen muß.

Die aufwändige Art beginnt zunächst genauso wie der schnelle
Weg. Erstellen Sie eine neue Datei mit dem Namen
F<share/web/templates/index.html> in Ihrem Editor. Befüllen Sie die
Datei mit:

  <&| /_elements/wrapper, title => Jifty->config->framework('ApplicationName') &>

  <% Jifty->web->region(name => "myweblog-posts",
                        path => "/fragments/page_of_posts") %>
  </&>

Wenn Sie mitgedacht haben, dann haben Sie bestimmt schon erraten, daß
Sie als nächstes eine Datei
F<share/web/templates/fragments/page_of_posts> mit dem nachfolgenden
Inhalt anlegen dürfen:

  <%args>
  $page => 1
  </%args>
  <%init>
  my $posts = MyWeblog::Model::PostCollection->new();
  $posts->unlimit();
  $posts->set_page_info( current_page => $page,
                         per_page     => 15
                       );
  $m->out("Keine Einträge.") if ($posts->pager->total_entries == 0);

  </%init>
  % if ($posts->pager->last_page > 1) {
     Seite <% $page %> von <% $posts->pager->last_page %>
  % }
  <dl class="list">
  % while (my $post = $posts->next) {
   <dt><% $post->title %></dt>
   <dd><% $post->body %></dd>
  % }
  </dl>

  % if ($posts->pager->previous_page) {
    <% Jifty->web->link( label => "vorherige Seite", onclick => { args => { page => $posts->pager->previous_page } } ) %>
  % }
  % if ($posts->pager->next_page) {
    <% Jifty->web->link( label => "nächste Seite", onclick => { args => { page => $posts->pager->next_page } } ) %>
  % }

Nun starten Sie den Jifty Webserver erneut. Erstellen Sie einen Post
indem Sie die URL C</post> auf Ihrem Webserver anfahren. Erstellen Sie
wenigstens 15 Einträge und beobachten Sie dabei, wie Jifty Ihnen die
AJAX Knöpfe C<vorherige Seite> und C<nächste Seite> erstellt. Schalten
Sie JavaScript aus oder verwenden Sie lynx und beobachten Sie wie AJAX
automatisch zurückfällt zum vollständigen Laden der jeweils neuen
Seite. Alles umsonst. Danke, Jifty!

=head3 Hey, woher kam diese Klasse?

Wenn Sie genau aufgepasst haben, dann haben Sie sich sicher gefragt,
woher die C<MyWeblog::Model::PostCollection> Klasse kam. Es gibt keine
Datei mit dem Namen F<PostCollection.pm>. Jifty setzt
C<Jifty::ClassLoader> ein, um einige Klassen für Sie zu
erstellen. Selbstverständlich könnten Sie das ebenfalls tun. Lesen Sie
unter L<Jifty::ClassLoader> mehr darüber.

=head2 Navigation

Natürlich ist es unschön, sich die URL der Post Seite merken zu
müssen. Um einen B<Post> Eintrag im Menü zu bekommen, müssen Sie die
Standard Menüs überschreiben.

Jifty's I<Standard> Menüs werden durch F<_elements/nav> in den
Standard Applikations Templates (die mit dem Pony) erzeugt. Im
Augenblick bleibt Ihnen nichts anderes übrig, als F<_elements/nav> zu
überschreiben. (Wir arbeiten an Methoden, dies besser zu gestalten.)

Legen Sie innerhalb des Verzeichnisses F<share/web/templates> Ihrer
Applikation ein Verzeichnis F<_elements> an.

  mkdir share/web/templates/_elements

Sie möchten bestimmt mit den normalen Jifty Templates arbeiten, also
müssen wir nur den C<< $top->child( Post... ) >> Teil anfügen.

  cat $(perl -MJifty::Util -e 'print Jifty::Util->share_root' \
    )/web/templates/_elements/nav > share/web/templates/_elements/nav

Ansonsten können Sie innerhalb F<_elements> auch gerne eine neue Datei
namens C<nav> anlegen, die so aussehen könnte:

  <%init>
  my $top = Jifty->web->navigation;
  $top->child( Home => url => "/");
  $top->child( Post => url => "/post",
                       label => "Neuen Eintrag");
  </%init>

Mehr Information über das Menü System können Sie der Dokumentation
unter L<Jifty::Web::Menu> entnehmen.

=head2 Das war's

Das war alles, das Sie benötigen, um anzufangen, Jifty Applikationen
zu erstellen. Wir arbeiten hart daran, Jifty noch einfacher einsetzbar
zu machen und die I<dicken Brocken> dieses Tutorials so bald als
möglich zu vereinfachen.

Bitte nehmen Sie auf der C<jifty-devel> Mailing Liste Kontakt mit uns
auf, wenn Sie Fragen haben, wie man Jifty benutzt oder was Sie
schwierig zu benutzen finden. Dies ist eine Mailing Liste in
englischer Sprache.

=head1 HILFE

=head2 Online Hilfe

Das C<jifty> Kommandozeilen Programm besitzt eine eingebaute Hilfe
Funktion.

  jifty help

  jifty help <kommando>

Wenn Ihr Server mit eingeschaltetem Administrations-Modus arbeitet
(die Konfigurations-Einstellung C<AdminMode> fehlt oder sie ist
ungleich Null), dann können Sie den "Online Docs" Link in Ihrem
Browser benutzen, um eine ausführliche modulweise Dokumentation zu
Jifty zu erhalten.

=head2 Beitreten der Mailing Liste

C<jifty-devel@lists.jifty.org> ist der Ort, an dem wir besprechen, wie
wir Jifty erstellen, was es an Problemen oder Vorschlägen gibt und so
weiter.

Um der Liste beizutreten, senden Sie eine Mail an
C<jifty-devel-subscribe@lists.jifty.org>. Bitte beachten Sie, daß die
Kommunikation in dieser Liste in englischer Sprache geführt wird.

=head2 Unser Wiki

Wir haben ein Wiki! (Tatsächlich ist das Wiki die hauptsächliche
Website von Jifty).

Besuchen Sie uns unter L<http://jifty.org/>, lesen Sie und tragen Sie
etwas bei!

Das Wiki wird von I<Wifty> betrieben, einem Wiki das auf Jifty
basiert. Sein Code ist frei verfügbar in unserem Subversion
Repository.

=head1 FEHLER MELDEN

In dieser frühen Phase von Jifty melden Sie bitte alle Fehler, die
Ihnen auffallen, an C<jifty-devel@lists.jifty.org>.

=head1 KÜNFTIGE TUTORIALS

Künftige Tutorials werden enthalten:

=over 4

=item * Zugangskontrolle und Sicherheit

=item * Erweiterung von Datenmodellen

=item * Umfangreiche Beschreibung des Dispatchers

=item * Einbindung einer Applikation in einen Live Server

=item * Web Services im Detail

=item * Continuations (Fortsetzungen) und deren Einsatz

=item * Anpassungen der Darstellung (Benutzerdefinierte Wrapper und CSS)

=back

=cut
