<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15854 -->
<!-- Reviewed: no -->
<sect1 id="zend.feed.importing">

    <title>Feeds importieren</title>

    <para>
        <classname>Zend_Feed</classname> ermöglicht es Entwicklern, Feeds sehr einfach abzurufen.
        Wenn Du die URI eines Feeds kennst, verwende einfach die
        <classname>Zend_Feed::import()</classname> Methode:
    </para>

    <programlisting language="php"><![CDATA[
$feed = Zend_Feed::import('http://feeds.example.com/feedName');
]]></programlisting>

    <para>
        Du kannst <classname>Zend_Feed</classname> außerdem verwenden, um Inhalte eines Feeds aus
        einer Datei oder die Inhalte aus einem PHP String Variable zu abzurufen.
    </para>

    <programlisting language="php"><![CDATA[
// Feeds von einer Textdatei importieren
$feedFromFile = Zend_Feed::importFile('feed.xml');

// Feeds von einer PHP String Variable importieren
$feedFromPHP = Zend_Feed::importString($feedString);
]]></programlisting>

    <para>
        In jedem der obigen Beispiele wird bei Erfolg abhängig vom Typ des Feeds ein Objekt einer
        Klasse zurück gegeben, welche <classname>Zend_Feed_Abstract</classname> erweitert. Wird ein
        RSS Feed durch eine der obigen Importiermethoden abgerufen, wird eine
        <classname>Zend_Feed_Rss</classname> Objekt zurückgegeben. Auf der anderen Seite wird beim
        Importieren eines Atom Feeds ein <classname>Zend_Feed_Atom</classname> Objekt zurückgegeben.
        Bei Fehlern, wie z.B. ein unlesbarer oder nicht wohlgeformter Feed, werfen die
        Importiermethoden auch ein <classname>Zend_Feed_Exception</classname> Objekt.
    </para>

    <sect2 id="zend.feed.importing.custom">

        <title>Eigene Feeds</title>

        <para>
            <classname>Zend_Feed</classname> ermöglicht es Entwicklern Ihre eigenen Feeds sehr
            einfach zu erstellen. Man muß nur ein Array erstellen und es in
            <classname>Zend_Feed</classname> importieren, Dieses Array kann mit
            <classname>Zend_Feed::importArray()</classname> oder mit
            <classname>Zend_Feed::importBuilder()</classname> importiert werden. Im letzteren Fall
            wird das Array on the Fly durch eine eigene Datenquelle berechnet die
            <classname>Zend_Feed_Builder_Interface</classname> implementiert.
        </para>

        <sect3 id="zend.feed.importing.custom.importarray">

            <title>Importieren eines eigenen Arrays</title>

            <programlisting language="php"><![CDATA[
// Importieren eines Feeds von einem Array
$atomFeedFromArray = Zend_Feed::importArray($array);

// Die folgende Zeile ist identisch mit der obigen; standardmäßig
// wird eine Zend_Feed_Atom Instanz zurückgegeben
$atomFeedFromArray = Zend_Feed::importArray($array, 'atom');

// Importieren eines RSS Feeds von einem Array
$rssFeedFromArray = Zend_Feed::importArray($array, 'rss');
]]></programlisting>

            <para>
                Das Format des Arrays muß dieser Struktur entsprechen:
            </para>

            <programlisting language="php"><![CDATA[
array(
    // benötigt
    'title' => 'Titel des Feeds',
    'link'  => 'Kanonische URL zu dem Feed',

    // optional
    'lastUpdate' => 'Zeitstempel des Update Datums',
    'published'  => 'Zeitstempel des Veröffentlichungs Datums',

    // benötigt
    'charset' => 'Zeichensatz der textuellen Daten',

    //optional
    'description' => 'Kurzbeschreibung des Feeds',
    'author'      => 'Author, Veröffentlicher des Feeds',
    'email'       => 'Email des Authors',

    // optional, ignoriert wenn Atom verwendet wird
    'webmaster' => 'Email Adresse der Person die für technische '
                .  'Belange verantwortlich ist',

    //optional
    'copyright' => 'Copyright Notiz',
    'image'     => 'URL zu Bildern',
    'generator' => 'Ersteller',
    'language'  => 'Sprache in der der Feed geschrieben ist',

    // optional, ignoriert wenn Atom verwendet wird
    'ttl'    => 'Wie lange ein Feed gecached werden kann '
             .  'bevor er erneut werden muß',
    'rating' => 'Die PICS Rate dieses Kanals',

    // optional, ignoriert wenn Atom verwendet wird
    // eine Wolke die über Updates benachrichtigt wird
    'cloud' => array(
        // benötigt
        'domain' => 'Domain der Wolke, e.g. rpc.sys.com',

        // optional, Standard ist 80
        'port' => 'Port zu dem verbunden wird',

        // benötigt
        'path'              => 'Pfad der Wolke, e.g. /RPC2',
        'registerProcedure' => 'Prozedur die aufgerufen wird, '
                            .  'z.B. myCloud.rssPleaseNotify'
        'protocol'          => 'Protokoll das verwendet wird, z.B. '
                            .  'soap oder xml-rpc'
    ),

    // optional, ignoriert wenn Atom verwendet wird
    // Eine Texteingabebox die im Feed angezeigt werden kann
    'textInput' => array(
        // benötigt
        'title'       => 'Die Überschrift des Senden Buttons im '
                      .  'Texteingabefeld',
        'description' => 'Beschreibt das Texteingabefeld',
        'name'        => 'Der Name des Text Objekts im '
                      .  'Texteingabefeld',
        'link'        => 'Die URL des CGI Skripts das Texteingabe '
                      .  'Anfragen bearbeitet'
    ),

    // optional, ignoriert wenn Atom verwendet wird
    // Hinweise geben welche Stunden übersprungen werden können
    'skipHours'   => array(
        // bis zu 24 Zeilen dessen Werte eine Nummer zwischen 0 und 23 ist
        // z.B. 13 (1pm)
        'hour in 24 format'
    ),

    // optional, ignoriert wenn Atom verwendet wird
    // Hinweise geben welche Tage übersprungen werden können
    'skipDays '   => array(
        // bis zu 7 Zeilen dessen Werte Montag, Dienstag, Mittwoch,
        // Donnerstag, Freitag, Samstag oder Sonntag sind
        // z.B. Montag
        'a day to skip'
    ),

    // optional, ignoriert wenn Atom verwendet wird
    // Itunes Erweiterungsdaten
    'itunes' => array(
        // optional, Standard ist der Wert der author Spalte
        'author' => 'Musiker Spalte',

        // optional, Standard ist der Wert der author Spalte
        // Eigentümer des Podcasts
        'owner' => array(
            'name'  => 'Name des Eigentümers',
            'email' => 'Email des Eigentümers'
        ),

        // optional, Standard ist der image Wert
        'image' => 'Album/Podcast Bild',

        // optional, Standard ist der description Wert
        'subtitle' => 'Kurzbeschreibung',
        'summary'  => 'Langbeschreibung',

        // optional
        'block' => 'Verhindern das eine Episode erscheint (ja|nein)',

        // benötigt
        // 'Kategoriespalte und iTunes Music Store Browse'
        'category' => array(
            // bis zu 3 Zeilen
            array(
                // benötigt
                'main' => 'Hauptkategorie',

                // optional
                'sub'  => 'Unterkategorie'
            ),
        ),

        // optional
        'explicit'     => 'Elterliche Anweisungsspalte (ja|nein|löschen)',
        'keywords'     => 'Eine kommagetrennte Liste von maximal '
                       .  '12 Schlüsselwörtern',
        'new-feed-url' => 'Verwendet um iTunes über eine neue URL '
                       .  'Lokation zu informieren'
    ),

    'entries' => array(
        array(
            // benötigt
            'title' => 'Titel des Feedeintrags',
            'link'  => 'URL zum Feedeintrag',

            // benötigt, nur Text, kein HTML
            'description'  => 'Kurzversion des Feedeintrags',

            //optional
            'guid' => 'Id des Artikels, wenn nicht angegeben '
                   .  'wird der link Wert verwendet',

            // optional, kann HTML enthalten
            'content' => 'Langversion',

            // optional
            'lastUpdate' => 'Zeitstempel des Veröffnetlichungsdatums',
            'comments'   => 'Kommentarseite des Feedeintrags',
            'commentRss' => 'Die FeedURL der zugehörenden Kommentare',

            // optional, Originale Quelle des Feedeintrags
            'source' => array(
                // benötigt
                'title' => 'Titel der Originalen Quelle',
                'url'   => 'URL der originalen Quelle'
            ),

            // optional, Liste der zugeordneten Kategorien
            'category' => array(
                array(
                    // benötigt
                    'term' => 'Überschrift der ersten Kategorie',

                    // optional
                    'scheme' => 'URL die das Kategorisierungsschema '
                             .  'identifiziert'
                ),

                array(
                    //Daten der zweiten Kategorie und so weiter
                )
            ),

            // optional, Liste der Anhänge des Feedeintrags
            'enclosure' => array(
                array(
                    // benötigt
                    'url' => 'URL des verlinkten Anhangs',

                    // optional
                    'type'   => 'Mime Typ des Anhangs',
                    'length' => 'Länge des verlinkten Inhalts oktal'
                ),

                array(
                    // Daten für den zweiten Anhang und so weiter
                )
            )
        ),

        array(
            // Daten für den zweiten Eintrag und so weiter
        )
    )
);
]]></programlisting>

            <para>
                Referenzen:
                <itemizedlist>
                    <listitem>
                        <para>
                            RSS 2.0 Spezifikation: <ulink
                                url="http://blogs.law.harvard.edu/tech/rss">RSS 2.0</ulink>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Atom Spezifikation: <ulink url="http://tools.ietf.org/html/rfc4287">RFC
                                4287</ulink>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            WFW Spezifikation: <ulink
                                url="http://wellformedweb.org/news/wfw_namespace_elements">Gut
                                geformtes Web</ulink>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            iTunes Spezifikation:
                            <ulink
                                url="http://www.apple.com/itunes/store/podcaststechspecs.html">iTunes
                                Technische Spezifikation</ulink>
                        </para>
                    </listitem>
                </itemizedlist>
            </para>

        </sect3>

        <sect3 id="zend.feed.importing.custom.importbuilder">

            <title>Importieren einer eigenen Daten Quelle</title>

            <para>
                Eine Zend_Feed Instanz kann von jeder Datenquelle erstellt werden die
                <classname>Zend_Feed_Builder_Interface</classname> implementiert. Die
                <code>getHeader()</code> und <code>getEntries()</code> Methoden müssen implementiert
                werden damit das Objekt mit <classname>Zend_Feed::importBuilder()</classname>
                verwendet werden kann. Als einfache Referenz Implementation kann
                <classname>Zend_Feed_Builder</classname> verwendet werden, welches ein Array im
                Kontruktor entgegen nimmt, einige einfache Prüfungen durchführt, und anschließend in
                der <code>importBuilder()</code> Methode verwendet werden kann. Die
                <code>getHeader()</code> Methode muß eine Instanz von
                <classname>Zend_Feed_Builder_Header</classname> zurückgeben, und
                <code>getEntries()</code> muß ein Array von
                <classname>Zend_Feed_Builder_Entry</classname> Instanzen zurückgeben.
            </para>

            <note>
                <para>
                    <classname>Zend_Feed_Builder</classname> arbeitet als konkrete Implementation um
                    die Verwendung zu demonstrieren. Benutzer sind angehlaten Ihre eigenen Klassen
                    zu Erstellen um <classname>Zend_Feed_Builder_Interface</classname> zu
                    implementieren.
                </para>
            </note>

            <para>
                Hier ist ein Beispiel der Verwendung von
                <classname>Zend_Feed::importBuilder()</classname>:
            </para>

            <programlisting language="php"><![CDATA[
// Einen Feed von einer eigenen Erstellungsquelle importieren
$atomFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array));

// Die folgende Zeile ist mit der obigen äquivalent; standardmäßig
// wird eine Zend_Feed_Atom Instanz zurückgegeben
$atomFeedFromArray =
    Zend_Feed::importArray(new Zend_Feed_Builder($array), 'atom');

// Einen RSS Feeed von einem Array von eigenen Erstellungsquellen importieren
$rssFeedFromArray =
    Zend_Feed::importArray(new Zend_Feed_Builder($array), 'rss');
]]></programlisting>

        </sect3>

        <sect3 id="zend.feed.importing.custom.dump">

            <title>Ausgeben des Inhalts eines Feeds</title>

            <para>
                Um den Inhalt einer <classname>Zend_Feed_Abstract</classname> Instanz auszugeben
                können die <code>send()</code> oder <code>saveXml()</code> Methoden verwendet
                werden.
            </para>

            <programlisting language="php"><![CDATA[
assert($feed instanceof Zend_Feed_Abstract);

// Den Feed an der Standardausgabe ausgeben
print $feed->saveXML();

// HTTP Header und den Feed ausgeben
$feed->send();
]]></programlisting>

        </sect3>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->