Added docs for the Zend_Service_ReCaptcha_MailHide component

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

documentation/manual/en/module_specs/Zend_Service-ReCaptcha.xml

@@ -35,18 +35,24 @@
             your public and private keys:
         </para>
 
-        <programlisting language="php"><![CDATA[
+        <example id="zend.service.recaptcha.example-1">
+            <title>Creating an instance of the ReCaptcha service</title>
+            <programlisting language="php"><![CDATA[
 $recaptcha = new Zend_Service_ReCaptcha($pubKey, $privKey);
 ]]></programlisting>
+        </example>
 
         <para>
             To render the reCAPTCHA, simply call the <methodname>getHTML()</methodname>
             method:
         </para>
 
-        <programlisting language="php"><![CDATA[
+        <example id="zend.service.recaptcha.example-2">
+            <title>Displaying the ReCaptcha</title>
+            <programlisting language="php"><![CDATA[
 echo $recaptcha->getHTML();
 ]]></programlisting>
+        </example>
 
         <para>
             When the form is submitted, you should receive two fields,
@@ -54,12 +60,15 @@ echo $recaptcha->getHTML();
             these to the ReCaptcha object's <methodname>verify()</methodname> method:
         </para>
 
-        <programlisting language="php"><![CDATA[
+        <example id="zend.service.recaptcha.example-3">
+            <title>Verifying the form fields</title>
+            <programlisting language="php"><![CDATA[
 $result = $recaptcha->verify(
     $_POST['recaptcha_challenge_field'],
     $_POST['recaptcha_response_field']
 );
 ]]></programlisting>
+        </example>
 
         <para>
             Once you have the result, test against it to see if it is valid. The
@@ -67,11 +76,14 @@ $result = $recaptcha->verify(
             which provides an <methodname>isValid()</methodname> method.
         </para>
 
-        <programlisting language="php"><![CDATA[
+        <example id="zend.service.recaptcha.example-4">
+            <title>Validating the ReCaptcha</title>
+            <programlisting language="php"><![CDATA[
 if (!$result->isValid()) {
     // Failed validation
 }
 ]]></programlisting>
+        </example>
 
         <para>
             Even simpler is to use <link
@@ -83,6 +95,118 @@ if (!$result->isValid()) {
             validating the reCAPTCHA are automated for you.
         </para>
     </sect2>
+    
+    <sect2 id="zend.service.recaptcha.mailhide">
+        <title>Hiding email addresses</title>
+        
+        <para>
+            <classname>Zend_Service_ReCaptcha_MailHide</classname> can be used to hide email 
+            addresses. It will replace a part of an email address with a link that opens a popup 
+            window with a ReCaptcha challenge. Solving the challenge will reveal the complete 
+            email address. 
+        </para>
+        <para>
+            In order to use this component you will need 
+            <ulink url="http://recaptcha.net/whyrecaptcha.html">an account</ulink>, and generate 
+            public and private keys for the mailhide API.
+        </para>
+        <example id="zend.service.recaptcha.mailhide.example-1">
+            <title>Using the mail hide component</title>
+            <programlisting language="php"><![CDATA[
+// The mail address we want to hide
+$mail = 'mail@example.com';
+
+// Create an instance of the mailhide component, passing it your public and private keys as well as 
+// the mail address you want to hide
+$mailHide = new Zend_Service_ReCaptcha_Mailhide();
+$mailHide->setPublicKey($pubKey);
+$mailHide->setPrivateKey($privKey);
+$mailHide->setEmail($mail);
+
+// Display it
+print($mailHide);
+]]></programlisting>
+        </example>
+        <para>
+            The example above will display "m...@example.com" where "..." has a link that opens up 
+            a popup windows with a ReCaptcha challenge.
+        </para>
+        <para>
+            The public key, private key and the email address can also be specified in the 
+            constructor of the class. A fourth argument also exists that enables you to set some
+            options for the component. The available options are listed in the following table:
+            <table id="zend.service.recaptcha.mailhide.options.table">
+                <title>Zend_Service_ReCaptcha_MailHide options</title>
+                <tgroup cols="4">
+                    <thead>
+                        <row>
+                            <entry>Option</entry>
+                            <entry>Description</entry>
+                            <entry>Expected Values</entry>
+                            <entry>Default Value</entry>
+                        </row>
+                    </thead>
+                    <tbody>
+                        <row>
+                            <entry>linkTitle</entry>
+                            <entry>The title attribute of the link</entry>
+                            <entry>string</entry>
+                            <entry>'Reveal this e-mail address'</entry>
+                        </row>
+                        <row>
+                            <entry>linkHiddenText</entry>
+                            <entry>The text that includes the popup link</entry>
+                            <entry>string</entry>
+                            <entry>'...'</entry>
+                        </row>
+                        <row>
+                            <entry>popupWidth</entry>
+                            <entry>The width of the popup window</entry>
+                            <entry>int</entry>
+                            <entry>500</entry>
+                        </row>
+                        <row>
+                            <entry>popupHeight</entry>
+                            <entry>The height of the popup window</entry>
+                            <entry>int</entry>
+                            <entry>300</entry>
+                        </row>
+                    </tbody>
+                </tgroup>
+            </table>
+        </para>
+        <para>
+            The configuration options can be set by sending it as the fourth argument to the 
+            constructor or by calling the <methodname>setOptions($options)</methodname> which takes 
+            an associative array or an instance of <link linkend="zend.config">Zend_Config</link>.
+        </para>
+        <example id="zend.service.recaptcha.mailhide.example-2">
+            <title>Generating many hidden email addresses</title>
+            <programlisting language="php"><![CDATA[
+// Create an instance of the mailhide component, passing it your public and private keys as well as 
+// well the mail address you want to hide
+$mailHide = new Zend_Service_ReCaptcha_Mailhide();
+$mailHide->setPublicKey($pubKey);
+$mailHide->setPrivateKey($privKey);
+$mailHide->setOptions(array(
+    'linkTitle' => 'Click me',
+    'linkHiddenText' => '+++++',
+));
+
+// The addresses we want to hide
+$mailAddresses = array(
+    'mail@example.com',
+    'johndoe@example.com',
+    'janedoe@example.com',
+);
+
+foreach ($mailAddresses as $mail) {
+    $mailHide->setEmail($mail);
+    print($mailHide);
+}
+]]></programlisting>
+        </example>
+    </sect2>
 </sect1>
 <!--
 vim:se ts=4 sw=4 et: