Calling The WebRocketX API For Dynamic Web Applications

The Webapi is the primary interface to the WebRocketX framework. All calls to the server should be done through this javascript utility. Every time a new async call is to be made, a new instance of the Webapi utility should be created, because this instance also persists request state information. After instantiation, setters should be called to configure the Webapi followed by the execution of the async call itself.

Following is a basic example of using the Webapi, where a simple callback is defined and no parameters are sent to the server. The injection location of the layout coming back from the server will be determined by the attributes of the Meta Capsule that the content is delivered in.

Here is another example that does not have a callback but where a form is submited to the URL. All of the inputs in the form will be serialized and sent to the specified URL by the utility. Note that once again the developer does not need to place the content coming back as long as the meta attributes, in the capsule, define where the content goes.

Parameters do not have to be present as inputs in a form. They can also be set by javascript from any source available as shown in the below example. The AsyncParametersList utility takes care of URI encoding the parameters.

Method Name	Parameters	Description
addTagIdToHideDuringProgress	1) Id of tag (String)	If a part of the page is to be hidden during the async call, then add its id to a list by calling this method. Can be called multiple times to add multiple items. Rarely needed.
addTagIdToShowDuringProgress	1) Id of tag (String)	By default the framework shows an hourglass or similar "spinner" during an async call but if an additional part of the page is to be shown, then add its id to a list by calling this method. Can be called multiple times to add multiple items. Since showy spinners are generally not good form, this function should only be used if the call will take an unusually long time and the developer is concerned about the user giving up on the call.
setClearBackStack	1) Enabled (boolean true or false)	Set to true to clear the history of DOM injections after the async call is successful. Default is false. Rarely needed. Only made available for a small number of special cases.
setDisableSendingCsrfToken	1) disabled (default is false)	Allows the developer to disable the sending of the CSRF token for a single request. This is useful if the developer has read only content that they want to cache across server side sessions where the extra security of a CSRF token is not necessary. By not sending the CSRF token the parameters can be same across sessions and allow caching to occur. Use this setting along with setUseGetRequest to implement caching.
setFailureCallbackReference	1) callback function handle	Sets the developer defined function that will be called when the async call is completed but fails. Rarely needed because the framework already takes care of the cleanup on failure. Only made available for a small number of special cases.
setSilentMode	1) Enabled (boolean true or false)	Set to true to enable silent mode. Default is false. Silent mode will disable user interaction control, progress indicators, and error display. Rarely needed.
setSuccessCallbackReference	1) callback function handle	Sets the developer defined function that will be called when the async call is completed successfully.
setUrl	1) URL (String)	Sets the URL that the async call will be sent to.
setUseGetRequest	1) useGet (default is false)	Sets get to be used instead of the default of post. Desireable when wanting to cache views, because post requests will not be cached by the browser. Use along with setDisableSendingCsrfToken so that params do not vary between sessions.
submitAsync	1) no params or 1) AsyncParametersList object	Submits the async call to the server.
submitAsyncForm	1) Name of a form on the page (String)	Submits the async call to the server sending the inputs in a form.
submitAsyncFormMultiPart	1) Name of a form on the page (String)	Submits the async call to the server sending the inputs in a form and any attached files such as images. Makes the request protocol more complex on the server side so only use when needed. Reload is not supported for this method like it is for submitAsyncForm because the file attachments cannot be easily stored in a simple javascript object.
submitReload	1) Capsule Object	Calling this method will reload the capsule sent to it from the server. Sending the capsule object instead of the capsule id might seem odd at first until you realize that this is often called from jsReturn, and jsReturn is supplied the capsule object as its single parameter. When calling this in other contexts the capsule can be retrieved as a div in the DOM by its id and then fed to this function by creating a new Webapi and then calling this function on it with the capsule div object as its input. For example: var myCapsule = domUtil.getElement("myCapsuleId"); var webapi = new Webapi(); webapi.submitReload(myCapsule);

A number of methods are defined outside of the Webapi object, globally available to javascript calls, that allow the developer to interact with the view stack. They are listed below.

Method Name	Parameters	Description
dtBack	none	Calling this method will pop the view stack and display the previously injected view. Putting this method under an onclick in a hyperlink will have the same effect as pushing the back button on the browser.
dtCloseUntrackedModal	none	Developer can close an untracked modal and land on the page behind it, even if the page behind it is untracked, this way the untracked page is not skipped over. Handy for untracked popups in front of untracked pages. Error page modals are now handled by the framework as untracked so this method is necessary on the okay or close button for your server side error page modals to close them. If previously using dtBack on server side error modals, then change your code to use this method instead for proper behavior.
dtInit	1) Call back function	Call this method to clear the view stack. This is most useful when starting a new user interface flow. For example, if starting a new flow from a main menu item, then call this method before the async request of the first view, to clean up any previous flow stacks. The clearing of the stack is done asychronously and part of this process is the rolling back of the browser address bar programatically. Since this rolling back is done asychronously, any code called immediately after dtInit will be in a race state against the rollback causing unpredictable behavior. Therefore, dtInit now requires a callback for code executed immediately after it to be executed. This callback is safe from the race condition. For example. var initCallBack = function() { var webapi = new Webapi(); webapi.setUrl("mycall.go"); webapi.submitAsync(); }; dtInit(initCallBack); // do not put any code here
dtSetCapsuleById	1) capsuleId	Call this method to jump to any previous views. All views visited after that view will be popped off the stack. If the view was marked as reload, then a fresh view will be requested from the server automatically, otherwise the view will come from the javascript cache. If the view is not being reloaded then the jsReturn method will be called if specified.
getStaticContent	1) name of html page	This is a convenience method used to wrap the following calls. var webapi = new Webapi(); webapi.setUrl(fileName); webapi.submitAsync(); It can only be used while running in static web application mode meaning that the staticPage global variable is set equal to true. An example of using this method is given below. Note that this method returns false from the onclick method which will bypass the execution of the reference in the href attribute. Even though the href is not used it is recommended that the bookmark reference to this page be correctly coded as shown so that if by chance any search engine spider records it, then it will record the correct entry path to your page from outside.
removeCapsuleFromHistory	1) capsuleId	Handy to surgically remove a create page from the stack after creation so that back button will not land on a filled out form after creating something. This technique can be done instead of marking the create page as untracked.
restoreAsyncResponse	1) capsuleId	Used to refresh a view to the way it looked coming from the server before any editing was done by the user, without contacting the server. The capsule storing this view must currently be visible, not hidden in the stack, and must have been marked with the meta attribute saveResponse being equal to true. This functionality is most useful in the implementation of a cancel button, because the user can modify a user interface by entering data and showing and hiding parts of the interface etc. Therefore, the only way to reliably return the interface to its original state is to reinject it.

The following methods are called by the WebRocketX framework but do not have any implementation. They are designed to be implemented by the developer. Declare these methods with the same signature in your own file and reference them after the declaration of the WebRocketX javascript file includes. An example of how you would declare your custom applyGlobalJs method is also given below.

Method Name	Parameters	Description
applyGlobalJs	domObject	This method is called on the body load event of the welcome page and is passed a handle to the body tag as its input parameter. Later, during each injection this method is also called and is passed the handle of the capsule object. Therefore, the developer can implement, inside of this method, whatever logic they intend to process on all DOM objects. The most common use for this method is implementing dynamic styling that cannot be done with a style sheet.
dtNavigationCallback	none	This method is called on every navigation, which means it is called whenever the hash changes. By declaring an overridden version of this method, the developer can execute javascript code that happens on every navigation. The most common use of this method is to clear server side error messages potentially written to the header of the application.