Calling The WebRocketX API For Dynamic Web Applications
When using WebRocketX the developer will make all of their calls to the server through the Webapi utility.
- Calling The API
Using the Webapi
The Webapi is the primary interface to the WebRocketX framework. All calls to the server should be done
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
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.
Basic Webapi Example with a Callback
Example Of Webapi Form Submission
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.
Example Of Submitting Parameters Without A Form
Parameters do not have to be present as inputs in a form. They can also be set by
utility takes care of URI encoding the parameters.
Full List Of Dynamic Webapi Methods
|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.|
1) no params
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.|
|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:
Global Utility Methods
that allow the developer to interact with the view stack. They are listed below.
|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.
|getStaticContent||1) name of html page||
This is a convenience method used to wrap the following calls.
var webapi = new Webapi();
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.|
Example of using getStaticContent
Global Methods To Override
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
of how you would declare your custom applyGlobalJs method is also given below.
|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.|