ZF-7602 - Add documentation on Zend_Paginator Adapter Aggregate feature

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

documentation/manual/en/module_specs/Zend_Paginator-Advanced.xml

@@ -219,6 +219,40 @@ var_dump($paginator->getPageItemCache());
 ]]></programlisting>
         </para>
     </sect2>
+
+    <sect2 id="zend.paginator.advanced.aggregator">
+        <title>Zend_Paginator_AdapterAggregate Interface</title>
+
+        <para>
+            Depending on your application you might want to paginate objects, whose internal data-structure
+            is equal to existing adapters, but you don't want to break up your encapsulation to allow access
+            to this data. In other cases an object might be in a "has-an adapter" relationship, rather than
+            the "is-an adapter" relationsship that <classname>Zend_Paginator_Adapter_Abstract</classname> promotes.
+            For this cases you can use the <classname>Zend_Paginator_AdapterAggregate</classname> interface that
+            behaves much like the <classname>IteratorAggregate</classname> interface of the PHP SPL extension.
+        </para>
+
+        <para>
+            <programlisting language="php"><![CDATA[
+interface Zend_Paginator_AdapterAggregate
+{
+    /**
+     * Return a fully configured Paginator Adapter from this method.
+     *
+     * @return Zend_Paginator_Adapter_Abstract
+     */
+    public function getPaginatorAdapter();
+}
+]]></programlisting>
+        </para>
+
+        <para>
+            The interface is fairly small and only expects you to return an instance of
+            <classname>Zend_Paginator_Adapter_Abstract</classname>. An Adapter Aggregate instance is then
+            recognized by both <code>Zend_Paginator::factory</code> and the constructor of Zend_Paginator and
+            handled accordingly.
+        </para>
+    </sect2>
 </sect1>
 <!--
 vim:se ts=4 sw=4 et: