Expanded Zend_Feed_Writer docs with full API core list

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@21676 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Feed_Writer.xml

@@ -19,7 +19,7 @@
         <para>
             In many ways, <classname>Zend_Feed_Writer</classname> is the inverse of
             <classname>Zend_Feed_Reader</classname>. Where <classname>Zend_Feed_Reader</classname>
-            focused on providing an easy to use architecture fronted by getter methods,
+            focuses on providing an easy to use architecture fronted by getter methods,
             <classname>Zend_Feed_Writer</classname> is fronted by similarly named setters or
             mutators. This ensures the <acronym>API</acronym> won't pose a learning curve to anyone
             familiar with <classname>Zend_Feed_Reader</classname>.
@@ -27,10 +27,10 @@
 
         <para>
             As a result of this design, the rest may even be obvious. Behind the scenes, data set on
-            any <classname>Zend_Feed_Reader</classname> object is translated at render time onto a
+            any <classname>Zend_Feed_Writer</classname> Data Container object is translated at render time onto a
             DOMDocument object using the necessary feed elements. For each
             supported feed type there is both an Atom 1.0 and <acronym>RSS</acronym> 2.0 renderer.
-            Using a DOMDocument rather a templating solution has numerous advantages,
+            Using a DOMDocument class rather than a templating solution has numerous advantages,
             the most obvious being the ability to export the DOMDocument for
             additional processing and relying on <acronym>PHP</acronym> <acronym>DOM</acronym> for
             correct and valid rendering.
@@ -48,7 +48,7 @@
 
         <para>
             The architecture of <classname>Zend_Feed_Writer</classname> is very simple. It has two
-            core sets of classes: containers and renderers.
+            core sets of classes: data containers and renderers.
         </para>
 
         <para>
@@ -57,20 +57,38 @@
             to any Feed class. The sole purpose of these containers is to collect data about the
             feed to generate using a simple interface of setter methods. These methods perform some
             data validity testing. For example, it will validate any passed <acronym>URI</acronym>s,
-            dates, etc. These checks are not tied to any of the feed standards. The container
+            dates, etc. These checks are not tied to any of the feed standards definitions. The container
             objects also contain methods to allow for fast rendering and export of the final feed,
             and these can be reused at will.
         </para>
+        
+        <para>
+            In addition to the main data container classes, there are two additional Atom 2.0 specific
+            classes. <classname>Zend_Feed_Writer_Source</classname> and <classname>
+            Zend_Feed_Writer_Deleted</classname>. The former implements Atom 2.0 source elements which
+            carry source feed metadata for a specific entry within an aggregate feed (i.e. the current feed
+            is not the entry's original source). The latter implements the Atom Tombstones RFC allowing
+            feeds to carry references to entries which have been deleted.
+        </para>
 
         <para>
-            While there are two data containers, there are four renderers - two matching container
-            renderers per support feed type. The renderer accept a container, and based on its
-            content attempt to generate a valid feed. If the renderer is unable to generate a valid
-            feed, perhaps due to the container missing an obligatory data point, it will report this
+            While there are two main data container types, there are four renderers - two matching container
+            renderers per supported feed type. Each renderer accepts a container, and based on its
+            content attempts to generate valid feed markup. If the renderer is unable to generate valid
+            feed markup, perhaps due to the container missing an obligatory data point, it will report this
             by throwing an <classname>Exception</classname>. While it is possible to ignore
             <classname>Exception</classname>s, this removes the default safeguard of ensuring you
             have sufficient data set to render a wholly valid feed.
         </para>
+        
+        <para>
+            To explain this more clearly, you may construct a set of data containers for a feed where
+            there is a Feed container, into which has been added some Entry containers and a Deleted
+            container. This forms a data hierarchy resembling a normal feed. When rendering is performed,
+            this hierarchy has its pieces passed to relevant renderers and the partial feeds (all DOMDocuments)
+            are then pieced together to create a complete feed. In the case of Source or Deleted (Tomestone)
+            containers, these are rendered only for Atom 2.0 and ignored for RSS.
+        </para>
 
         <para>
             Due to the system being divided between data containers and renderers, it can make
@@ -87,8 +105,9 @@
         <title>Getting Started</title>
 
         <para>
-            Using <classname>Zend_Feed_Reader</classname> is as simple as setting data and
+            Using <classname>Zend_Feed_Writer</classname> is as simple as setting data and
             triggering the renderer. Here is an example to generate a minimal Atom 1.0 feed.
+            As this demonstrates, each feed/entry uses a separate data container.
         </para>
 
         <programlisting language="php"><![CDATA[
@@ -190,7 +209,8 @@ $out = $feed->export('atom');
             present. This gives rise to Exceptions that differ between the two standards depending
             on the renderer in use. By design, <classname>Zend_Feed_Writer</classname> will not
             render an invalid feed for either standard unless the end-user deliberately elects to
-            ignore all Exceptions.
+            ignore all Exceptions. This built in safeguard was added to ensure users without
+            in-depth knowledge of the relevant specifications have a bit less to worry about.
         </para>
     </sect2>
 
@@ -204,12 +224,18 @@ $out = $feed->export('atom');
             <acronym>API</acronym> closely matches that for <classname>Zend_Feed_Reader</classname>
             to avoid undue confusion and uncertainty.
         </para>
-
+        
+        <note>
+            <para>Users have commented that the lack of a simple array based notation for input data
+            gives rise to lengthy tracts of code. This will be addressed in a future release.</para>
+        </note>
+        
         <para>
             <classname>Zend_Feed_Writer</classname> offers this <acronym>API</acronym> via its data
             container classes <classname>Zend_Feed_Writer_Feed</classname> and
-            <classname>Zend_Feed_Writer_Entry</classname>. These classes merely store
-            all feed data in type-agnostic manner, meaning you may reuse any data
+            <classname>Zend_Feed_Writer_Entry</classname> (not to mention the Atom 2.0 specific
+            and Extension classes). These classes merely store
+            all feed data in a type-agnostic manner, meaning you may reuse any data
             container with any renderer without requiring additional work. Both classes
             are also amenable to Extensions, meaning that an Extension may define its own
             container classes which are registered to the base container classes as extensions, and
@@ -226,6 +252,12 @@ $out = $feed->export('atom');
             methods operate at the same level as the Core <acronym>API</acronym> though we do allow
             you to retrieve any specific Extension object separately if required.
         </para>
+        
+        <para>
+            The Feed Level API for data is contained in <classname>Zend_Feed_Writer_Feed</classname>.
+            In addition to the API detailed below, the class also implements the <classname>Countable
+            </classname> and <classname>Iterator</classname> interfaces.
+        </para>
 
         <table>
             <title>Feed Level API Methods</title>
@@ -276,13 +308,12 @@ $out = $feed->export('atom');
                             final <acronym>URI</acronym> allowing a client to track its location
                             changes without necessitating constant redirects. The parameter is an
                             array of arrays, where each sub-array contains the keys "type" and
-                            "uri". The type should be one of "atom", "rss", or "rdf". If a type is
-                            omitted, it defaults to the type used when rendering the feed.
+                            "uri". The type should be one of "atom", "rss", or "rdf".
                         </entry>
                     </row>
 
                     <row>
-                        <entry><methodname>setAuthors()</methodname></entry>
+                        <entry><methodname>addAuthors()</methodname></entry>
 
                         <entry>
                             Sets the data for authors. The parameter is an array of arrays
@@ -296,11 +327,11 @@ $out = $feed->export('atom');
                     </row>
 
                     <row>
-                        <entry><methodname>setAuthor()</methodname></entry>
+                        <entry><methodname>addAuthor()</methodname></entry>
 
                         <entry>
                             Sets the data for a single author following the same
-                            format as described above for a single sub-array.
+                            array format as described above for a single sub-array.
                         </entry>
                     </row>
 
@@ -317,7 +348,7 @@ $out = $feed->export('atom');
                     </row>
 
                     <row>
-                        <entry><methodname>getDateModified()</methodname></entry>
+                        <entry><methodname>setDateModified()</methodname></entry>
 
                         <entry>
                             Sets the date on which this feed was last modified. The expected
@@ -352,7 +383,7 @@ $out = $feed->export('atom');
                     </row>
 
                     <row>
-                        <entry><methodname>setHubs()</methodname></entry>
+                        <entry><methodname>addHubs()</methodname></entry>
 
                         <entry>
                             Accepts an array of Pubsubhubbub Hub Endpoints to be rendered in
@@ -361,26 +392,82 @@ $out = $feed->export('atom');
                             order for real-time updates to be enabled. A Publisher may be
                             implemented using
                             <classname>Zend_Feed_Pubsubhubbub_Publisher</classname>.
+                            The method <methodname>addHub()</methodname> allows adding
+                            a single hub at a time.
                         </entry>
                     </row>
 
                     <row>
-                        <entry><methodname>setCategories()</methodname></entry>
+                        <entry><methodname>addCategories()</methodname></entry>
 
                         <entry>
                             Accepts an array of categories for rendering, where each element is
                             itself an array whose possible keys include "term", "label" and
                             "scheme". The "term" is a typically a category name suitable for
                             inclusion in a <acronym>URI</acronym>. The "label" may be a human
-                            readable category name supporting special characters (it is encoded
+                            readable category name supporting special characters (it is HTML encoded
                             during rendering) and is a required key. The "scheme" (called the domain
                             in <acronym>RSS</acronym>) is optional but must be a valid
                             <acronym>URI</acronym>.
+                            The method <methodname>addCategory()</methodname> allows adding
+                            a single category at a time.
                         </entry>
                     </row>
+                    
+                    <row>
+                        <entry><methodname>createEntry()</methodname></entry>
+                        <entry>Returns a new instance of <classname>Zend_Feed_Writer_Entry
+                        </classname>. This is the Entry level data container. New entries
+                        are not automatically assigned to the current feed, so you
+                        must explicitly call <methodname>addEntry()</methodname>
+                        to add the entry for rendering.</entry>
+                    </row>
+                    
+                    <row>
+                        <entry><methodname>addEntry()</methodname></entry>
+                        <entry>Adds an instance of <classname>Zend_Feed_Writer_Entry
+                        </classname> to the current feed container for rendering.</entry>
+                    </row>
+                    
+                    <row>
+                        <entry><methodname>createTombstone()</methodname></entry>
+                        <entry>Returns a new instance of <classname>Zend_Feed_Writer_Deleted
+                        </classname>. This is the Atom 2.0 Tombstone level data container. New entries
+                        are not automatically assigned to the current feed, so you
+                        must explicitly call <methodname>addTombstone()</methodname>
+                        to add the deleted entry for rendering.</entry>
+                    </row>
+                    
+                    <row>
+                        <entry><methodname>addTombstone()</methodname></entry>
+                        <entry>Adds an instance of <classname>Zend_Feed_Writer_Deleted
+                        </classname> to the current feed container for rendering.</entry>
+                    </row>
+                    
+                    <row>
+                        <entry><methodname>removeEntry()</methodname></entry>
+                        <entry>Accepts a parameter indicating an array index of the
+                        entry to remove from the feed.</entry>
+                    </row>
+                    
+                    <row>
+                        <entry><methodname>export()</methodname></entry>
+                        <entry>Exports the entire data hierarchy to an XML feed. The method
+                        has two parameters. The first is the feed type, one of "atom"
+                        or "rss". The second is an optional boolean to set whether
+                        Exceptions are thrown. The default is TRUE.</entry>
+                    </row>
                 </tbody>
             </tgroup>
         </table>
+        
+        <note>
+            <para>In addition to these setters, there are also matching getters to retrieve data from the
+            Entry data container.</para>
+        </note>
+        
+        <!-- remaining feed stuff -->
+        
     </sect2>
 
     <sect2 id="zend.feed.writer.setting.entry.data.points">
@@ -395,6 +482,10 @@ $out = $feed->export('atom');
             methods operate at the same level as the Core <acronym>API</acronym> though we do allow
             you to retrieve any specific Extension object separately if required.
         </para>
+        
+        <para>
+            The Entry Level API for data is contained in <classname>Zend_Feed_Writer_Entry</classname>.
+        </para>
 
         <table>
             <title>Entry Level API Methods</title>
@@ -405,7 +496,7 @@ $out = $feed->export('atom');
                         <entry><methodname>setId()</methodname></entry>
 
                         <entry>
-                            Set a unique ID associated with this feed. For Atom 1.0
+                            Set a unique ID associated with this entry. For Atom 1.0
                             this is an atom:id element, whereas for <acronym>RSS</acronym> 2.0 it is
                             added as a guid element. These are optional so long as a link is
                             added, i.e. the link is set as the ID.
@@ -414,12 +505,17 @@ $out = $feed->export('atom');
 
                     <row>
                         <entry><methodname>setTitle()</methodname></entry>
-                        <entry>Set the title of the feed.</entry>
+                        <entry>Set the title of the entry.</entry>
                     </row>
 
                     <row>
                         <entry><methodname>setDescription()</methodname></entry>
-                        <entry>Set the text description of the feed.</entry>
+                        <entry>Set the text description of the entry.</entry>
+                    </row>
+                    
+                    <row>
+                        <entry><methodname>setContent()</methodname></entry>
+                        <entry>Set the content of the entry.</entry>
                     </row>
 
                     <row>
@@ -428,9 +524,9 @@ $out = $feed->export('atom');
                         <entry>
                             Set a <acronym>URI</acronym> to the <acronym>HTML</acronym> website
                             containing the same or
-                            similar information as this feed (i.e. if the feed is from a blog,
-                            it should provide the blog's <acronym>URI</acronym> where the
-                            <acronym>HTML</acronym> version of the entries can be read).
+                            similar information as this entry (i.e. if the feed is from a blog,
+                            it should provide the blog article's <acronym>URI</acronym> where the
+                            <acronym>HTML</acronym> version of the entry can be read).
                         </entry>
                     </row>
 
@@ -451,7 +547,7 @@ $out = $feed->export('atom');
                     </row>
 
                     <row>
-                        <entry><methodname>setAuthors()</methodname></entry>
+                        <entry><methodname>addAuthors()</methodname></entry>
 
                         <entry>
                             Sets the data for authors. The parameter is an array of arrays
@@ -465,7 +561,7 @@ $out = $feed->export('atom');
                     </row>
 
                     <row>
-                        <entry><methodname>setAuthor()</methodname></entry>
+                        <entry><methodname>addAuthor()</methodname></entry>
 
                         <entry>
                             Sets the data for a single author following the same
@@ -481,7 +577,8 @@ $out = $feed->export('atom');
                             only applicable to Atom where it represents the date the resource
                             described by an Atom 1.0 document was created. The expected parameter
                             may be a <acronym>UNIX</acronym> timestamp or a
-                            <classname>Zend_Date</classname> object.
+                            <classname>Zend_Date</classname> object. If omitted, the date
+                            used will be the current date and time.
                         </entry>
                     </row>
 
@@ -491,64 +588,84 @@ $out = $feed->export('atom');
                         <entry>
                             Sets the date on which this feed was last modified. The expected
                             parameter may be a <acronym>UNIX</acronym> timestamp or a
-                            <classname>Zend_Date</classname> object.
+                            <classname>Zend_Date</classname> object. If omitted, the date
+                            used will be the current date and time.
                         </entry>
                     </row>
 
                     <row>
-                        <entry><methodname>setLanguage()</methodname></entry>
+                        <entry><methodname>setCopyright()</methodname></entry>
+                        <entry>Sets a copyright notice associated with the feed.</entry>
+                    </row>
+
+                    <row>
+                        <entry><methodname>setCategories()</methodname></entry>
 
                         <entry>
-                            Sets the language of the feed. This will be omitted unless set.
+                            Accepts an array of categories for rendering, where each element is
+                            itself an array whose possible keys include "term", "label" and
+                            "scheme". The "term" is a typically a category name suitable for
+                            inclusion in a <acronym>URI</acronym>. The "label" may be a human
+                            readable category name supporting special characters (it is encoded
+                            during rendering) and is a required key. The "scheme" (called the domain
+                            in <acronym>RSS</acronym>) is optional but must be a valid
+                            <acronym>URI</acronym>.
                         </entry>
                     </row>
-
+                    
                     <row>
-                        <entry><methodname>getGenerator()</methodname></entry>
+                        <entry><methodname>setCommentCount()</methodname></entry>
 
                         <entry>
-                            Allows the setting of a generator. The parameter should be an
-                            array containing the keys "name", "version" and "uri". If omitted
-                            a default generator will be added referencing
-                            <classname>Zend_Feed_Writer</classname>, the current Zend Framework
-                            version and the Framework's <acronym>URI</acronym>.
+                            Sets the number of comments associated with this entry. Rendering
+                            differs between <acronym>RSS</acronym> and Atom 2.0 depending
+                            on the element/attribute needed.
                         </entry>
                     </row>
-
+                    
                     <row>
-                        <entry><methodname>setCopyright()</methodname></entry>
-                        <entry>Sets a copyright notice associated with the feed.</entry>
-                    </row>
+                        <entry><methodname>setCommentLink()</methodname></entry>
 
+                        <entry>
+                            Seta a link to a HTML page containing comments associated with this entry.
+                        </entry>
+                    </row>
+                    
                     <row>
-                        <entry><methodname>setHubs()</methodname></entry>
+                        <entry><methodname>setCommentFeedLink()</methodname></entry>
 
                         <entry>
-                            Accepts an array of Pubsubhubbub Hub Endpoints to be rendered in
-                            the feed as Atom links so that PuSH Subscribers may subscribe to
-                            your feed. Note that you must implement a Pubsubhubbub Publisher in
-                            order for real-time updates to be enabled. A Publisher may be
-                            implemented using
-                            <classname>Zend_Feed_Pubsubhubbub_Publisher</classname>.
+                            Sets a link to a XML feed containing comments associated with this entry.
+                            The parameter is an array containing the keys "uri" and "type", where
+                            the type is one of "rdf", "rss" or "atom".
                         </entry>
                     </row>
+                    
+                    <row>
+                        <entry><methodname>setCommentFeedLinks()</methodname></entry>
 
+                        <entry>
+                            Same as <methodname>setCommentFeedLink()</methodname> except it
+                            accepts an array of arrays, where each subarray contains the
+                            expected parameters of <methodname>setCommentFeedLink()</methodname>.
+                        </entry>
+                    </row>
+                    
                     <row>
-                        <entry><methodname>setCategories()</methodname></entry>
+                        <entry><methodname>setEncoding()</methodname></entry>
 
                         <entry>
-                            Accepts an array of categories for rendering, where each element is
-                            itself an array whose possible keys include "term", "label" and
-                            "scheme". The "term" is a typically a category name suitable for
-                            inclusion in a <acronym>URI</acronym>. The "label" may be a human
-                            readable category name supporting special characters (it is encoded
-                            during rendering) and is a required key. The "scheme" (called the domain
-                            in <acronym>RSS</acronym>) is optional but must be a valid
-                            <acronym>URI</acronym>.
+                            Sets the encoding of entry text. This will default to UTF-8 which
+                            is the preferred encoding.
                         </entry>
                     </row>
                 </tbody>
             </tgroup>
         </table>
+        
+        <note>
+            <para>In addition to these setters, there are also matching getters to retrieve data from the
+            Entry data container.</para>
+        </note>
     </sect2>
 </sect1>