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.
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.
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.

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.
dtInit	none	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 menu item, then call this method before the async request of the first view, to clean up any previous flow stacks.
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.
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.