Tutorial 29: How to Share a Web Session Across Multiple Formspider Applications

Note: This tutorial is not applicable on Formspider Online, you can exercise this tutorial only on your local Formspider installations.

This tutorial explains how to share the same session across multiple Formspider applications. You will discover how to run a Formspider application in the same session with another Formspider application and consequently how to share session variables across multiple applications.

Assume that you have a system divided into multiple sub-modules where each sub-module is implemented as a standalone Formspider application. For providing the connection between these sub-modules, assume that you designed a main application from which you can run these sub-module Formspider applications. In such a structure you inevitably need to share some information between your main and sub-module applications. To accomplish this, the best solution is to keep the shared information in session variables and sharing these session variables by running multiple Formspider applications in the same web session with another Formspider application.

In this tutorial you will create two basic applications named “main” and “module1”. The purpose of “main” application is providing the connection between standalone sub-module applications as mentioned earlier. In this tutorial, there is only one sub-module application named “module1”.

“Main” application starts with a simple sign in screen . When the user signs in, a navigation screen listing sub-module applications is displayed. This screen contains a button which when pressed, runs the “module1” application. In such a scenario, it is desirable to implement single sign on, so that when the user starts “module1″ he does not enter his user name and password again. This tutorial explains how to provide this functionality by keeping user name and password information in session variables and run “module1” application in the same session with the “main” application in order to be able to share these session variables between the two applications.

Creating User Interface

Open Formspider IDE and click “New Application” under the “File” menu. The “New Application” dialog shows up. Enter “main” as the name of the application and ”HR” as its datasource schema name. Leave other fields empty and click “OK”. This creates the “main” application with a default mainframe (called “mainFrame”) and a default panel (called “mainPanel”).

As the first step implement the sign in screen. Double click the “mainPanel” under the “Panels” node of the “Containers” navigation tree to open it in the editor. Edit the Panel XML and add a textField named “tf_username” and a passwordField named “pf_password” where the user can enter his user name and password information. Additionally, add a button labeled “Sign In” which navigates the user to the navigation panel and creates the necessary session variables holding user name and password information if a valid user name/password combination is provided. The panel XML looks like the following;

<panel>
  <tableLayout cellSpacing="5">
    <row height="0">
      <cell width="40%"/>
      <cell/>
    </row>
    <row/>
    <row height="20">
      <cell hAlign="Full" vAlign="Center">
        <textLabel font-style="Bold" label="Username" text-align="Right"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <textField name="tf_username"/>
      </cell>
    </row>
    <row height="20">
      <cell hAlign="Full" vAlign="Center">
        <textLabel font-style="Bold" label="Password" text-align="Right"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <passwordField name="pf_password"/>
      </cell>
    </row>
    <row height="20">
      <cell/>
      <cell hAlign="Left" vAlign="Center" childWidth="75">
        <button label="Sign In"/>
      </cell>
    </row>
    <row/>
  </tableLayout>
</panel>

As the next step, create the navigation panel which is displayed when the user is successfully signed in. To create this panel, expand the “Containers” accordion panel, select the “Panels” node in the navigation tree and click the “+” button to create a new simple panel. Alternatively, you may right click the “Panels” node and select the “New” menu item from the pop-up menu. The “New Panel” dialog shows up. Enter “navigationPanel” as the name of the panel. Click “OK” to create and open the panel in the editor. Edit the panel to contain a button labeled “Module1” for running “module1” application in the same session with the “main” application. The panel XML is below;

<panel>
  <tableLayout cellSpacing="5">
    <row height="20">
      <cell hAlign="Full" vAlign="Full">
        <textLabel label="Please select a child module from below: "/>
      </cell>
    </row>
    <row height="10"/>
    <row height="20">
      <cell hAlign="Center">
        <button label="Module1"/>
      </cell>
    </row>
  </tableLayout>
</panel>

Press “Run on Web” button to run the “main” application. Note that the sign in screen is displayed as expected.

“main” application is opened with a Sign In screen

Next, create your “module1” application which is opened when “Module1” button in the “navigationPanel” of the main application is pressed. To achieve this, create a new application, enter “module1” as the name of the application and ”HR” as its datasource schema name. Leave other fields empty and click “OK”.

“Module1” application consists of a sign in screen and a welcome screen. When “module1” application is started it checks the user name and password session variables to determine whether this application is called by a logged in user. If the user is already logged in the sign in screen of “module1” application is not displayed and the application proceeds directly to the welcome screen.

You will use exactly the same sign in panel design that you have used in the “main” application. Therefore, double click the “mainPanel” and edit your panel xml as the following;

<panel>
  <tableLayout cellSpacing="5">
    <row height="0">
      <cell width="40%"/>
      <cell/>
    </row>
    <row/>
    <row height="20">
      <cell hAlign="Full" vAlign="Center">
        <textLabel font-style="Bold" label="Username" text-align="Right"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <textField name="tf_username"/>
      </cell>
    </row>
    <row height="20">
      <cell hAlign="Full" vAlign="Center">
        <textLabel font-style="Bold" label="Password" text-align="Right"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <passwordField name="pf_password"/>
      </cell>
    </row>
    <row height="20">
      <cell/>
      <cell hAlign="Left" vAlign="Center" childWidth="75">
        <button label="Sign In"/>
      </cell>
    </row>
    <row/>
  </tableLayout>
</panel>

Next, create a welcome panel displaying a sample welcome message. This panel is displayed when the user signs in to “module1” application or if this application is called by a logged in user. To accomplish this, create a new panel and enter “welcomePanel” as the name of the panel. Your panel XML should look like this:

<panel>
  <tableLayout>
    <row>
      <cell hAlign="Full" vAlign="Full" >
        <textLabel font-size="15"  label="Welcome to Module1 application! You are successfully signed in." text-align="Center"/>
      </cell>
    </row>
  </tableLayout>
</panel>

Press “Run on Web” button to run the “module1” application. Note that the sign in screen is displayed as expected;

“module1” application is opened with a Sign In screen

As the final step of the tutorial implement the session sharing mechanism.

Implementing Session Sharing Mechanism

Select “main” application from the “Application” combobox to open it in the Formspider IDE. When “Sign In” button is pressed, the application validates the user name/password combination provided by the user and displays the “navigationPanel” if this combination is valid. At the same time it creates two session variables named “username” and “password” holding signed in user’s user name and password information. These session variables are later used in the “module1” application whether the user is already logged in. To accomplish this, create a Formspider action which fires when “Sign In” button is pressed.

In the datasource schema, create a package called  “sessionSharing_pkg” and it in your favorite PL/SQL Editor. Add a procedure named “signIn” and ensure that the procedure is exposed in the package specification. Below is the code of the signIn procedure.

procedure signIn is
  v_userName_tx varchar2(4000);
  v_password_tx varchar2(4000);
begin
  v_userName_tx := api_component.getvaluetx('mainPanel.tf_username');
  v_password_tx := api_component.getvaluetx('mainPanel.pf_password');

  if v_userName_tx = 'demo' and v_password_tx = 'demo' then
    api_session.add('username', v_userName_tx);
    api_session.add('password', v_password_tx);

    api_frame.addpanel('mainFrame','cell_mainFrameCenter', 'navigationPanel');
  else
    api_application.showpopupmessage('Invalid username or password');
  end if;
end;

Note that in this example, demo/demo is the only valid user name/password combination in the system. If the valid user name/password combination is provided, two session variables are created to keep these values.

Also note that you have used api_frame.addpanel to display “navigationPanel” panel in the “mainframe”. In order to reference a Formspider UI Object in an API call, it must be named. To accomplish this expand the “Windows” node and then the “Mainframe” node from the “Containers” tree. Double click to the “mainFrame” node to open it and enter “cell_mainFrameCenter” as the name of the cell in which the “navigationPanel” is added. The final panel XML is below:

<mainframe title="main" width="500" height="500">
  <borderLayout>
    <cell docking="Center" name="cell_mainFrameCenter">
      <include panelName="mainPanel"/>
    </cell>
  </borderLayout>
</mainframe>

In the Formspider IDE expand the “Actions” accordion, select the “Actions” node and click the “+” button to create a new action. Alternatively, you may right click the “Actions” node and select “New” from the pop-up menu. The “New Action” dialog shows up. Enter “signIn” as the action name and “sessionSharing_pkg.signIn” as the procedure. Click “OK” to save the action.

Creating “signIn” action

Open the “mainPanel” in the editor. Add a buttonPress event to the “Sign In” button triggering the “signIn” action. The final panel XML looks like the following:

<panel>
  <tableLayout cellSpacing="5">
    <row height="0">
      <cell width="40%"/>
      <cell/>
    </row>
    <row/>
    <row height="20">
      <cell hAlign="Full" vAlign="Center">
        <textLabel font-style="Bold" label="Username" text-align="Right"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <textField name="tf_username"/>
      </cell>
    </row>
    <row height="20">
      <cell hAlign="Full" vAlign="Center">
        <textLabel font-style="Bold" label="Password" text-align="Right"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <passwordField name="pf_password"/>
      </cell>
    </row>
    <row height="20">
      <cell/>
      <cell hAlign="Left" vAlign="Center" childWidth="75">
        <button label="Sign In">
          <events>
            <buttonPress action="signIn"/>
          </events>
        </button>
      </cell>
    </row>
    <row/>
  </tableLayout>
</panel>

As the next step, create necessary procedure and action which runs when the “Module1” button in the “navigationPanel” is pressed. Open “sessionSharing_pkg” package and create a procedure named “openModule1” which uses api_application.run API to open “module1” application in the same session with the “main” application.

procedure openModule1 is
  v_servletURL_tx varchar2(255) := 'http://localhost:8080/formspider/';
begin
  api_application.run(in_weblink_tx           => v_servletURL_tx || 'main.html?name=module1'
                     ,in_browserwindowname_tx => 'module1'
                     ,in_transferfocus_yn     => 'Y'
                     ,in_keepsession_yn       => 'Y');
end;

Note that the value ‘Y’ assigned to in_keepsession_yn parameter assures that the “module1” application is opened in the same session with the “main” application. If the value is ‘N’ for this parameter the “module1” application opens in a new session and the session variables created in “main” application become inaccessible. In Formspider, an application starts in a new session by default (when you run it through IDE or by making an URL request through your web browser). The only way to run an application in the same session with another one is using the api_application.run API with ‘Y’ as in_keepsession_yn parameter value.

Also note that the value assigned to the in_weblink_tx parameter is the URL of “module1” application. You may change the value of v_servletURL_tx variable depending on the URL of your local Formspider installation.

Create a new action. Enter “openModule1” as the action name and “sessionSharing_pkg.openModule1” as the procedure. Since api_application.run API triggers the opening of a new browser window, tick “Allow Popups” check box to avoid browser popup windows. Click “OK” to save the action.

Open the “navigationPanel” in the editor. Add a buttonPress event to the “Module1” button triggering the “openModule1” action. The final panel XML looks like this:

<panel>
  <tableLayout cellSpacing="5">
    <row height="20">
      <cell hAlign="Full" vAlign="Full">
        <textLabel label="Please select a child module from below: "/>
      </cell>
    </row>
    <row height="10"/>
    <row height="20">
      <cell hAlign="Center">
        <button label="Module1">
          <events>
            <buttonPress action="openModule1"/>
          </events>
        </button>
      </cell>
    </row>
  </tableLayout>
</panel>

Run the “main” application again. Enter demo as “User Name” and demo as “Password” and press “Sign In” button to proceed to the “navigationPanel”. Then, press “Module1” button. The “module1” application opens in the same web session with the “main” application. Since there is no verification mechanism yet in “module1” application, controlling the session variables created in “main” application, the sign in screen is still displayed.

In the final step of this tutorial, create an action which triggers after “module1” application is opened. In this action check the values of “username” and “password” session variables. If a valid combination is already provided skip the sign in screen and directly display the welcome screen.

Select “module1” from the “Application” combobox to open the “module1” application in Formspider IDE.

Open “sessionSharing_pkg” package and create a new procedure named “postOpenModule1”. Ensure that the procedure is exposed in the package specification. The code for the “postOpenModule1” is below:

procedure postOpenModule1 is
  v_userName_tx varchar2(4000);
  v_password_tx varchar2(4000);
begin
  v_userName_tx := api_session.getValueTX('username');
  v_password_tx := api_session.getValueTX('password');
  if v_userName_tx = 'demo' and v_password_tx = 'demo' then
    api_frame.addpanel('mainFrame','cell_mainFrameCenter', 'welcomePanel');
  end if;
end;

The procedure gathers the user name and password values from the web session variables which were created in “main” application. If it’s a valid combination the procedure displays the “welcomePanel” in the “mainFrame”.

Note that the procedure uses the api_frame.addpanel API to display the “welcomePanel” panel in the “mainframe”. Therefore, the layout cell in which the “welcomePanel” is added must have a name. Edit the mainframe XML so that it looks like this:

<mainframe title="module1" width="500" height="500">
  <borderLayout>
    <cell docking="Center" name="cell_mainFrameCenter">
      <include panelName="mainPanel"/>
    </cell>
  </borderLayout>
</mainframe>

Create a new action. Enter “postOpenModule1” as the action name and “sessionSharing_pkg.postOpenModule1” as the procedure. Click “OK” to save the action.

Use the “postOpen” event of the “module1” application to trigger the “postOpenModule1” action after the “module1” application starts. Click “Edit Current Application” button next to the “Application” combobox to open application edit dialog. Open “Events” tab and select “postOpenModule1” from “Post Open” combobox. Click “OK” to save changes.

Assigning “postOpenModule1” action to application's postOpen event

Exprimenting with Session Sharing

Run the “module1” application from the IDE. Since the “module1” application is started in a new session, the “username” and “password” session variables for this instance of the application are undefined. Therefore, the sign in screen shows up.

Select “main” from the “Application” combobox to open the “main” application in the Formspider IDE. Run the application. Sign in as demo/demo user and press “Module1” button.

This time, since “module1” application shares the same session with the “main” application, it can access to the “username” and “password” session variables defined in the “main” application. Consequently, the sign in screen is skipped and the welcome screen is displayed.

Since “module1” shares the same session with “main”, welcome screen is displayed