[1.11] Added docs for TeraWurfl and DeviceAtlas UserAgent adapters

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

documentation/manual/en/manual.xml.in

@@ -1135,6 +1135,16 @@
                     <xi:include href="../en/module_specs/Zend_Http_UserAgent-Features_Wurfl.xml" />
                 </xi:fallback>
             </xi:include>
+            <xi:include href="module_specs/Zend_Http_UserAgent-Features_DeviceAtlas.xml">
+                <xi:fallback>
+                    <xi:include href="../en/module_specs/Zend_Http_UserAgent-Features_DeviceAtlas.xml" />
+                </xi:fallback>
+            </xi:include>
+            <xi:include href="module_specs/Zend_Http_UserAgent-Features_TeraWurfl.xml">
+                <xi:fallback>
+                    <xi:include href="../en/module_specs/Zend_Http_UserAgent-Features_TeraWurfl.xml" />
+                </xi:fallback>
+            </xi:include>
             <xi:include href="module_specs/Zend_Http_UserAgent-Storage.xml">
                 <xi:fallback>
                     <xi:include href="../en/module_specs/Zend_Http_UserAgent-Storage.xml" />

documentation/manual/en/module_specs/Zend_Http_UserAgent-Features_DeviceAtlas.xml

@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect1 id="zend.http.user-agent-features-device-atlas">
+    <title>The DeviceAtlas UserAgent Features Adapter</title>
+
+    <sect2 id="zend.http.user-agent-features-device-atlas.intro">
+        <title>Overview</title>
+
+        <para>
+            <ulink url="http://deviceatlas.com/">DeviceAtlas</ulink> provides a comprehensive mobile
+            device database, in editions ranging from free to enterprise level. The databases
+            provided with all editions utilize the same API, which is shipped as part of the
+            DeviceAtlas offering. This particular features adapter interacts with the DeviceAtlas
+            API in order to return device capabilities.
+        </para>
+    </sect2>
+
+    <sect2 id="zend.http.user-agent-features-device-atlas.quick-start">
+        <title>Quick Start</title>
+
+        <para>
+            You will first need to download the DeviceAtlas PHP API, available via their <ulink
+                url="http://deviceatlas.com/downloads">downloads</ulink> page. Unpack this into your
+            library, and make note of the directory in which it resides.
+        </para>
+
+        <para>
+            From there, you may optionally desire to download one of the DeviceAtlas databases; see
+            their site for details. When you do, make sure you make note of where the data file
+            resides.
+        </para>
+
+        <para>
+            Once you have this information, you may configure
+            <classname>Zend_Http_UserAgent</classname> to utilize it. The easiest way is through
+            your application configuration.
+        </para>
+
+        <programlisting language="ini">
+resources.useragent.deviceatlas.deviceatlas_lib_dir = APPLICATION_PATH "/../library/DeviceAtlas"
+resources.useragent.deviceatlas.deviceatlas_data = APPLICATION_PATH "/../data/DeviceAtlas/json/DeviceAtlas.json
+</programlisting>
+    </sect2>
+
+    <sect2 id="zend.http.user-agent-features-device-atlas.options">
+        <title>Configuration Options</title>
+
+        <variablelist>
+            <title>DeviceAtlas API Options</title>
+
+            <varlistentry>
+                <term>deviceatlas.deviceatlas_lib_dir</term>
+
+                <listitem>
+                    <para>
+                        If using the DeviceAtlas API, use this key to specify in which directory the
+                        library exists. If the <classname>Mobi_Mtld_DA_Api</classname> class is
+                        autoloadable, you may omit this setting.
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>deviceatlas.deviceatlas_data</term>
+
+                <listitem>
+                    <para>
+                        If using the DeviceAtlas API, use this key to specify the location of the
+                        data file you will use.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </sect2>
+
+    <sect2 id="zend.http.user-agent-features-device-atlas.methods">
+        <title>Available Methods</title>
+
+        <variablelist>
+            <varlistentry id="zend.http.user-agent-features-device-atlas.methods.get-from-request">
+                <term>
+                    <methodsynopsis>
+                        <methodname>getFromRequest</methodname>
+                        <methodparam>
+                            <funcparams>array $request, array $config</funcparams>
+                        </methodparam>
+                    </methodsynopsis>
+                </term>
+
+                <listitem>
+                    <para>
+                        Decompose the request in order to return an array of device capabilities.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </sect2>
+</sect1>

documentation/manual/en/module_specs/Zend_Http_UserAgent-Features_TeraWurfl.xml

@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect1 id="zend.http.user-agent-features-tera-wurfl">
+    <title>The TeraWurfl UserAgent Features Adapter</title>
+
+    <sect2 id="zend.http.user-agent-features-tera-wurfl.intro">
+        <title>Overview</title>
+
+        <para>
+            <ulink url="">TeraWurfl</ulink> parses the <link
+                linkend="zend.http.user-agent-features-wurfl">WURFL</link> database into a MySQL
+            database, and provides an API for querying that database for mobile device capabilies.
+            The API also performs rigorous caching, leading to excellent performance.
+        </para>
+    </sect2>
+
+    <sect2 id="zend.http.user-agent-features-tera-wurfl.quick-start">
+        <title>Quick Start</title>
+
+        <para>
+            You will need to <ulink
+                url="http://www.tera-wurfl.com/wiki/index.php/Downloads">download</ulink> and <ulink
+                url="http://www.tera-wurfl.com/wiki/index.php/Installation">install</ulink>
+            TeraWurfl. Make a note of where you install the library
+            (<filename>TeraWurfl.php</filename>); we recommend installing it in your application's
+            <filename>library</filename> directory.
+        </para>
+
+        <para>
+            Once installed, the easiest way to use TeraWurfl is to configure it via the application
+            resource.
+        </para>
+
+        <programlisting language="ini">
+resources.useragent.terawurfl.terawurfl_lib_dir = APPLICATION_PATH "/../library/"
+</programlisting>
+
+        <para>
+            If the file is autoloadable, you can also specify an empty configuration in order to
+            utilize the adapter.
+        </para>
+
+        <programlisting language="ini">
+resources.useragent.terawurfl[] = 
+</programlisting>
+    </sect2>
+
+    <sect2 id="zend.http.user-agent-features-tera-wurfl.options">
+        <title>Configuration Options</title>
+
+        <variablelist>
+            <title>TeraWurfl API Options</title>
+
+            <varlistentry>
+                <term>terawurfl.terawurfl_lib_dir</term>
+
+                <listitem>
+                    <para>
+                        If using the TeraWurfl API, use this key to specify in which
+                        directory the <filename>TeraWurfl.php</filename> file exists.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </sect2>
+
+    <sect2 id="zend.http.user-agent-features-tera-wurfl.methods">
+        <title>Available Methods</title>
+
+        <variablelist>
+            <varlistentry id="zend.http.user-agent-features-tera-wurfl.methods.get-from-request">
+                <term>
+                    <methodsynopsis>
+                        <methodname>getFromRequest</methodname>
+                        <methodparam>
+                            <funcparams>array $request, array $config</funcparams>
+                        </methodparam>
+                    </methodsynopsis>
+                </term>
+
+                <listitem>
+                    <para>
+                        Decompose the request in order to return an array of device capabilities.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </sect2>
+</sect1>

documentation/manual/en/module_specs/Zend_Http_UserAgent.xml

@@ -75,13 +75,38 @@
 
         <para>
             At the time of this writing, The <classname>UserAgent</classname> component provides
-            only a single features adapter, one that consumes the <ulink
-                url="http://wurfl.sourceforge.net/">WURFL</ulink> (Wireless Universal Resource File)
-            PHP API. This database is considered one of the most comprehensive mobile device
-            databases, and coupled with the <classname>UserAgent</classname> component can provide
-            you with all the tools you need to write applications targetting mobile devices with
-            Zend Framework.
+            three adapters:
         </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <link
+                        linkend="zend.http.user-agent-features-wurfl">Zend_Http_UserAgent_Features_Adapter_Wurfl</link>
+                    consumes the <ulink url="http://wurfl.sourceforge.net/">WURFL</ulink> (Wireless
+                    Universal Resource File) PHP API. This database is considered one of the most
+                    comprehensive mobile device capabilities databases available.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <link
+                        linkend="zend.http.user-agent-features-tera-wurfl">Zend_Http_UserAgent_Features_Adapter_TeraWurfl</link>
+                    consumes the TeraWurfl API, which is built on top of <acronym>WURFL</acronym>,
+                    and aimed at providing a highly available, highly performant lookup mechanism.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <link
+                        linkend="zend.http.user-agent-features-device-atlas">Zend_Http_UserAgent_Features_Adapter_DeviceAtlas</link>
+                    consumes the DeviceAtlas API, which is a paid, Enterprise-grade mobile device
+                    capabilities database.
+                </para>
+            </listitem>
+        </itemizedlist>
     </sect2>
 
     <sect2 id="zend.http.user-agent.quick-start">
@@ -232,6 +257,11 @@ $config = array(
 );
 ]]></programlisting>
 
+            <para>
+                Each features adapter has its own options available as well, which may be mixed in
+                with the general UserAgent options.
+            </para>
+
             <varlistentry>
                 <term>browser_type</term>