Structuring The Welcome Page For A Dynamic Web App
A WebRocketX application runs out of a single page. In order for the framework to do its magic, the user enters into a structured page environment after logging into the application. All subsequent navigation within the application will be done by dynamically delivering content into this structure through asynchronous WebRocketX API calls. Considering all of the things that WebRocketX does, the required elements in its welcome page are really quite minimal.
- Structuring The Welcome Page
Basic Welcome Page
Shown below is the jsp code for the most basic WebRocketX welcome page for dynamic web applications. Feel free to copy this code for your use.
A WebRocketX welcome page can be written in any technology that renders HTML such as JSP, ASP, PHP, and even CGI. Since WebRocketX runs
this website are all in jsp.
- asyncDebugMode - Set to true if running in development mode so that the developer feedback text area is enabled. Set to false when running in production.
- signInPageURI - This is the URI that users will be sent to, as a full page submission, if their session times out. This should always lead to the login page. Servers always return the login page when a users session times out, but in an asynchronous environment we do not want this login page coming in as a sub page HTML injection. Therefore, WebRocketX will detect the login page coming back, from an async call, and route to a full page refresh of the login page. In order for WebRocketX to detect that content is the login page, the login page must contain a div with an id="thisIsTheSignInPage".
- pageLoadTimeStamp - Into this variable should be rendered a unique number that is assigned when the user first enters the system from a login. Often a timestamp down to the millisecond will serve this purpose. WebRocketX will send this value as a parameter every time an asynchronous call is made to the server. The server can then validate this number on every communication and prevent cross site request forgery attacks. WebRocketX will still run even if this value is left blank.
- modalTargetSpacing - This value can be left at the default setting of 10. It specifies the z-index spacing between modal dialog layers.
- staticPage - Set this value to false for dynamic application behavior. Dynamic applications will handle the user navigation as a stack, instead of handling it as a queue as is done in static page mode. Dynamic mode will also enable all of the application targeted method calls and capsule attributes such as callbacks and reloads etc. See the Static App Tutorial for more details on developing and SPSW site.
Following the body of the HTML page is an example target div. This is a location where HTML script can be dynamically included in the page through a WebRocketX call. The id of this location will be referenced in the targetId of the Meta Capsule that the content is delivered in. Notice that this welcome page example is an empty shell so once the framework is entered an async call will need to be made to deliver the first content to the page. WebRocketX also has a mechanism for delivering the welcome page with content already in it. See the Basic Welcome Page With Starting Content example below to see how this is done.
The last section of the page is the communication error alert display. This section provides a mechanism for a popup alert if anything goes wrong during asynchronous communication with the server. The communicationErrorAlertWrapper is required and is configured as hidden so that it will only display when the framework shows it. The alert implements a Modal Capsule. The modal capsule parameters must be present, as do the communicationErrorMessage div and the onclick for hiding it. The layout involving the table etc. is open for editing as this is just look and feel and not integral to the framework.
HTML/JSP Code For The Basic Welcome Page
Basic Welcome Page With Starting Content
The JSP page code below is exactly the same as the code above except that it includes starting content
when the welcome page loads. This enables the framework to be loaded along with content so that an
extra round trip will not need to be made after the WebRocketX framework is loaded.
The target div, for the starting content, is marked with a special class name of "startingTarget". The framework searches for this class name when the application is first loaded and will then register the meta capsule, within it, into the application history stack. Take note how, in this example, the actual content that will be displayed is only the phrase "My Starting Content". The rest of the contents of the of the starting target div setup the metacapsule metadata. The targetId in the metadata must match the id of the enclosing starting target div.