The vingd object

Core functionality

class vingd()

A global window.vingd object is created and initialized upon script (main.min.js) load. To create a “popup opener” function object you should use vingd.popupOpener() function, with arguments describing details of a future popup open process.

For example, you can create orderOpener object once, like this:

var orderOpener = new vingd.popupOpener({
    popupURL: "http://example.com/popup.html",
    siteURL: "http://example.com",
    lang: "en",
    onSuccess: function(hwnd, args) {
        window.location = vingd.buildURL("http://example.com/verify.php", {token: args.token});
    }
});

And use it later in your document, while presenting your user with the “buy” option:

<a href="https://www.vingd.com/link/to/your/order" onclick="return orderOpener(this);"> buy </a>

When user clicks the link, a popup window will open (redirect user to order link on Vingd frontend), your page will darken, and user shall be presented with an option of buying your order. Upon purchase, popup window will automatically close and your popupParams.onSuccess handler will be called (in the context of your (parent) page - the page that hosted the link, and the vingd object).

vingd.popupOpener(popupParams)

The main library method. It constructs and returns a specialized click-on-link handler function that opens popup, interprets the result and calls your event callbacks.

Arguments:
  • popupParams (object) –

    Behaviour of the constructed handler is defined with the popupParams function argument.

    popupParams.popupURL

    Location of the popup.html file hosted on your server (see Download).

    popupParams.siteURL

    [optional]. Your site’s URL. The user shall be redirected here when she closes the main window, and we don’t know where else to redirect her. The default value is taken from the parent page URL (a page you are calling vingd.popupOpener() from).

    popupParams.lang

    [optional] The language of popup messages (supported values: en, hr). If omitted, the default value is used: vingd.settings.lang (i.e. hr).

    popupParams.onOpen

    [optional]. Callback function called everytime after a popup window is opened and focused. Default handler will call vingd.darkenScreen(). To prevent it, override it with null.

    onOpen()
    popupParams.onClose

    [optional]. Callback function called always as the last heart beat - after popup window is closed. Default handler will call vingd.undarkenScreen(). Override it by providing your function (you can also provide null).

    onClose()
    popupParams.onInit

    [optional]. Callback function called when popup first opened. If you don’t specify your onInit callback, the default handler will redirect user to href property of a source link element, or element.href that you passed to the opener() function.

    Note :You can generate your orders from this callback. Or, more precisely, fetch them (on demand) via AJAX from your backend.
    onInit(hwndPopup, args, onDone)
    Arguments:
    • hwndPopup (object) – reference to a popup window handle
    • args (object) – query arguments
    • onDone(url) (function) – callback function you should call at the end of your (asynchronous) initialization to redirect user to url (typically order purchase URL you fetched with AJAX from your backend).
    popupParams.onSuccess

    [optional]. Callback function called if popup operation (purchase confirmation, voucher redeeming, etc.) finished successfully.

    onSuccess(hwndPopup, args)
    Arguments:
    • hwndPopup (object) – reference to a popup window handle
    • args (object) – query arguments (including purchase verification token object: args.token)
    popupParams.onError

    [optional] Callback function called in the case of Vingd frontend error.

    onError(hwndPopup, args)
    Arguments:
    • hwndPopup (object) – reference to a popup window handle
    • args (string) – query args including message string args.msg, the error message (as received from Vingd frontend)
    popupParams.onCancel

    [optional] Callback function called when user clicks the “Cancel” button on Vingd frontend.

    Note :If user simply closes the popup window, only the popupParams.onClose() will be called.
    onCancel(hwndPopup, args)
    Arguments:
    • hwndPopup (object) – reference to a popup window handle
    • args (object) – query arguments
    popupParams.onExpand

    [optional] Callback function called when user clicks the “Expand this popup” button on Vingd frontend.

    Note :Default handler opens args.expand_url, or if this URL is not not defined (by Vingd frontend), then to the frontendURL parameter.
    onCancel(hwndPopup, args)
    Arguments:
    • hwndPopup (object) – reference to a popup window handle
    • args (object) – query arguments
    popupParams.frontendURL

    [optional]. The address of Vingd frontend used in a certain error scenarios (zombie popups, malformed extend actions, etc.). The default value is: vingd.settings.frontendURL. You never have to override it (except when you’re hosting a local Vingd frontend).

    popupParams.width

    [optional] Width of popup window in pixels (as integer). If omitted, the default value is used: vingd.settings.width.

    popupParams.height

    [optional] Height of popup window in pixels (as integer). If omitted, the default value is used: vingd.settings.height.

Returns function:
 
opener([element])

You should use the returned function object to initiate purchase confirmation (or voucher redeeming or Vingd OAuth login) when user clicks your “purchase/redeem/login” link.

The only required propery of the popupParams object is the popupParams.popupURL. Note however, that your site will seem quite dysfunctional if you also don’t handle at least the onSuccess() event.

The document at popupParams.popupURL location must handle the response from Vingd frontend (response is encoded in GET data). You should use the default handler supplied with the library, popup.html (see Download). The default handler will call your on... callbacks, it will handler error scenarios, zombie popup mode (when user closes the main/site/parent window/tab), and several other dirty details.

vingd.popupCloser(window)

Handles popup closing process. Depending on the result of popup operation, user-defined callbacks are executed (within a context of popup opener window).

Arguments:

Return values from Vingd frontend are used to call this popup’s event callback functions: onSuccess(), onCancel(), onError() and onExpand():

  • On successful operation (purchase/voucher redeem/login): popupParams.onSuccess function is called. args.token can then be used to verify the purchase in backend via AJAX.
  • Upon user clicking “Cancel” button while on Vingd frontend, the popupParams.onCancel function is executed.
  • In case of an error, the popupParams.onError handler is called, receiving error description as an argument (args.msg).
  • When user requests popup expansion, while on Vingd frontend, the popupParams.onExpand function is called (in a context of parent window) to be able to close the popup window and then open the requested page in parent window. The requested page URL is propagated thru args.expand_url GET parameter.

When appropriate handler is finished executing, this function closes the popup, which in turn triggers calling of popupParams.onClose handler from within vingd.closeListener internal method. (Note: problems have been reported for some Safari versions that do not handle delayed function execution properly.)

Simple utility functions

vingd.darkenScreen()

A utility method, usually used in onOpen handler, that darkens the screen by overlaying it with a semi-transparent black layer. To use, ensure that no screen element has a z-index at or above 10000. This layer can be suppressed using the vingd.undarkenScreen().

vingd.undarkenScreen()

A utility method, usually used in onClose handler, that undarkens the screen (see vingd.darkenScreen()).

vingd.buildURL(base, params)

A utility function for building a valid URL given base URL and query parameters in a dictionary (JavaScript object).

vingd.getURLQueryArgs(query)

A utility function for parsing URL GET parameters given a query string (eg. window.location.search).

Callback handlers storage facility

When a new popup window is opened, its description is stored inside an object pushed into an array. This is done transparently and automatically with the ‘pushWindowData’ function (upon opening the popup).

Popup description includes all event callback function references.

To retrieve a popup data (for example to execute some of the previously defined event handlers), the vingd.getWindowData() function can be used.

vingd.pushWindowData(hWnd, params, callbacks)

Stores event handlers (callbacks) and Vingd frontend parameters for a popup referenced by a window handle hWnd.

vingd.getWindowData(hWnd[, dequeue])

Retrieves popup data (including callbacks) for a window referenced by hWnd. To delete popup data, set dequeue to true.

Table Of Contents

Previous topic

Download

Next topic

Change log

This Page