Custom Event Framework

What is the Custom Event Framework used for?

Much of the code written for ATG Recommendations may not be executed on page load. This code requires other events to occur before it may be executed, and those events often happen asynchronously. One can always write code that polls for conditions but this is inefficient and fragile, especially if many things are polling at once. For this reason, it is important to be able to register event handlers to execute code when the required conditions have been met.

How is the Event Framework used?

There are a number of functions that should be utilized. The developer may check to see if events have occurred, register handlers for events and fire custom events.

• CleverSet.erg.cond(event_name, times_occurred)

  Checks to see if one event has already occurred

Parameters

event_name—the name of the event to check

times_occurred—(optional) if a number is passed, the event must have occurred at least that many times, if true the event must have occurred once

Returns

true if the event whose name is given has occurred at least times_occurred number of times, or once if times_occurred is omitted. False if the event has not occurred enough times.

• CleverSet.erg.gate(condition_hash)

  Checks to see if more than one event has already occurred. Functions the same as cond() but for multiple conditions.

Parameters

condition_hash—a hash of name/value pairs where the name is the event_name to check and the value is the times_occurred as in the cond() function

Returns

true if all of the events meet their conditions, false if one or more do not

• CleverSet.erg.wait(condition_hash, callback_function, callback_parameters, ...)

  Registers a callback function that will execute when a set of conditions is met. Callback functions are executed in the order they were registered.

Parameters

condition_hash—a hash of name/value pairs where the name is the event_name to check and the value is the times_occurred. The same that is used in the gate() function.

callback_function—a function to call when the gate condition_hash is met

callback_parameters—(optional) any other parameters after the callback function will be passed to the callback function if and when it is executed

Returns

Void—registers the callback_function to execute asynchronously

• CleverSet.erg.occur(event_name)

  Fires an event with the given name. Any listening functions will be executed immediately before the function returns.

Parameters

event_name—name of the event that has occurred

Returns

the number of times the event has occurred

Examples

You have a function that you only want to execute once a certain part of your renderer has injected a <div> tag. You can use the Event Framework to handle this case.

First you will want to check to see if the event has already happened, and if it hasn’t you’ll want to add the function as an event handler.

if ( CleverSet.erg.cond('div_injected') ) {
  my_function_to_run('my parameters are boring');
} else {
  CleverSet.erg.wait({div_injected: true}, my_function_to_run, 'my parameters are boring');
}

Then, in your renderer, once you’ve injected the <div> tag you will need to fire the event.

CleverSet.erg.occur('div_injected');

But Wait! You have two recommendation slots on the page and you have another function you want to execute once the div has been injected twice, plus your other function has been run. You’ll need to make your check a little more complex.

if ( CleverSet.erg.gate({div_injected: 2, other_function_happened: true}) ) {
  another_function_to_run();
} else {
  CleverSet.erg.wait({div_injected: 2, other_function_happened: true}, another_function_to_run);
}

And in your other function you’ll need to fire the other event.

CleverSet.erg.occur('other_function_happened');

Once all conditions have been met the another_function_to_run() function will be executed.

What events are available out of the box?

Apart from any events the developer may add, there are number of events that may occur as part of the ATG Recommendations service.

Event Name	Description
renderer_<name>_loaded	A renderer has finished loading. The name of the renderer is substituted for <name>.
rbldr_<name>_loaded	A recommendation builder has finished loading. The name of the recommendation builder is substituted for <name>.
ready	The browser has finished parsing the DOM, but the ATG Recommendations JavaScript has not read from it yet.
checkout_ready	The ATG Recommendations JavaScript has read a checkout configuration from the page, but has not operated on that configuration yet.
slot_found	A recommendation slot has been found, but the ATG Recomendations JavaScript has not yet read its configuration.
failover_started	The failover timer for recommendations has been started and the request to the ATG Recommendations service is about to be sent.
checkout	A checkout transaction is about to be sent to the ATG Recommendations service.
render	Recommendations have been returned, either by the ATG Recommendations service or by the failover service. They have not yet been processed nor displayed.
failover_cancelled	Recommendations have been returned by the ATG Recommendations service and the failover service has been cancelled. The recommendations have not yet been processed nor displayed.
rendered	Recommendations have been inserted into the page DOM by a renderer, but have not been displayed yet. CleverSet.REC_DATA and CleverSet.REC_IDS are set.