Custom Popup HTML Guide

About the custom HTML template

Let’s take a look at the HTML code of a sample custom popup:

<form class="OM-form">
    <div class="OM-box">
        <div class="OM-box-form-line">
            <label>Firstname:</label>
            <input type="text" name="visitor[firstname]" data-error="[ERROR_TEXT]" data-validations="required">
        </div>
        <div class="OM-box-form-line">
            <label>Lastname:</label>
            <input type="text" class="OM-visitor-lastname" data-error="[ERROR_TEXT]" data-validations="required">
        </div>
        <div class="OM-box-form-line">
            <label>Email:</label>
            <input type="text" class="OM-visitor-email" name="visitor[email]" data-error="[ERROR_TEXT]" data-validations="required email">
        </div>
  <div class="OM-box-form-line">
<label>My custom field</label>
<input type="text" name="custom_fields[my_custom_field]">
</div>

<div class="OM-box-form-line">
<input type="hidden" name="custom_fields[hidden_custom]" value="My OptiMonk Campaign">
</div> <!-- 1. Submitting data, then closing the popup --> <div class="OM-box-form-line OM-box-form-line-button"> <input type="submit" class="OM-button OM-submit OM-close" value="[BUTTON_TEXT]"> </div> <!-- 2. Submitting data, then redirecting to another page on the same tab --> <div class="OM-box-form-line OM-box-form-line-button"> <input type="submit" class="OM-button OM-submit OM-redirect" value="[BUTTON_TEXT]" data-redirectUrl="[REDIRECT_URL]"> </div> <!-- 3. Submitting data, then redirecting to another page on a new tab --> <div class="OM-box-form-line OM-box-form-line-button"> <input type="submit" class="OM-button OM-submit OM-redirect-blank" value="[BUTTON_TEXT]" data-redirectUrl="[REDIRECT_URL]"> </div> <!-- 4. Custom behavior --> <div class="OM-box-form-line OM-box-form-line-button"> <a class="OM-popup-button" onclick="onButtonClick()">[BUTTON_TEXT]</a> </div> <!-- 5. Redirect using a link instead of a button --> <div class="OM-box-form-line OM-box-form-line-button"> <a class="OM-button OM-close OM-redirect-blank" href="[REDIRECT_URL]">[BUTTON_TEXT]</a> </div> </div> </form>

You can create custom popups with OptiMonk and the system will interpret the HTML tags and values.

HTML tags and values for OptiMonk forms

Please note, the following rules apply when using HTML tags and values:

  • The input fields you are transmitting to OptiMonk must be contained within a form that uses the form tag and class OM-form. For example: <form class=”OM-form”> ...  </form>
  • Input fields must have a name or class for the data to be transmitted to OptiMonk. For example: name=”visitor[lastname]”, or, class=”OM-visitor-lastname”
  • Input fields also have a validation feature. The data-validation and data-error tags are responsible for this. The value of data-error is the message that will be displayed when incorrect data is entered.

What happens when the form is submitted

You can use different methods for handling what happens when the form is submitted:

  • After the data is transferred, close the popup.
  • After the data is transferred, redirect the visitor to another page, in the same tab. In this case, we have to replace [REDIRECT_URL] with the destination URL.
  • Redirect the visitor as in the previous case, but open the destination URL in a new tab.
  • Use your own custom method for handling form completion.

If you are familiar with JavaScript, you can implement these functions with a few lines of code. However, it’s much easier to handle this functionality with classes. We can use pre-defined classes to assign functions to popup elements, like in the example code above.

Assigning names and classes

Here’s some more guidance on using names and classes to transfer data from your form to OptiMonk. You can use a name or a class to tell OptiMonk what the inputs are in your form.

For example, for the name tag you would use:

    • name="visitor[firstname]"
    • name="visitor[lastname]"
    • name="visitor[email]"

If for some reason you are not able to assign a name property, for example, it is being used for another purpose, you can assign a class to the input instead. For example, for the class tag you would use:

    • class=”OM-visitor-firstname”
    • class=”OM-visitor-lastname”
    • class=”OM-visitor-email”

Custom Fields

To submit information othen than the default visitor data, you have to use custom fields. A custom field input must have a name attribute, which must follow this strict format:

name=”custom_fields[field_name]”

The field name inside the square brackets can be anything, but you should avoid using spaces and special characters. In the above code example, the name of the custom field is "my_custom_field". You can use underscore characters ("my_variable") or hyphens ("my-variable") to separate words in your variable name.

Custom fields can be hidden inputs, but in this case you have to make sure it gets a value. You can assign a static value when creating the form, or use JavaScript to assign a value dynamically.

Using buttons and links

You can add multiple classes to the same button or link. When you do so, the actions will be executed in the following order:

OM-button
IMPORTANT: This class is required for OptiMonk to process any of the further OM classes below.

OM-submit

IMPORTANT: This class is required for the button or link that submits the form and transfers the data to OptiMonk.

If the form tag has an action, and optionally a method attribute, the form can also be submitted to this destination. For example: <form action="[DESTINATION]" method="[METHOD]">, where METHOD can be either post or get.

OM-redirect,  OM-redirect-blank

These classes tell the program to look for a redirect URL. If found, the visitor will be redirected to that URL. 

  • OM-redirect will open the destination in the same tab, navigating the visitor away from the source page
  • OM-redirect-blank will open a new tab to load the page

In case of buttons, the system will look for a URL in the data-redirect-url or data-redirecturl tag, while if the element is a link, it will look for the href attribute first (see case 5. in the code above).

OM-close

If this class is present, the popup will be closed upon clicking on the element.

When not using OM classes, a custom popup's HTML code looks like this:

<form class="OM-form">
    <div class="OM-box">
        <div class="OM-box-form-line">
            <label>Firstname:</label>
            <input type="text" name="visitor[firstname]" data-error="[ERROR_TEXT]" data-validations="required">
        </div>
        <div class="OM-box-form-line">
            <label>Lastname:</label>
            <input type="text" name="visitor[lastname]" data-error="[ERROR_TEXT]" data-validations="required">
        </div>
        <div class="OM-box-form-line">
            <label>Email:</label>
            <input type="text" name="visitor[email]" data-error="[ERROR_TEXT]" data-validations="required email">
        </div>

        <!-- 1. Submitting data, then closing the popup -->
        <div class="OM-box-form-line OM-box-form-line-button">
            <input type="submit" class="OM-popup-button" value="[BUTTON_TEXT]" data-action="closePopup">
        </div>

        <!-- 2. Submitting data, then redirecting to another page -->
        <div class="OM-box-form-line OM-box-form-line-button">
            <input type="submit" class="OM-popup-button" value="[BUTTON_TEXT]" data-action="redirect" data-redirectUrl="[REDIRECT_URL]">
        </div>

        <!-- 3. Custom behavior -->
        <div class="OM-box-form-line OM-box-form-line-button">
            <a class="OM-popup-button" onclick="onButtonClick()">[BUTTON_TEXT]</a>
        </div>
    </div>
</form>

The same rules apply as when using OM classes, but we have to create and place the JavaScript ourselves, and write the selectors for specific elements.

 
Handling conversion with your custom method

JavaScript API
When using custom HTML templates, certain functions and behaviors can be implemented with the help of JavaScript API. Additionally, jQuery functions are also available to use, as the popup's source code contains the jQuery framework. 
The following JavaScript methods are available:

OptiMonk.resize(width, height)
Can be used to resize the iframe containing the popup. Width and height values have to be entered in pixels (px).
OptiMonk.resize('800px', '600px');
OptiMonk.close()
Can be used to close the popup. It hides the iframe and the overlay around the iframe which contains the popup.
OptiMonk.close();
OptiMonk.redirect(url)
Redirects to the URL given as parameter. When used on internal pages, it is enough to provide the relative path to the page. In case of external pages, the protocol also must be provided with the URL.
OptiMonk.redirect('/register'); //For internal page
OptiMonk.redirect('http://www.optimonk.hu/'); //For external page
OptiMonk.markFilled()
Used for marking a specific campaign as filled. This is useful when we don't want the campaign to show up for a certain visitor, e.g. because he already filled the form.
OptiMonk.markFilled();
OptiMonk.validate(form)
Validates the specified form's data based on the data-validations attributes of the inputs. Automatically displays the error message for incorrectly filled inputs. It has one parameter: form: We can specify any form HTML element, jQuery object, or selector.
OptiMonk.validate('#myForm');

OptiMonk.submit(form, callback)
Used for sending the specified form's data to OptiMonk. In this case data handling is performed the same way as for other templates: visitor data will be added to the internal database and and also to the integration we previously set on the admin page. Has two paramters: form: Can be any form HTML element, jQuery object or selector. When left blank, the system uses the '.OM-form:first' selector to locate the form. callback: Can be any valid JavaScript function. The function is executed after the AJAX call ends. When left blank, the OptiMonk.markFilled method is called automatically. If we override the basic behavior, we have to make sure the OptiMonk.markFilled method is called in the callback function we specify.

OptiMonk.submit();
OptiMonk.submit(
    '#myForm',
    function () {
        myFunction(); // custom JavaScript
        OptiMonk.markFilled();
        OptiMonk.close();
    });
);

OptiMonk.convert(data, callback)
JavaScript objects can be sent to Optimonk with this function. In this case data handling is performed the same way as for other templates: visitor data will be added to the internal database and and also to the integration we previously set on the admin page. Has two parameters: data: JavaScript object. When left blank, only the conversion will be submitted, without visitor data. callback: Can be any valid JavaScript function. The function is executed after the AJAX call ends. When left blank, the OptiMonk.markFilled method is called automatically. If we override the basic behavior, we have to make sure the OptiMonk.markFilled method is called in the callback function we specify.

OptiMonk.convert(); // Report the conversion, and mark the campaign as filled in the callback method.
OptiMonk.convert(
    {visitor:{firstname: 'NameOfVisitor'}},
    function () {
        myFunction(); // custom JavaScript
        OptiMonk.markFilled();
        OptiMonk.close();
});

Built-in variables
When handling conversion with your own custom method, there are certain built-in OptiMonk variables you can use in JavaScript. You can use these to store more information on your users.

OptiMonk.Vars.campaignId – Contains the ID of the campaign the current popup belongs to.

OptiMonk.Vars.parentUrl – Contains the URL of the site the current popup appears on. The popup is in an iFrame, which has its own URL, therefore you cannot use the document.URL command inside the JavaScript of the popup to get the URL of the current site. For this reason you have to use the OptiMonk.Vars.parentUrl variable.

Examples

Request: When the button is clicked, I would like the popup to close and never show up again.
In this case the conversion will not show in the statistics on the admin site. The following JavaScript code has to be added:

<script>
    function onButtonClick () {
        OptiMonk.markFilled();
        OptiMonk.close();
    }
</script>

Request: When the button is clicked, I would like to redirect the visitor here: http://www.example.com. Also the campaign should not be displayed again.

In this case the conversion will not show in the statistics on the admin site. The following JavaScript code has to be added:

<script>
    function onButtonClick () {
        OptiMonk.markFilled();
        OptiMonk.redirect('http://www.example.com');
    }
</script>

Request: After the popup has been filled, I would like to send the data to OptiMonk, then close the popup.
In this case the conversion is reported, so it will show up in the statistics on the admin site. The following JavaScript code has to be added:

<script>
    function onButtonClick () {
        var form = $('.OM-form:first');
        if (OptiMonk.validate(form)) {
            OptiMonk.submit(
                form,
                function () {
                    OptiMonk.markFilled();
                    OptiMonk.close();
                }
            );
        }
    }
</script>

Request: After the popup has been filled, I would like to send the data to OptiMonk, then redirect the visitor to this URL: http://www.example.com.
The following JavaScript code has to be added:

<script>
    function onButtonClick () {
        var form = $('.OM-form:first');
        if (OptiMonk.validate(form)) {
            OptiMonk.submit(
                form,
                function () {
                    OptiMonk.markFilled();
                    OptiMonk.redirect('http://www.example.com');
                }
            );
        }
    }
</script>

Request: The are no inputs on my popup, I just want to redirect the visitor. I would also like this to show up in the statistics on the admin site.
The following JavaScript code has to be added:

<script>
    function onButtonClick () {
        OptiMonk.convert({}, function () {
            OptiMonk.markFilled();
            OptiMonk.redirect('http://www.example.com');
        });
    }
</script>

Request: I would like to open the page in a new tab, instead of just redirecting the visitor.
The HTML code of the button has to be modified like this:

<div class="OM-box-form-line OM-box-form-line-button">
    <a href="http://www.example.com" target="_blank" onclick="onButtonClick()">[BUTTON_TEXT]</a>
</div>


Additionally, the following JavaScript code has to be added:

<script>
    function onButtonClick () {
        OptiMonk.convert({}, function () {
            OptiMonk.markFilled();
            OptiMonk.close();
        });
    }
</script>

Request: I would like to send visitor data to my own system.
The following JavaScript code has to be added:

<script>
    function onButtonClick () {
        var form = $('.OM-form:first');
        if (OptiMonk.validate(form)) {
            //Submitting to external system
            $.ajax({
                type: 'POST',
                url: 'http://www.example.com/subscribe',
                data: {
                    firstname: form.find('input[name="visitor[firstname]"]').val(),
                    lastname: form.find('input[name="visitor[lastname]"]').val(),
                    email: form.find('input[name="visitor[email]"]').val()
                },
                dataType: 'json',
                success: function (response) {
                    //If successful, we also send it to OptiMonk
                    OptiMonk.submit(
                        form,
                        function () {
                            OptiMonk.markFilled();
                            OptiMonk.close();
                        }
                    );
                }
            });
        }
    }
</script>

 
Have more questions? Submit a request

Comments

Powered by Zendesk