Meta Capsules For Dynamic Web Applications

The use of meta capsules for content delivery lies at the heart of the WebRocketX paradigm. A meta capsule is a div that encloses the incoming content. This div also contains custom attributes, called meta attributes, which give instructions to the WebRocketX framework. Delivering content encapsulated within a meta capsule makes the framework both declarative and component driven.

Simple Meta Capsule Example

Shown here is an example of using a meta capsule. Note how the capsule is a simple outside div with meta attributes and content inside of it. This example capsule only specifies the capsule id for tracking this view, the capsule class, the capsule type, the target div for injection, a js onload function that will be run when injection is complete, and the title to show in the browser. Meta attributes that are not included in the div and are not required will be set to their defaults by the framework.

The capsule class "metaCapsule" is only used by the framework to locate the capsule in the DOM. It servers no other styling purpose. The capsule is designed to be an invisible wrapper for content delivery. It should not be styled to be visible. However, sometimes the capsule div will break the css of the surrounding page hierarchy because it throws an extra div between its children and their parents. Small adjustments to the css can usually be done to fix this.

Keep in mind that a "hook", the jsOnload attribute, to facilitate onloads during injection is necessary because this is a Single Page Application and the body onload event that happened when we entered the application is no longer available for later injections.

Note that, in the example, the html content is in the same file as the capsule. With large layouts, it is recommended that the developer abstract the content to an included file to keep things cleaner, instead of putting the content in the same file as the capsule. Also, use of a meta capsule template will add even more formal structure, which is desireable when applications are built using large teams of developers. An example of that is given further below.

Of course, this is simply html markup so you can do this any way you want. All you need in the end, coming back from an async call, is a div (aka capsule) wrapping your content and the Webapi will do the rest. In the case of this example, the framework will do things in the following order.

Use the innerHTML method to inject the text into the div in your page with an id of "id_of_a_div".
Put a reference to this content in a js stack identified by the id of "helloWorldPage". This page can then be cached by this reference on the browser and therefore navigated to later when it has gone out of sight.
Call the function "myJSFunction()" to do any onload activities on this page.
Set the title on the browser to "My Great Title".

HTML Code For A Simple Meta Capsule

        
        <div id="helloWorldPage" class="metaCapsule" capsuleType="inline" targetId="id_of_a_div" jsOnload="myJSFunction();" windowTitle="My Great Title">
            <h1>Hello World</h1>
            <table>
                <tr>
                    <td>
                       Some content. 
                    </td>
                </tr>
            </table
        </div>

Using a Meta Capsule Template

Given below is an example of a page using a meta capsule template, with all of the settings possible. The use of templates is not required. The capsule div can simply be written in plain text around content if desired instead. Templates just help standardize things. Comments are used to mark which attributes are required and which are optional. Optional settings can actually be left out, and will be defaulted by the framework. This example is given in JSP but any server side technology can be used. The c:set tags used are really just parameters which are fed to the meta capsule template/include. The jsp of the meta capsule template is shown below the usage example.

HTML/JSP Code showing the usage of a Meta Capsule Template

        
        <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
        <%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt" %>
        
        <c:set var="metaCapsuleContent" scope="page">
            This is a table with some content in it.
            <table>
                <tr>
                    <td>
                       Some content. 
                    </td>
                </tr>
            </table> 
        </c:set>
            
        <%-- required --%>
        <c:set var="capsuleId" value="welcome" scope="page"/>            
        <c:set var="capsuleType" value="inline" scope="page"/> <%-- inline, modal, data --%>                        
        <%-- conditionally required --%>
        <c:set var="targetId" value="winMain" scope="page"/> <%-- required for capsuleType of inline --%>            
        <%-- optional --%>
        <c:set var="jsOnload" value="myOnloadMethod()" scope="page"/>
        <c:set var="reloadPage" value="false" scope="page"/>
        <c:set var="skipReloadPageOnPrevious" value="false" scope="page"/>
        <c:set var="saveOriginalRequest" value="false" scope="page"/>
        <c:set var="saveResponse" value="false" scope="page"/>
        <c:set var="trackPage" value="true" scope="page"/>
        <c:set var="windowTitle" value="welcome" scope="page"/>                                                                        
        <c:set var="errorPage" value="false" scope="page"/> 
        <%@ include file="/jsp/capsules/metaCapsule.jsp" %>

Meta Capsule Template

Below is an example of how you could structure your Meta Capsule Template in JSP. Notice how all of the c:set's are initialized after their usage to be on the safe side. This is necessary if another template, like a Modal Capsule Template is used, in conjunction with the Meta Template.

HTML/JSP Code showing a Meta Capsule Template

        
        <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
        <%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt" %>
        
        <div id="${capsuleId}" class="metaCapsule" capsuleType="${capsuleType}" targetId="${targetId}" jsOnload="${jsOnload}" reloadPage="${reloadPage}" skipReloadPageOnPrevious="${skipReloadPageOnPrevious}" saveOriginalRequest="${saveOriginalRequest}" saveResponse="${saveResponse}" trackPage="${trackPage}" windowTitle="${windowTitle}" errorPage="${errorPage}">
            ${metaCapsuleContent}                              
        </div>
        
        <%-- clear parameters --%>
        <c:set var="capsuleId" value="" scope="page"/>            
        <c:set var="capsuleType" value="" scope="page"/>                
        <c:set var="targetId" value="" scope="page"/>          
        <c:set var="jsOnload" value="" scope="page"/>
        <c:set var="reloadPage" value="" scope="page"/>
        <c:set var="skipReloadPageOnPrevious" value="" scope="page"/>
        <c:set var="saveOriginalRequest" value="" scope="page"/>
        <c:set var="saveResponse" value="" scope="page"/>
        <c:set var="trackPage" value="" scope="page"/>
        <c:set var="windowTitle" value="" scope="page"/>         
        <c:set var="errorPage" value="" scope="page"/>
        <c:set var="metaCapsuleContent" value="" scope="page"/>

Full List Of Capsule Attributes Available In Dynamic Web App Mode

Listed here are all of the capsule attributes that WebRocketX supports in Dynamic Mode. The framework is running in Dynamic Mode when the staticPage variable in the welcome page is set to false. There are far fewer attributes available when the framework is running in Static Mode. See the Static App Tutorial for instructions on how to develop a Single Page Static Web (SPSW) site.

Attributes not included in the capsule will be set to their default values. Required attributes are marked with an asterisk*.

id* - Used to keep track of the page in the WebRocketX framework. Relayed through capsuleId parameter in template example. Using templates is not required.
class* - Must be set to the value "metaCapsule". Used by the framework to locate the capsule div.
capsuleType* - Can be set to the following four values, which determines how and if the capsule will be injected.
- inline - Content will be injected in the div specified by the targetId attribute.
- modal - Content will be injected in a floating modal layer.
- data - Content will not be tracked for navigation by the framework. The developer can decide whether to specify a targetId or place the content on their own, or even use the content without placing it in the page. The content will be returned to the developer in the callback, as the first parameter, in the form of a DOM object of the capsule and its included contents. This is the ideal capsule type to use for refreshable smaller parts of the page that are not navigated as whole pages. For example, search results, tickers, etc.
- json - Simply render the json text into the capsule server side and it will be delivered in the browser side callback already turned into a json object. Sending json parameters to the server can be done by setting the value of a parameter to a json string using the AsyncParametersList object.
targetId (*required if capsuleType is inline) - Specifies the location where incoming html will be injected, when the capsule type is "inline".
jsOnload - Specifies a javascript method that will be called when the injection is complete. Very useful for registering autocompleters, jquery ui components, and any other kind of page load type operations. All of your javascript file references can be made in javascriptFileList.jsp, so that all js is loaded when entering the welcome page of the application.

If a handle to the capsule that the jsOnload function was declared in is desired, inside the onload code, then add the parameter "capsule" in lower case letters in the attribute declaration like so

jsOnload="myJSFunction(capsule);"

Then in this function a handle to the capsule will be available as its one parameter.
jsReturn - Specifies a javascript method that will be called when this page is returned to but not reloaded. Returning to a page can be trigged by using the back button or calling dtSetCapsuleById. This mechanism is useful when the developer desires part of the view to be refreshed, or any other code to be run, upon display either conditionally or unconditionally. Since the application is running in a single page, conditions can be relayed between pages as global variables.

If a handle to the capsule that the jsReturn function was declared in is desired, inside the onload code, then add the parameter "capsule" in lower case letters in the attribute declaration like so

jsReturn="myJSFunction(capsule);"

Then in this function a handle to the capsule will be available as its one parameter.
reloadPage (default: false) - When this is true, navigating to this page in the browser stack will result in a fresh version of this content being retrieved from the server. The original request will be resent, with all of its original parameters, and the original callback method will be called.
skipReloadPageOnPrevious (default: false) - When this is true, a navigation from this page to a page in the browser stack that is marked with a reload will block that destination page from reloading. This is particularly useful in allowing the developer to control whether different back flows to a reload page will cause it to reload or not. For example, it is often undesireable when navigating back to a background page from a modal for that background page to reload. However, it still might be desireable for that same background page to reload when it is navigated back to from a page that replaced it.
saveOriginalRequest (default: false) - When set to true, the original request will be saved even if this is not a reload.
saveResponse (default: false) - When set to true, the response object is stored in the injected capsule div. This can be later used to restore the injected content to its original state after edits by the user, by calling restoreAsyncResponse(id). The most common case where this ability is desired is when the page has a cancel button.
trackPage (default: true) - Defaults to true specifying that this page is placed in the back stack for further reference. This setting is not relevant for the capsule types of data and json because those types are not navigable to begin with. The developer can specify that this page should not be placed in the back stack by setting this attribute to false. Setting trackPage to false is an ideal solution for pages that you do not want the user to go back to and then resubmit, like a "create" page. When the user goes back to an untracked page they will skip over it and land on the tracked page preceding it.
windowTitle - Specifies the title to be set on the top of the browser. Necessary because we never changes pages and therefore never update the title tag in the html header.
errorPage - Marks this page as a typed exception which will result in the developer defined successful callback being skipped and the developer defined failure callback being called.