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 are the html, php, and jsp code examples for the most basic WebRocketX welcome page for dynamic web applications.
Feel free to copy this code for your use. The jsp and php examples are only different in that they use includes to abstract and template
some of the elements. Focus on the html example first to learn and use the jsp and php examples if desired.
A WebRocketX welcome page can be written in any technology that renders HTML such as JSP, ASP, PHP, and even CGI. Since WebRocketX runs
- 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.
- disableNavigation - Set this value to true if you want to use the Webapi as a convenient ajax interface but do not want the page navigation enabled. Defaults to false if not present.
Following, in the body of the HTML page are example header and footer sections and in the center is an example starting target div. This 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. Notice how the id of the target div is repeated in the inline capsule. This is required to make things work. This location can later be used to injected new content, but new content can also be injected anywhere else in the page. Still, keep in mind that the application only maintains a single view stack since there is only one back button in the browser. The view stack does support multiple divs though so it will unwind through multiple div locations, as the user pushes the back button. For more information on the custom attributes that can be used in the capsule see the Meta Capsule page.
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.