Monitus Public Javascript Library

Monitus Public Javascript Library v1

(available at http://live..monitus.net/scripts/pantry/mmin.php/mui.js?x)

MUI.utilities

MUI.utilities.add_event(element, event type, function, use capture)

Return: (nothing)

Parameters:

element (HTMLElement): element to add an event to.
event type (String): the event to add. (ex: “submit”, &quit;click”, …)
function (Function): the function to run when the event fires.
use capture (Bool): parameter of the same name in the DOM addEventListener function.

Description:

Cross-browser function to attach events to HTML elements.

MUI.utilities.form_inflate(template)

Return: String

Parameters:

template (String): a template string to inflate with form values.

Description:

This function will inflate current form values into the template string. You insert special tokens in the template string, and they will be replaced by the equivalent form field value.
Tokens are delimited by the percentage character (“%”), as such:

The name field value is: %name%

In this case, the token “%name%” will be replaced by the current value of the form field whose ID is “name”.

MUI.utilities.is_landing_page(domains to ignore)

Return: Bool

Parameters:

domains to ignore (Array): list of referrer domains to ignore.

Description:

Tells you if the current page is a landing page. (visitor came form another domain, not in the list of domains to ignore)

MUI.utilities.non_null_string(string, default value=””)

Return: String

Parameters:

string (String): the string to test.
default value (String): default value to return, if “string” is null.

Description:

Function to ensure a string is never null.

MUI.utilities.object_by_name_attribute(tag, object name, root)

Return: HTMLElement | null

Parameters:

tag (String): the tag name to look for. (ex: “input”, “img”, …)
object name (String): the name attribute to look for.
root (Object): the root of the search. Optional. Defaults to document. Version 2

Description:

Look for a particular HTMLElement by “name&quote; attribute.

MUI.utilities.rename_element(element, suffix, deep)

Return: (nothing)

Parameters:

element (HTMLElement): element to rename.
suffix (String): suffix to use for the new name; the new name of the element will be <original name> + suffix.
deep (Bool): rename all the children nodes too?

Description:

This function will change both the name and id attributes of an element and, optionally, its children.

MUI.utilities.wait_object(object name, callback function, callback arguments)

Return: (nothing)

Parameters:

object name (String): the javascript object to wait for.
callback function (Function): a function to call when the object exists.
callback arguments (Array): array of arguments to pass to the callback function.

Description:

Allows you to wait until a particular javascript object has been created on the page. The callback function will be called as soon as the object becomes available.

MUI.ga

MUI.ga.track_event(tracker object, event category, event action, event label=”)

Return: (nothing)

Parameters:

tracker object (GA Tracker): the tracker object to use for event tracking.
event category (String): the event category to send to GA.
event action (String): the event action to send to GA..
event label (String): the event label to send to GA. (optional)

Description:

Easy function to send events to Google Analytics.

MUI.ga.attach_tracking_infodestination object, tracker object, event category, event action, event label=”)

Return: (nothing)

Parameters:

destination object (HTMLElement): the object to attach the event info to.
tracker object (GA Tracker): the tracker object to use for event tracking.
event category (String): the event category to send to GA.
event action (String): the event action to send to GA..
event label (String): the event label to send to GA. (optional)

Description:

Allows you to attach the event information to a particular object, for later use, usually by the MUI.ga.track_event_attached_to_object function.

MUI.ga.track_event_attached_to_object object)

Return: True

Parameters:

object (HTMLElement): the object to which the event info was attached.

Description:

Sends an event to Google analytics, based on the info attached to the object by the MUI.ga.track_event_attached_to_object function.

MUI.ga.append_queued_variables tracker object)

Parameters:

tracker object (GA Tracker Object): the tracker object to append the custom variables to.

Description:

This is the function that actually adds all the custom variables queued by the “MUI.ga.track_event_attached_to_object” function.
For more information on custom variable, please refer to GA’s documentation.

MUI.ga.queue_custom_variable slot, name, value, scope)

Parameters:

slot (Number): the slot to use for this variable.
name (String): the name of the variable sent to GA.
value (String): the value of the variable.
scope (Constant): the scope of this variable: MUI.ga.kvariable_scope_visitor, MUI.ga.kvariable_scope_session or MUI.ga.kvariable_scope_page

Description:

Custom variables need to be sent with the initial pageview sent to GA. Because the tracking object might not exist when you have the custom variable data ready, you use this function to “queue” a variable’s data so it can be added to the tracking object later.
Note that you should use this in all cases, whether or not the tracking object is ready or not, because the function warn us if two variables of the same scope use the same slot on a page.
For more information on custom variable, please refer to GA’s documentation.

MUI.gwo

MUI.gwo.track_variation_as_event(tracker object, experiment name, variation name)

Return: (nothing)

Parameters:

tracker object (GA Tracker): the tracker object to use for event tracking.
experiment name (String): the experiment’s name – sent as the event’s category
variation name (String): the variation’s name – sent as the event’s action..

Description:

Easy function to send Google Website Optimizer’s shown variations as events to Google Analytics. You would normally place a call to this funciton in each of your variation.

MUI.yahoo

MUI.yahoo.save_referrer_for_redirect() — version 3

Return: (nothing)

Parameters:

Description:

This function allows you to preserve the original referrer when you do a javascript redirect. It sets the “_mrrf” cookie.

Note: This function makes use of cookies, and so it will only work if the redirect is on the same domain.

MUI.yahoo.clear_referrer_for_redirect() — version 3

Return: (nothing)

Parameters:

Description:

This function quite simply clears the cookie used by MUI.yahoo.save_referrer_for_redirect – to be called once you have read and used the “_mrrf” cookie.

MUI.yahoo.create_ga_tracking_object(profile ID, ignored referrers=null) — version 2

Return: GA Tracker

Parameters:

profile ID (String): the GA profile to use for the tracking object. (UA-xxxxxx-x)
ignored referrers (Array of strings): Referring domains to ignore, i.e. referrals from these domains are considered as coming from the same domain as the current page.

Description:

This function allows you to get a Monitus-compatible GA tracker. This needs to be used instead of the usual var pageTracker = _gat._getTracker(…); call, and will ensure that the tracking object is commpatible with the Monitus one, so that GA cookies are not corrupt.

The function adds a few referrers to ignore automatically: “paypal.com”, “stores.yahoo.net”, “order.store.yahoo.net”, “search.store.yahoo.com”, “search.store.yahoo.net” and the current page’s domain. So you should only pass additional referrers in the second arguments.

MUI.yahoo.current_page_id()

Return: (String)

Parameters: (none)

Description:

Will returned a standardized page identifier for the current page. On the store, it will either be the product ID or “homepage”. On the Checkout, it will be the value of the “sectionId” parameter: ysco.cart, ysco.review, etc…

MUI.yahoo.cleanup_order_data()

Return: (nothing)

Parameters: (none)

Description:

On the order confirmation page, Yahoo! provides javascript arrays with detials of the current order. However, if an item was ordered twice with different options, Yahoo!’s arrays will show two lines with the same product ID. And since options are not considered in these arrays, that does not make much sense: a blue square box, as far as these arrays are concerned, should be the very same as a pink square box – if both have the same product ID.
So this function creates new arrays and merges lines with the same product ID and price, adding quantities to produce the new item’s quantity. The new arrays are:
mon_order_ids
mon_order_items
mon_order_codes
mon_order_price
mon_order_qtys

MUI.yahoo.install_track_cart_update(tracker object, event action=’Update Cart’, event label=”, event category=’Checkout Button Clicked’ )

Return: (nothing)

Parameters:

tracker object (GA Tracker): the tracker object to use for event tracking.
event action (String): the event’s action
event label (String): the event’s label.
event category (String): the event’s category.

Description:

Attaches an event tracker to the “Update” button in the checkout cart page. Sends an event to GA when the button is clicked.

MUI.yahoo.install_track_ship_update(tracker object, event action=’Update Shipping – <page ID> page’, event label='<zip code> – <state> – <shipping method>’, event category=’Checkout Button Clicked’ )

Return: (nothing)

Parameters:

tracker object (GA Tracker): the tracker object to use for event tracking.
event action (String): the event’s action
event label (String): the event’s label.
event category (String): the event’s category.

Description:

Attaches an event tracker to the Shipping Calculator button on the checkout. Sends an event to GA when the button is clicked.

MUI.yahoo.track_add_to_cart(tracker object, event action='<page ID>’, event label=”, event category=’Add to cart’)

Return: True

Parameters:

tracker object (GA Tracker): the tracker object to use for event tracking.
event action (String): the event’s action
event label (String): the event’s label.
event category (String): the event’s category.

Description:

To be used in an “onclick” function for the “Add to cart” button. Sends an event to GA when called.

MUI.yahoo.track_click_to_enlarge(tracker object, event action=’clicked’, event label='<page ID>’, event category=’Click to enlarge’ )

Return: True

Parameters:

tracker object (GA Tracker): the tracker object to use for event tracking.
event action (String): the event’s action
event label (String): the event’s label.
event category (String): the event’s category.

Description:

To be used in an “onclick” function for a “Click to enlarge” button. Sends an event to GA when called.

MUI.yahoo.checkout_button_image_swap(image name, new image URL)

Return: (nothing)

Parameters:

image name (String): the name of the input (type “button”) whose image will be swapped.
new image URL (String): the URL (absolute or relative) of the new image to swap on the button.

Description:

Allows swapping image type input’s image for a new one; particularely useful on the checkout.

MUI.yahoo.checkout_button_caption_swap(button name, new caption)

Return: (nothing)

Parameters:

button name (String): the name of the input (type “submit”) whose caption will be swapped.
new caption (String): the new caption for the button.

Description:

Allows swapping submit type input’s caption for a new one; particularely useful on the checkout.

MUI.yahoo.checkout_move_subsection(subsection ID, new section ID, position)

Return: (nothing)

Parameters:

subsection ID (String): the ID of the subsection to move.
new section ID (String): the ID of the section in which the subsection will be moved.
position (Integer): the position of the subsection in it’s new parent section. (zero-based)

Description:

Allows moving subsections to another section on the checkout page. The subsection will be added before the subsection at position position.

MUI.yahoo.checkout_create_new_section(placeholder section ID, new section ID, title, subtitle)

Return: (nothing)

Parameters:

placeholder section ID (String): the ID of the section relative to which the new section will be placed.
new section ID (String): the ID of the section to create.
title (String): the title of the new section.
subtitle (String): the title of the new section’s first subsection.

Description:

Allows creating a new section on the checkout page. The new section will be added before the placeholder section.

MUI.yahoo.checkout_create_date_fields_for_field(field ID)

Return: (nothing)

Parameters:

field ID (String): the ID of the field to attach date fields to.

Description:

This function creates 3 fields (MM / DD / YYYY) to enter dates, and will update the original field’s value accordingly. The original field is usually a hidden field.

MUI.yahoo.checkout_duplicate_button(new sibling ID, button ID, insert after)

Return: (nothing)

Parameters:

new sibling ID (String): the ID of new button’s sibling.
button ID (String): the ID of button to duplicate.
insert after (Bool): insert the new button after (True) or before (False) the new sibling?

Description:

Duplicates a checkout button. You can define an optional MUI.community.yahoo.node_duplicated(pNewButton) function to further customize the new button.

MUI.yahoo.checkout_duplicate_field(new sibling ID, original field container ID, original field ID, focus, hide original)

Return: (nothing)

Parameters:

new sibling ID (String): the ID of new field’s sibling.
original field container ID (String): the ID of original field’s container.
original field ID (String): the ID of original field.
focus (Bool): give the new field focus?
hide original (Bool): hide the original version?

Description:

Duplicates a checkout field. You can define an optional MUI.community.yahoo.node_duplicated(pNewField) function to further customize the new field.

MUI.yahoo.checkout_mandatory_to_optional_field(mandatory field container ID, mandatory field ID, default value)

Return: (nothing)

Parameters:

mandatory field container ID (String): the ID of mandatory field’s container.
mandatory field ID (String): the ID of mandatory field.
default value (String): the value to place in the mandatory field, when the optional version is empty.

Description:

This function duplicates the mandatory field and then hides-it. Values entered in the new (optional) field are automatically copied to the (hidden) mandatory field. You need to provide a default value to put in the mandatory version so the form will still validate when the user clears the optional version of the field.

MUI.yahoo.checkout_validation(marking callback, invalid marker callback, failed validation callback, ignored fiield list)

Return: (nothing)

Parameters:

marking callback (Function): a function to define how mandatory fields are marked; by default, a star is put to the left of the field. callback(mandatory field (object), show marker (bool)) – Toggling function: use the second parameter to show or hide the marker.
invalid marker callback (Function): a function to mark fields that failed validation; by default, they are marked with a warning icon. callback(mandatory field (object), valid value? (bool)) – Toggling function: use the second parameter to show or hide the marker.
failed validation callback (Function): a function to let the user know some values did not validate; by default, shows a generic alert message. callback()
ignored fiield list (Array of strings): n array of field names for fields that should not be considered by the validation mechanism; by default, all fields are considered.

Description:

This function installs a validation mechanism on the checkout pages. It will mark required fields, and make sure they are not empty when the user tries to go to the next checkout step. Note that this check, unlike Yahoo!’s implementation, will not reload the page nor will it show the normal Yahoo! error messages.