Structuring The Welcome Page For A Dynamic Web App

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 as javascript in the browser only, the means by which HTML is delivered to the browser from the server is unimportant.

The welcome page starts out with standard HTML header layout, and includes lines loading the javascript library files for Jquery, and WebRocketX. The next section contains some javascript variables required for the WebRocketX framework.

• 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. Some backend frameworks already facilitate this behavior. For example, while using Django this variable should be set as follows:
  var pageLoadTimeStamp = "{{ csrf_token }}";
• pageLoadTimeStampParamName - Allows the developer to configure the parameter name for the CSRF token that is sent to the server. This improvement became high priority to support developers using WebRocketX against a Django backend. Django by default checks a parameter called "csrfmiddlewaretoken", with all POST requests, and will fail the request unless this parameter is sent with the correct value. Django allows the enforcement of the CSRF token to be disabled for each mapping, but this is not recommended because it leaves the web application vulnerable. WebRocketX will still run even if this value is left blank, and even if the variable is missing. An example of using this variable with Django is as follows:
  
  var pageLoadTimeStampParamName="csrfmiddlewaretoken";
• 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.

Next are included the lines that load the javascript and css files for the application. WebRocketX is designed so that all of the applications javascript and css load on the welcome page, since it is a Single Page Application.

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.