How to use External Method

This tutorial explains how to use external method in a Formspider application. It decribes how to implement a “Remember Me” functionality using a cookie created and retrieved back through Formspider external method.

The sample application described in this tutorial contains two screens. The first one is a login screen containing “Username” and “Password” fields, a “Remember Me” checkBox and a “Log In” button. The second one is a simple welcome screen containing a welcome message textLabel. The tutorial explains how to create a cookie when “Log In” is pressed, if the “Remember Me” checkBox is ticked. This cookie stores username and password values. It also describes how to skip the application’s login screen by retrieving and checking the cookie value when the application starts.

What is the External Method?

The external method is a Formspider feature which enables you to execute methods on the client computer. In other words, the external method enables you to execute JavaScript methods on the client computer.

Formspider JavaScript library introduces two predefined JavaScript methods named “setCookie” and “getCookie” which allow you to create a cookie with the given name-value pair and duration and retrieve the value of a cookie with the given name. This tutorial benefits from these two predefined JavaScript methods to implement the “Remember Me” functionality.

Note: In addition to the Formspider predefined JavaScript methods, you can always use an external method to execute your custom JavaScript code. To achieve this;

  • Place your JavaScript code any place under the [Tomcat]/webapps/formspider folder
  • Add the reference of your JavaScript code to the “main.jsp” file existing under the [Tomcat]/webapps/formspider folder

Assuming that the name of the file containg your JavaScript code is “myCodes.js” and you have placed this file under the [Tomcat]/webapps/formspider/js folder, you should simply add the following line to your “main.jsp” (please remember to add this line in html body);

<script src="js/myCodes.js" type="text/javascript"></script>

You may click here to run the completed application.

Implementing the Login Mechanism

Open Formspider IDE and click “New Application” under the “File” menu. The “New Application” dialog shows up. Enter “externalMethod” as the name of the application and “HR” as its Datasource Schema name.  If you are using Formspider Online, you do not need to enter database schema name since your account is already configured to use your online database. Leave other fields empty and click “OK”. This creates the “externalMethod” application with a default mainframe (called “mainFrame”) and a default panel (called “mainPanel”).

Create a panel which contains the “Username” and “Password” fields, “Remember Me” checkBox and the “Log In” button. Expand the “Containers” accordion, select the “Panels” node in the navigation tree and click the “+” button to create a new 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 “loginPanel” as the name of the panel. Click “OK” to create and open the panel in the editor.

Creating “loginPanel”

Add a textField labeled “Username”, a passwordField labeled “Password”, a checkBox labeled “Remember Me” and a button labeled “Log In” to the “loginPanel”.

<panel font-size="14">
  <tableLayout cellSpacing="10">
    <row/>
    <row heightPolicy="Dynamic">
      <cell columnSpan="3" hAlign="Full" vAlign="Full">
        <textLabel font-size="20" label="Log in to the Tutorial Application"/>
      </cell>
    </row>
    <row height="1"/>
    <row height="30">
      <cell width="100" hAlign="Left" vAlign="Full">
        <textLabel label="Username:"/>
      </cell>
      <cell columnSpan="2" hAlign="Full" vAlign="Full">
        <textField name="username" autoComplete="Y"/>
      </cell>
    </row>
    <row height="30">
      <cell hAlign="Left" vAlign="Full">
        <textLabel label="Password:"/>
      </cell>
      <cell columnSpan="2" hAlign="Full" vAlign="Full">
        <passwordField name="password"/>
      </cell>
    </row>
    <row height="30">
      <cell hAlign="Left" vAlign="Full">
        <textLabel label="Remember Me:"/>
      </cell>
      <cell columnSpan="2" hAlign="Left" vAlign="Full">
        <checkBox name="rememberMe"/>
      </cell>
    </row>
    <row height="30">
      <cell/>
      <cell columnSpan="2" hAlign="Full" vAlign="Full">
        <button font-color="#303030" font-style="Bold" label="Log In"/>
      </cell>
    </row>
    <row height="1"/>
    <row/>
  </tableLayout>
</panel>

Include the “loginPanel” to the “mainPanel”. Expand the “Panels” node under the “Containers” accordion and double-click the “mainPanel” to open it in the editor. Edit the panel XML as following;

<panel>
  <borderLayout>
    <cell docking="Center" name="cell_center">
      <include panelName="loginPanel"/>
    </cell>
  </borderLayout>
</panel>

Create a new panel and enter “welcomePanel” as the name. This panel contains a welcome message textLabel.

<panel font-size="14">
  <tableLayout>
    <row>
      <cell hAlign="Full" vAlign="Full">
        <textLabel label="Welcome to the Tutorial Application." text-align="Center"/>
      </cell>
    </row>
  </tableLayout>
</panel>

When “Log In” button of the “loginPanel” is pressed you should validate the “Usename” and “Password” values. To achieve this, create a Formspider action which will be fired when “Log In” button is pressed.

In your datasource schema, create a package called “externalmethod_pkg” and open your newly created “externalmethod_pkg” package in your favorite PL/SQL editor. Add a procedure named “logIn” and ensure that the procedure is exposed in the package specification. This procedure uses api_component.getValueTX API to retrieve the values entered in “Username” and “Password” fields. If both of these values are equal to “admin”, this procedure uses the api_panel.addPanel API to display the “welcomePanel” on the screen.

procedure logIn is
  v_userName_tx   varchar2(4000);
  v_password_tx   varchar2(4000);
begin
  v_userName_tx := api_component.getvaluetx('loginPanel.username');
  v_password_tx := api_component.getvaluetx('loginPanel.password');
  if v_userName_tx = 'admin' and v_password_tx = 'admin' then
    -- navigate to the welcome screen
    api_panel.addpanel('mainPanel', 'cell_center','welcomePanel');
  else
    api_application.showpopupmessage('Invalid username or password');
  end if;
end;

In Formspider IDE expand the “Actions” accordion, select the “Actions” node, 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 “logIn” as the action name and “externalmethod_pkg.logIn” as the procedure. Click “OK” to save your action.

Creating “logIn” action

Open the “loginPanel” in the editor. Add a buttonPress event to the “Log In” button triggering the “logIn” action, the panel XML should look like;

<panel font-size="14">
  <tableLayout cellSpacing="10">
    <row/>
    <row heightPolicy="Dynamic">
      <cell columnSpan="3" hAlign="Full" vAlign="Full">
        <textLabel font-size="20" label="Log in to the Tutorial Application"/>
      </cell>
    </row>
    <row height="1"/>
    <row height="30">
      <cell width="100" hAlign="Left" vAlign="Full">
        <textLabel label="Username:"/>
      </cell>
      <cell columnSpan="2" hAlign="Full" vAlign="Full">
        <textField name="username" autoComplete="Y"/>
      </cell>
    </row>
    <row height="30">
      <cell hAlign="Left" vAlign="Full">
        <textLabel label="Password:"/>
      </cell>
      <cell columnSpan="2" hAlign="Full" vAlign="Full">
        <passwordField name="password"/>
      </cell>
    </row>
    <row height="30">
      <cell hAlign="Left" vAlign="Full">
        <textLabel label="Remember Me:"/>
      </cell>
      <cell columnSpan="2" hAlign="Left" vAlign="Full">
        <checkBox name="rememberMe"/>
      </cell>
    </row>
    <row height="30">
      <cell/>
      <cell columnSpan="2" hAlign="Full" vAlign="Full">
        <button font-color="#303030" font-style="Bold" label="Log In">
          <events>
            <buttonPress action="logIn"/>
          </events>
        </button>
      </cell>
    </row>
    <row height="1"/>
    <row/>
  </tableLayout>
</panel>

Press “Run on Web” to run your application. Enter “admin” as the “Username” and “admin” as the “Password” values, tick “Remember Me” and press “Log In”, the welcome screen is displayed. Note that since the “Remember Be” functionality is not implemented yet, the login screen displays each time you run the application.

Implementing the “Remember Me” Functionality

Expand the “Miscellaneous” accordion panel, select the “External Methods” root node and click the “+” button from the toolbar of the accordion panel. Alternatively, you may right click the “External Methods” root node in the navigation tree and click the “New” menu item from the pop up menu that is displayed. The “New External Method” dialog shows up.

Enter “setUserCookie” as the “Name”, this value will be used later on API calls.

Enter “setCookie(string,string,number)” as the “JavaScript Signature”. Note that the first parameter of this method is the name of your cookie, the second parameter is the value of your cookie and the last parameter is the duration time of your cookie in days.

Leave “Post method completed” blank. “Post method completed” is the name of the Formspider event which is triggered when the the external method execution is completed. This event is meaningful for external methods which returns a value since it’s mainly used to obtain the return value of the external method.

Creating “setUserCookie” external method

Press “OK” to create your external method.

Invoke the “setCookie” JavaScript method if the “Remember Me” checkBox is ticked when the “Log In” button is pressed. To achieve this, edit the “logIn” procedure existing in your “externalmethod_pkg” package as the following;

procedure logIn is
  v_userName_tx   varchar2(4000);
  v_password_tx   varchar2(4000);
  v_rememberMe_yn varchar2(1);
  v_params_t      api_externalMethod.tt_params;
begin
  v_userName_tx := api_component.getvaluetx('loginPanel.username');
  v_password_tx := api_component.getvaluetx('loginPanel.password');
  if v_userName_tx = 'admin' and v_password_tx = 'admin' then
    v_rememberMe_yn := api_component.ischecked('loginPanel.rememberMe');
    -- if "Remember Me" is ticked, create the cookie
    if v_rememberMe_yn = 'Y' then
      -- cookie name
      v_params_t('0').value_tx := 'externalMethodDemo';
      -- cookie value
      v_params_t('1').value_tx := v_userName_tx||';'||v_password_tx;
      -- cookie duration
      v_params_t('2').value_tx := 365 * 40;
      -- invoke "setUserCookie" external method
      api_externalMethod.invoke('setUserCookie', v_params_t);
    end if;
    -- navigate to the welcome screen
    api_panel.addpanel('mainPanel', 'cell_center', 'welcomePanel');
  else
    api_application.showpopupmessage('Invalid username or password');
  end if;
end;

Note that v_params_t is the array holding the value of the external method parameters, respecting the order they appeared in the signature. Examining the external method parameters you can easily conclude that the name of the cookie which will be created is “externalMethodDemo”, which holds the username and the password values and expires after 40 years.

Also, note that api_externalMethod.invoke API is used to execute the JavaScript method that the “setUserCookie” external method references.

Create a new external method, enter “getUserCookie” as the “Name” and “getCookie(string)” as the “JavaScript Signature”. Note that the single parameter of this method is the name of the cookie whose value will be retrieved. Leave “Post method completed” blank for now and press “OK”.

Creating “getUserCookie” external method

Add a new procedure named “getUserCookie” in your “externalmethod_pkg”, this procedure simply invokes your newly created “getUserCookie” external method to retrieve the value of the cookie named “externalMethodDemo”.

procedure getUserCookie is
  v_params_t api_externalMethod.tt_params;
begin
  -- cookie name
  v_params_t('0').value_tx := 'externalMethodDemo';
  -- invoke "getUserCookie" external method
  api_externalMethod.invoke('getUserCookie', v_params_t);
end;

Create a new action, enter “getUserCookie” as the action name and “externalmethod_pkg.getUserCookie” as the procedure. Click “OK” to save your action. You will use this action to retrieve the cookie value when the application is started. To achieve this, use the “Post Open” event of the application.

Press “Edit Current Application” button next to the “Application” combobox to open the edit dialog. Select the “Events” tab and select “getUserCookie” from the “Post Open” combobox. Press “OK” to save your changes.

Using “getUserCookie” action in “Post Open” event of the application

As explained above, the return value of an external method can be retrieved in “Post method completed” event of this external method. Add a new procedure named “checkUserByCookie” in your “externalmethod_pkg”. This procedure first checks whether the “getUserCookie” external method is successfully invoked or not using the api_externalMethod.isSuccessful API. If it’s successfully executed it retrieves the return value of the “getUserCookie” external method through api_externalMethod.getResult API and navigate directly to “welcomePanel” if the cookie value is a valid username/password pair.

procedure checkUserByCookie is
  v_result_tx          varchar2(8000);
  v_userName_tx        varchar2(4000);
  v_password_tx        varchar2(4000);
  v_seperatorIndex_nr  number;
begin
  -- if "getUserCookie" external method is successfully invoked
  if api_externalMethod.issuccessful('getUserCookie') = 'Y' then
    -- get the return value of your external method, which is the cookie value
    v_result_tx := api_externalMethod.getresult('getUserCookie');
    -- retrieve username and password from cookie value
    v_seperatorIndex_nr := instr(v_result_tx, ';');
    v_userName_tx := substr(v_result_tx, 1, v_seperatorIndex_nr - 1);
    v_password_tx := substr(v_result_tx, v_seperatorIndex_nr + 1);

    if v_userName_tx = 'admin' and v_password_tx = 'admin' then
      -- navigate to the welcome screen
      api_panel.addpanel('mainPanel', 'cell_center', 'welcomePanel');
    else
      -- navigate to the login screen
      api_panel.addpanel('mainPanel', 'cell_center', 'loginPanel');
    end if;
  end if;
end;

Create a new action, enter “checkUserByCookie” as the action name and “externalmethod_pkg.checkUserByCookie” as the procedure. Click “OK” to save your action.

Double-click the “getUserCookie” node under the “External Methods” node from the “Miscellaneous” tree to open the edit dialog. Select “checkUserByCookie” action from the “Post method completed” combobox and press “OK” to save your changes.

Select “checkUserByCookie” from the “Post method completed” combobox

Finally, open the “mainPanel” and remove the previously included “loginPanel” since the “checkUserByCookie” procedure dynamically adds “welcomePanel” or “loginPanel” to the “mainPanel” following the cookie check.

<panel>
  <borderLayout>
    <cell docking="Center" name="cell_center"/>
  </borderLayout>
</panel>

Run your application again, enter “admin” as the “Username” and “Password”, tick “Remember Me” and press “Log In”, the cookie is created.

Refresh the application by pressing F5 key or simply run it again from the Formspider IDE. Note that, since the “Remember Me” functionality is implemented, the login screen is skipped and the welcome screen is displayed automatically.

You may click here to run the application.

“Remember Me” functionality is implemented