Source: VisitorAPI.js

  1. /**
  2. * VisitorAPI.js
  3. *
  4. * Created by Matthias Seemann on 4.01.2013.
  5. * Copyright (c) 2013 Visisoft GbR. All rights reserved.
  6. *
  7. * How to build the documentation with JSDoc3:
  8. * from inside the visitor_api/v2 directory execute the command line:
  9. * jsdoc -d ~/Documents/Projects/yalst/yalst-trunk/Documentation/visitor_api/ api/<wildcard star>*.js ../Readme.md
  10. * JSDoc 3.0 postprocessing:
  11. * in index.html add class="prettyprint" to all <pre> tags which contain code
  12. *
  13. * JSDoc 3.3.0 postprocessing:
  14. * Either
  15. * Include jQuery then fire this script on document ready. The DOM must be loaded in order for the post-processing to have something to act upon. Of course if your target browsers are modern you can use pure JS and not jQuery.
  16. *
  17. * $('code').parent('pre').addClass('prettyprint source linenums');
  18. * window.prettyPrint && prettyPrint();
  19. *
  20. * or
  21. *
  22. * use modified jsdoc/templates/default/tmpl/examples.tmpl + mainpage.tmpl
  23. *
  24. * (see: https://github.com/jsdoc3/jsdoc/pull/424#issuecomment-28893173)
  25. *
  26. * How to change the namespace:
  27. * 1. change 2x in build.js - or use custom build.js file
  28. * 2. change GLOBAL_NAMESPACE in api/configuration.js
  29. * 3. change argument of the outer immediate function here in api/VisitorAPI.js
  30. * 4. change the GLOBAL_NAMESPACE variable in the build.sh script
  31. * 5. collect the Api under the global namespace with r.js (build script is ./build.sh)
  32. *
  33. *
  34. * @overview Documentation of the public yalst Visitor API
  35. * @copyright Visisoft OHG 2013-2014
  36. * @author Matthias Seemann
  37. * @version 2.0
  38. * @license License of the yalst Live Support Tool applies
  39. */
  40. (function(namespaceName){
  41. return define(['underscore', 'api/errorCodes', 'api/configuration', 'api/ManagedError', 'api/operatorAvailability', 'api/startLiveChat', 'api/startControlling', 'api/ChatObserver'],
  42. function(_, ErrorCodes, Configuration, ManagedError, OperatorAvailability, StartLiveChat, startControlling, ChatObserver)
  43. {
  44. /// global namespace LiveSupport is already defined
  45. // in the integration code or in the self-hosted loader 'visitorApiLoader.js'
  46. /// (Re-)define the api root ///
  47. var LiveSupport = window[namespaceName];
  48. if (LiveSupport === undefined)
  49. {
  50. /**
  51. * The yalst namespace
  52. * @namespace LiveSupport
  53. */
  54. LiveSupport = window[namespaceName] = {};
  55. }
  56. if (LiveSupport.VisitorAPI === undefined)
  57. {
  58. /**
  59. * The Visitor API namespace
  60. * @namespace LiveSupport.VisitorAPI
  61. */
  62. LiveSupport.VisitorAPI = {};
  63. }
  64. /// insert the sub-apis
  65. LiveSupport.ManagedError = ManagedError;
  66. LiveSupport.VisitorAPI.ErrorCode = ErrorCodes;
  67. _(LiveSupport.VisitorAPI).extend(Configuration);
  68. _(LiveSupport.VisitorAPI).extend(OperatorAvailability);
  69. _(LiveSupport.VisitorAPI).extend(StartLiveChat);
  70. LiveSupport.VisitorAPI.startControlling = startControlling;
  71. LiveSupport.VisitorAPI.ChatObserver = ChatObserver;
  72. /**
  73. * Signature of the user provided callback function used to deliver the result of
  74. * asynchronous API methods. <br/>
  75. * Callbacks are always executed in a later run of the Javascript event loop like
  76. * in Node's <tt>process.nextTick(callback)</tt> or <tt>setTimeout(callback, 0)</tt>, i.e.
  77. * never immediately or synchronously to the method call.
  78. * @function userCallback
  79. * @param {*|LiveSupport.ManagedError|Error} resultOrError -
  80. * The result of the asynchronous process or an
  81. * API error. If the API call has failed <tt>resultOrError instanceof Error</tt> is true.
  82. */
  83. /// redefine the invoke method to directly execute the method rather than queueing it
  84. /**
  85. * Calls API methods regardless whether the browser has finished loading the API or not.
  86. * It can be used right after the its definition in the Javascript code which loads
  87. * the Visitor API asynchronously into the web page.
  88. * If the API is not yet loaded the calls are FIFO queued and
  89. * invoked right when the API is ready.
  90. * @param {string} method The method name like 'getVersionString'
  91. * @param {array} parameterArray The parameters of the method or an empty array if there are no
  92. * parameters required.
  93. * @param {userCallback=} invocationCallback An optional invocationCallback function
  94. * which receives the result of the immediately and synchronously executed method
  95. * or an error
  96. * @memberof LiveSupport.VisitorAPI
  97. * @example
  98. * LiveSupport.VisitorAPI.invoke('getVersionString', [], function(versionOrError){
  99. * if (versionOrError instanceof Error){
  100. * alert("Error :" + versionOrError.message; + "(#" + versionOrError.number + ")");
  101. * }
  102. * else{
  103. * document.getElementById('apiVersion').innerHTML = "API version:" + versionOrError;
  104. * }
  105. * });
  106. */
  107. LiveSupport.VisitorAPI.invoke = function(method, parameterArray, invocationCallback)
  108. {
  109. if (typeof method != "string")
  110. {
  111. if (typeof invocationCallback == "function")
  112. {
  113. _.defer(_.bind(invocationCallback, null, new ManagedError(ErrorCodes.ParameterTypeError
  114. , "invalid argument: 1 must be string")));
  115. }
  116. return;
  117. }
  118. invocationCallback = invocationCallback || function(){};
  119. if (!(method in LiveSupport.VisitorAPI))
  120. {
  121. _.defer(_.bind(invocationCallback, null
  122. , new ManagedError(ErrorCodes.CallToUndefinedMethod
  123. , "Call to unknown method: " + method)
  124. )
  125. );
  126. }
  127. else
  128. {
  129. _.defer(_.bind(invocationCallback, null,
  130. LiveSupport.VisitorAPI[method].apply(null, parameterArray))
  131. );
  132. }
  133. };
  134. return LiveSupport.VisitorAPI;
  135. }
  136. );
  137. }("LiveSupportDIY"));