Troubleshooting

Before you contact support, read this first!

❗️

Tips for Troubleshooting

1. Turn on Template Hints to quickly find out which template a form block is using.
2. Make sure you reference the correct block in your Layout XML.
3. Always check that the recaptcha block is 'allowed' to display on the form block.

🚧

If you've solved an issue which not on this list, please send us the details of your problem at magento at studioforty9 dot com

1. Using PHP to add the reCAPTCHA block
2. Using reCAPTCHA on the Contact Form on a different CMS Page
3. Using reCAPTCHA widget on other Magento pages
4. Using Ebizmarts_MageMonkey
5. Using Ultimo Theme by Infortis
6. Understanding Configuration Routes
7. Using with Reviews

Using PHP to add the reCAPTCHA block

In certain situations adding the reCAPTCHA block via XML is not possible, in this case, it's usually best to add the block into your template using PHP. For example, under <ul class="form-list"> on the rwd theme review form template (located at: /app/design/frontend/rwd/review/form.phtml) you can just add another item to the list like so:

PHP

<li>
	<?php $recaptcha = $this->getLayout()->createBlock('studioforty9_recaptcha/explicit')->setTemplate('studioforty9/recaptcha/explicit.phtml'); ?>
	<?php $this->setChild('studioforty9.recaptcha.explicit', $recaptcha->setAllow(true)); ?>
	<?php echo $this->getChildHtml('studioforty9.recaptcha.explicit'); ?>
</li>

❗️

Important

You should always create your own version of the template in your custom theme, never hack the core file.

Using reCAPTCHA on the Contact Form on a different CMS Page

Open up the cms page in Magento and go to the Design Tab and paste the following under Layout Update XML:

XML

<reference name="content">
   <block type="core/template" name="contactForm" template="contacts/form.phtml">
     <action method="setFormAction"><value>/contacts/index/post</value></action>
		 <block type="studioforty9_recaptcha/explicit" name="studioforty9.recaptcha.explicit" template="studioforty9/recaptcha/explicit.phtml">
			 <action method="setAllow"><value>true</value></action>
		 </block>
  </block>
</reference>

❗️

Important

Don't use the Magento templating language to insert your form, the recaptcha widget won't display if you do.

Using reCAPTCHA widget on other Magento pages

The reCAPTCHA widget is set up as a Magento Block, if you are trying to display it on a form but it's not showing up, it's typically one of the following:

1. Your custom Layout XML for the recaptcha block is incorrect.
2. Your custom Layout XML is referencing the wrong parent block.
3. You haven't told the block to allow itself to be displayed.
4. You haven't added the call to $this->getChildHtml('studioforty9.recaptcha.explicit') to the template.

We can't possibly know if your XML is incorrect unless we see it, so check you've got something like:

XML

<block type="studioforty9_recaptcha/explicit" name="studioforty9.recaptcha.explicit" template="studioforty9/recaptcha/explicit.phtml">
	<action method="setAllow"><value>true</value></action>
</block>

You also have to know which parent block to include the reCAPTCHA block on, usually that means the block which includes the form.

Out of the box, we set up the reCAPTCHA widget to display on certain pages, product review, send to friend, contacts and customer registration, if you need to include it on a page that isn't one of those then you need to set the 'allow' flag on the block:

XML

<action method="setAllow"><value>true</value></action>

Of course, the widget cannot display at all if you don't tell the template to display it, find the template of the form you want to add reCAPTCHA to and add the following snippet of PHP.

PHP

<?php echo $this->getChildHtml('studioforty9.recaptcha.explicit'); ?>

❗️

Using reCAPTCHA with themes and other extensions

Some extensions out there will completely overwrite layout blocks to suit their own needs, we can't do anything about that, except encourage other extension developers to more be mindful of the Magento community, here are some known conflicts with other vendors.

Using Ebizmarts_MageMonkey

Includes the following XML, which removes the built-in review form:

XML

<review_product_list>
	<reference name="product.info.product_additional_data">
		<remove name="product.review.form"/>
    <block type="ebizmarts_autoresponder/review_form" name="product.review.form.autoresponder" as="review_form"/>
    <block type="page/html_wrapper" name="product.review.form.fields.before" as="form_fields_before" translate="label"/>
    <label>ReviewFormFieldsBefore</label>
    <action method="setMayBeInvisible"><value>1</value></action>
  </reference>
</review_product_list>

You can fix this by replacing it with the following XML.

XML

<review_product_list>
	<reference name="product.info.product_additional_data">
		<remove name="product.review.form"/>
		<block type="ebizmarts_autoresponder/review_form" name="product.review.form.autoresponder" as="review_form">
			<block type="studioforty9_recaptcha/explicit" name="studioforty9.recaptcha.explicit" template="studioforty9/recaptcha/explicit.phtml">
				<action method="setAllow"><value>true</value></action>
			</block>
		</block>
		<block type="page/html_wrapper" name="product.review.form.fields.before" as="form_fields_before" translate="label"/>
		<label>ReviewFormFieldsBefore</label>
  	<action method="setMayBeInvisible"><value>1</value></action>
	</reference>
</review_product_list>

Using Ultimo Theme by Infortis

The review form is included on a tab on the product page with this theme demo. Since we are no longer on the default review page, we have to add some code to Layout XML to get this working, Under <catalog_product_view>, you can add the following in your local.xml file for your theme:

XML

<catalog_product_view>
  <!-- ...more XML above... -->
  <reference name="tabreviews">
    <block type="review/form" name="product.review.form" as="review_form">
      <block type="studioforty9_recaptcha/explicit" name="studioforty9.recaptcha.explicit" template="studioforty9/recaptcha/explicit.phtml">
        <action method="setAllow"><value>true</value></action>
      </block>
      <block type="page/html_wrapper" name="product.review.form.fields.before" as="form_fields_before" translate="label">
        <label>ReviewFormFieldsBefore</label>
        <action method="setMayBeInvisible"><value>1</value></action>
      </block>
    </block>
  </reference>
  <!-- ...more XML below... -->
</catalog_product_view>

Understanding Configuration Routes

Configuration routes are used to determine whether reCaptcha should run a verification check or not. They are simply a route identifier used internally by Magento. For example, a request for a product page in Magento would use the following route identifier: catalog_product_view.

The configuration routes we use for this extension are typically HTTP POST request routes. For instance, when you submit the product review form, it will send a POST request to review_product_post.

In Magento configuration, under System -> Configuration -> Google API -> Google ReCaptcha, you can select Product Review Form. Behind the scenes, that stores the route value review_product_post in the Magento configuration table. When that route is requested, i.e. when someone submits a review, the reCaptcha verification is sent to Google.

Any routes selected in the configuration multi-select are deemed to be 'enabled' and will not process unless the reCaptcha is verified.