EKM Tag Documentation - ekm:newsletter

This tag is used to output an ekmResponse sign up form on your EKM shop.

You must enable the "ekmResponse" feature on your EKM before this tag will output.

Tag Information
Styles
Nesting This Tag
Using Callbacks

Basic Use

In its basic use the tag will display the newsletter signup field with one of the predefined styles.


[ekm:newsletter]style='1';[/ekm:newsletter]

This outputs the following.

Advanced Use

The advanced use of the tag allows you to specify your own HTML and layout for the newsletter tag including showing additional fields


[ekm:newsletter]
    output_start='';
    output_item='[first_name][last_name][email][signup_button]';
    output_end='';
    textbox_attribute='maxlength="1000"';
    firstname_textbox_attribute='value="First Name" class="newsletter-text hide"';
    lastname_textbox_attribute='value="Last Name" class="newsletter-text hide"';
    email_textbox_attribute='value="Email Address" class="newsletter-text"';
    signupbutton_attribute='';
    signupbutton_image='';
[/ekm:newsletter]

Tag Attributes

Style

style='1';

Define the layout for the newsletter signup to be displayed. View All Styles Here

Value

Description

Uses layout 1 from the predefined styles. View Styles

Uses layout 2 from the predefined styles. View Styles

Uses layout 3 from the predefined styles. View Styles

Uses layout 4 from the predefined styles. View Styles

Output Start

output_start='<div id="newsletter">';

Specify any HTML or Text you want to output before the newsletter fields. This will only be output if the newsletter feature is enabled. Typically here you would output any opening HTML tags and headers.

Value

Description

{user defined}

Specify any custom HTML or text to output.

Output Item

output_item='[email][signup_button]';

Specify the layout for the form's content. Here you can insert HTML or Text to define the layout of the fields and submit button.

Value

Description

{user defined}

Specify your own HTML and Text to be output. You will also need to define the attribute tags for the fields.

To output the newsletter fields, including additional fields like First and Last name you need to include attribute tags within the output item.

Value

Description

[first_name]

Outputs the field for first name.

[first_name-name]

Outputs the name of the first name field. This is the name of the input box.

[last_name]

Outputs the field for last name.

[last_name-name]

Outputs the name of the last name field. This is the name of the input box.

[email]

Outputs the field for email address.

[email-name]

Outputs the name of the email address field. This is the name of the input box.

[signup_button]

Outputs the signup button.

[signup_button-name]

Outputs the name of the signup button.

Output End

output_end='</div>';

Specify any HTML or Text you would like to output when the newsletter form has finished outputting. Typically here you would close any opened divs from the output_start attribute.

Value

Description

{user defined}

Specify any HTML or Text to be output.

Text Field Attributes

textbox_attribute='maxlength="1000"';

Specify any input HTML attributes you would like to apply to the text fields. This will affect the first name, last name and email address.

Value

Description

{user defined}

Specify any HTML attributes to output

First Name Field Attributes

firstname_textbox_attribute='value="First Name"';

Specify any input HTML attributes you would like to apply to only the first name field.

Value

Description

{user defined}

Specify any HTML attributes to output on this field.

Last Name Field Attributes

lastname_textbox_attribute='value="Last Name"';

Specify any input HTML attributes you would like to apply to only the last name field.

Value

Description

{user defined}

Specify any HTML attributes to output on this field.

Email Field Attributes

email_textbox_attribute='value="Email Address"';

Specify any input HTML attributes you would like to apply to only the email address field.

Value

Description

{user defined}

Specify any HTML attributes to output on this field.

Signup Button Attributes

signupbutton_attribute='';

Specify any input HTML attributes you would like to apply to only the signup button.

Value

Description

{user defined}

Specify any HTML attributes to output on this button.

Signup Button Image

signupbutton_image='/ekmps/shops/mytestshop/resources/Design/signup-button.png';

Specify a path to any image you wish to use as the button.

Value

Description

{user defined}

Specify any image path.

Callback: Submit

on_submit='functionName';

These are for advanced use only, see Callback documentation for further information.

Specify the name of a Javascript function with global scope to be called when the user submits the newsletter signup.

Value

Description

{user defined}

Specify the name of any javascript function.

Callback: Success

on_success='functionName';

These are for advanced use only, see Callback documentation for further information.

Specify the name of a Javascript function with global scope to be called when the user submits the newsletter signup and receives success.

Value

Description

{user defined}

Specify the name of any javascript function.

Callback: Failure

on_failure='functionName';

These are for advanced use only, see Callback documentation for further information.

Specify the name of a Javascript function with global scope to be called when the user submits the newsletter signup and receives a failure.

Value

Description

{user defined}

Specify the name of any javascript function.

This tag has a number of predefined layout styles. Below are examples for each of the styles and how they will look on your website.

STYLE 1

When the newsletter tag is set to style 1 the form style will output like the example below.


[ekm:newsletter]style='1';[/ekm:newsletter]

This would output something like...

STYLE 2

When the newsletter tag is set to style 2 the form style will output like the example below.


[ekm:newsletter]style='2';[/ekm:newsletter]

This would output something like...

STYLE 3

When the newsletter tag is set to style 3 the form style will output like the example below.


[ekm:newsletter]style='3';[/ekm:newsletter]

This would output something like...

STYLE 4

When the newsletter tag is set to style 4 the form style will output like the example below.


[ekm:newsletter]style='4';[/ekm:newsletter]

This would output something like...

The EKM system allows for some tags to be nested within other tags.

This tag cannot be nested within other tags

This section offers documentation on the custom javascript callback responses offered by the newsletter tag. If you do not have a working knowledge of Javascript or Callbacks avoid using these features as it could cause errors and user problems for your site.

Submit Callback

As documented in the attributes, this attribute is used to call a javascript function when the submit/signup button is pressed.


[ekm:newsletter]
    output_item='[first_name][last_name][email][signup_button]';
    on_submit='newsletterSubmit';
[/ekm:newsletter]

This function is passed 3 parameters. These are the values for the first name, last name and email fields. This is useful for validating whether the email address is valid and whether a first name and last name was entered.


<script type="text/javascript">
function newsletterSubmit(email, firstname, lastname){
    if (!firstname || !lastname) { alert('You did not enter a first and last name'); return false;}
    if (!(/.+@.+\..+/).test(email)) { alert('your email address is invalid'); return false;}
    return true;
}
</script>

Success Callback

This function is called when the user is successfully signed up to the newsletter.


[ekm:newsletter]
    output_item='[first_name][last_name][email][signup_button]';
    on_success='newsletterSuccess';
[/ekm:newsletter]

With a success message the function is called with no parameters.


<script type="text/javascript">
function newsletterSuccess(){
    alert('You are signed up!');
}
</script>

Failure Callback

This function is called when the user signup has failed.


[ekm:newsletter]
    output_item='[first_name][last_name][email][signup_button]';
    on_failure='newsletterFailed';
[/ekm:newsletter]

When this function is called a message parameter is passed with information about the error.


<script type="text/javascript">
function newsletterFailed(message){
    alert(message);
}
</script>

EKM Tag: [ekm:newsletter]