X hide

Magento Newsletter Popup Developer's Guide & API Reference

From Plumrocket Documentation

You are viewing:  Newsletter-popup-icon-32.png  Newsletter Popup


Display Newsletter Popup Manually

In order to display Newsletter Popup manually you will have to perform the following steps:

Select "Display Popup Method" = "Manually" in your Magento back-end as shown below:

Newsletter popup 1.x devguide 1.jpg

Load" and "Show" newsletter popups using the following JavaScript methods below:

There are two available methods: .load() and .show(). "Load" allows to load newsletter popup content from server in background without displaying it. Then "Show" method will display the popup once its loaded.


Load popup without any arguments. This method is executed automatically when the extension is initialized.

.load([id][, callback ])

Load popup by specified newsletter popup ID. There is no need to check if the popup was already loaded. This method will not load the same popup twice.
You can find popup ID by going to your magento back-end, then Plumrocket -> Newsletter Popup -> Manage Newsletter Popups -> column "ID".

If supplied, the callback is fired once the newsletter popup is loaded. The callback passed to .load() is guaranteed to be executed after the DOM is ready, so this is usually the best place to attach all other events and run other JavaScript code. It is hard to predict the overall load time of the newsletter popup from server and therefore we strongly suggest to use callback function. If the popup is already loaded on page then the callback will be executed immediately.

callback: function([bool status][, bool just_loaded])


status — returns "true", if the popup is available to be displayed, otherwise returns "false".
just_loaded — returns "true", if the popup was just loaded during this function call, otherwise returns "false" if it was previously loaded on page.


Display popup on page after it was loaded with .load() method. It's an easy way to display popup without providing any arguments. If on the same page two popups are loaded - one using automatic "Display Popup Method" (such as "after the time delay" or "when leaving the site") and the second one using the "manual" display method, then the automatically loaded popup will be displayed. If you have loaded two or more popups using "manual" display popup method, then the first loaded popup will be displayed.

.show([id][, callback ])

Display popup by specified newsletter popup ID. This newsletter popup must be previously loaded using .load() method. If popup with different "ID" is currently displayed on page while the .show([id]) is being executed, then the previous popup will be hidden and the requested popup is displayed instead. There is no need to check for overlapping popups.

callback: function([bool status])


status — returns "true", if the popup exists and displayed on page, otherwise returns "false".


Example 1:

Let's load & display newsletter popup with ID=5 and output a message to the Web Console using our callback function:

  1. <script type="text/javascript">
  2. newsletterPopup.load(5, function(status, just_loaded) {
  3.  if (just_loaded) {
  4.  console.log('Well done, Sir. The popup was just loaded.');
  5.  // alert('This is another successful newsletter load message!');
  6.  newsletterPopup.show(5);
  7.  }
  8. }
  9. </script>
Example 2:

Load and display any available newsletter popup. Please note that ".load()" method without arguments is not required, it is executed automatically when the extension is initialized.

  1. <script type="text/javascript">
  2.  newsletterPopup.show();
  3. </script>
Example 3:

Load and display newsletter popup with ID=5 on link click

  1. <script type="text/javascript">
  2.  newsletterPopup.load(5);
  3. </script>
  5. <a href="javascript:void(0);" onclick="return newsletterPopup.show(5)">See Newsletter Popup</a>
Example 4:

In this example we are trying to display any default newsletter popup on page (no matter what ID). If this attempt was unsuccessful, then we will try to load and show popup ID=3.

  1. <script type="text/javascript">
  2.  newsletterPopup.show(function(status) {
  3.  if (status == false) {
  4.  newsletterPopup.load(3, function(status) {
  5.  newsletterPopup.show();
  6.  });
  7.  }
  8.  });
  9. </script>

Display Multi-step Newsletter Popup

In order to display multi-step popups you need to select any popup you've created before, and specify another popup that will be displayed after clicking on the element in its HTML code. In order to perform this, add an attribute with popup ID that needs to be displayed to the element (e.g. button or link) required.

Code Example

You can also use an attribute that records custom subscribers' actions in the History section.

Code Example

Use this attribute with "Cancel" value in order to close the popup and write records to the History section.

Code Example

Description.png Detailed description:
  1. This is an example of the html code in the template of the popup.

1 magento newsletter popup developer guide multi-step-popus.jpg

Disable Newsletter Popup Manually

To disable Newsletter popup manually you need to add this code to XML layout:

<reference name="newsletter.popup">
 <action method="disable" />
Code Example
  1. <catalog_category_default translate="label">
  2.  !!-<reference name="newsletter.popup">-!!
  3.  !!-<action method="disable" />-!!
  4.  !!-</reference>-!!
  5.  ....
  6. </catalog_category_default>

In order to disable Newsletter Popup Extension using controller class, please use the following code:

$newsletterBlock = $this->loadLayout()->getLayout()->getBlock('newsletter.popup');
if ($newsletterBlock) {
Code Example
  1. public function indexAction()
  2. {
  3.  $this->loadLayout();
  4.  $this->getLayout()->getBlock('contactForm')->setFormAction( Mage::getUrl('*/*/post') );
  6.  !!-$newsletterBlock = $this->loadLayout()->getLayout()->getBlock('newsletter.popup');-!!
  7.  !!-if ($newsletterBlock) {-!!
  8.  !!-$newsletterBlock->disable();-!!
  9.  !!-}-!! 
  11.  $this->_initLayoutMessages('customer/session');
  12.  $this->_initLayoutMessages('catalog/session');
  13.  $this->renderLayout();
  14. }

Newsletter Popup Extension for Magento Newsletter Popup Extension for Magento