AJAX-ZOOM - callbacks (event hooks) for developers

As a developer, working with or extending AJAX-ZOOM means that besides API methods you are also using callbacks / hooks / events to trigger your custom JavaScript code just at the right moment.

In this example, you can see all these callbacks triggered and illustrated in a visual console next to the player. You can also see some additional data passed to them, which can be, e.g. various coordinate values, zoom levels and similar. The example also explains how to define your custom callback functions, redefine them, register more than one function for the same callback and get a list of all available callbacks.

About

After initialization of AJAX-ZOOM, all callback functions are accessible over jQuery.axZm.userFunc object, e.g. the reference to "onZoomInClickStart" event is jQuery.axZm.userFunc.onZoomInClickStart. You are able to define, redefine or delete you custom hooks:

				jQuery.axZm.userFunc.onZoomInClickStart = function() {
					// Do something
					console.log('This is a test');
				};

				// delete
				jQuery.axZm.userFunc.onZoomInClickStart = null;
			

Get a list of all available event hooks

Calling jQuery.fn.axZm.getAllCallBackNames() API method will return a list (array) of all callbacks available in AJAX-ZOOM version you are using. Please note that many API methods have callbacks too.

Let us know if you are missing an "event" to place your hook. Mostly we can implement a new callback quickly and without additional costs for the customer.

Arguments passed to the event hook function

The first argument of the callback function is often an object containing information about e.g. click coordinates, viewport and other information. This information might be very useful when you create custom functionality with AJAX-ZOOM.

				jQuery.axZm.userFunc.onZoom = function(info) {
					console.log(info);
				};
			

Return of the callback function

In most cases, the return of your callback function does not matter. However, for e.g. onZoomInClickStart it does.

If onZoomInClickStart returns false, the zoom action cancels. You can grab the "info" object passed to this callback function as an argument, evaluate it and do something else with the data. For example, you can create a hotspot and place it precisely at the spot where the user has clicked on the viewer.

				var checkClickedCoordinates = function(x, y) {
					// do checks, execute your code
					// return true or false
				};

				jQuery.axZm.userFunc.onZoomInClickStart = function(info) {
					// coordinates releated to original image size
					var x = info.viewport.x;
					var y = info.viewport.y;

					return checkClickedCoordinates(x, y);
				};
			

or

				var checkClickedCoordinates = function(data) {
					// do checks, execute your code
					// return true or false
				};

				jQuery.axZm.userFunc.onZoomInClickStart = checkClickedCoordinates;
			

Multiple event hooks

A callback can also be a js object, which contains more than one function. In short, this usually happens when two or more functions for the same event are merged using $.fn.axZm.mergeCallBackObj() API method. It can happen before or after initialization of the AJAX-ZOOM viewer.

To be more precise, AJAX-ZOOM has "wrapper" plugins / extensions you will see in many examples and modules for several CMS / shopping carts. Within these extensions, AJAX-ZOOM may trigger indirectly at a later point of time so that $.axZm.userFunc object with event hooks is not available immediately after the extension initializes. Besides this, we make use of publicly available event hooks in the extensions as well. Therefore, to prevent that same event name is not overwritten, all data including callbacks need to pass through the options of such an extension. In the extension, event hooks merge together using $.fn.axZm.mergeCallBackObj() API.

So once again, as a developer you can submit your custom event hooks when dealing with the extensions as well, but please do it through an option of that extension. If you modify it later, be aware that the event hook may merge into an object containing other functions.

When AJAX-ZOOM is already initialized, you can safely add your callback function like this:

				var anOtherOnZoomFunction = function(info) {
					console.log(info);
				};

				$.axZm.userFunc = $.fn.axZm.mergeCallBackObj($.axZm.userFunc, {
					onZoom: anOtherOnZoomFunction
				});

				// or like this when AJAX-ZOOM is already initialized:
				$.fn.axZm.addCallback('onZoom', anOtherOnZoomFunction);
			

Editing custom event hooks

In most cases, you would put the code logic into your anOtherOnZoom function and would not need to change / replace this callback but merely change the execution of that external function. In case you do, add it like this:

				var anOtherOnZoom = function(info) {
					console.log(info);
				};

				$.axZm.userFunc = $.fn.axZm.mergeCallBackObj($.axZm.userFunc, {
					onZoom: {myOnZoom: anOtherOnZoom}
				});

				// or like this when AJAX-ZOOM is already initialized:
				$.fn.axZm.addCallback('onZoom', {myOnZoom: anOtherOnZoom});

				// and e.g. replace your onZoom callback named myOnZoom like this:
				$.axZm.userFunc.onZoom.myOnZoom = function(info) {
					// do something else
				}
			

The logic of AJAX-ZOOM event hooks is similar to jQuery events handling. In jQuery, when you are adding an event listener to, e.g. a click event, you can name it and unbind later without affecting other event functions. In jQuery, you can do it with bind / unbind or on / off methods.

				// For example
				var myFunction = function() {
					// your code
				};

				// Add myFunction to click event and name it "myHook"
				jQuery(selector).bind('click.myHook', myFunction);

				// Then you can unbind only your function from click event
				jQuery(selector).unbind('click.myHook');

				// When unbinding unnamed click, this will unbind all click events added by jQuery
				jQuery(selector).unbind('click');
			

Load other examples in slider