Tutorial 27: How to build a Timer

This tutorial explains how to build and use timer in Formspider. The timer allows you to specify an interval at which a Formspider event named “Timer Expired” is raised in your application. You can use this event to perform the processing you need. You can use a Formspider timer in two ways:

  • To perform a processing only once, after the first interval has elapsed.
  • To perform a processing repeatedly, each time the specified interval has elapsed.

In this tutorial, you will create a sample application containing a recurring timer which prints current time information on a textArea. You will learn how to create a timer, how to specify an interval for your timer, how to start and stop your timer and how to perform an action when the specified time interval has elapsed.

You may click here to run the completed application.

Open Formspider IDE and click “New Application” under the “File” menu. The “New Application” dialog will show up. Enter “timer” 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 “timer” application with a default mainframe (called “mainFrame”) and a default panel (called “mainPanel”).

Creating the User Interface

As the first step you will build the user interface. Double click the “mainPanel” under the “Panels” node of the “Containers” navigation tree to open it in the editor. Your panel will contain two buttons labeled “Start Timer” and “Stop Timer” which will start and stop your timer. Also this panel will contain a textArea named “textArea_dateTimeInfo” on which your timer will print the current time information. Your panel XML should look like;

<panel>
  <tableLayout cellSpacing="5">
    <row height="30">
      <cell vAlign="Full">
        <button label="Start Timer"/>
      </cell>
      <cell vAlign="Full">
        <button label="Stop Timer"/>
      </cell>
    </row>
    <row>
      <cell hAlign="Full" vAlign="Full" columnSpan="2">
        <textArea name="textArea_dateTimeInfo" domain="DefaultCLOB"/>
      </cell>
    </row>
  </tableLayout>
</panel>

Creating the Timer

As the second step you will create your timer. To achieve this, expand the “Miscellaneous” accordion panel, select the “Timers” root node and click the “+” button from the toolbar of the accordion panel. Alternatively, you may right click the “Timers” root node in the navigation tree and click the “New” menu item from the pop up menu that is displayed. The “New Timer” dialog shows up.

Creating a new timer

Enter “dateTimePrinter” in the “Name” section, you will use this name later on in PL/SQL API calls.

“Interval” is time, in seconds, between raisings of the “Timer Expired” event. Enter 5 as “Interval” value for setting your timer‘s interval to 5 seconds.

“Repeat” is the section defining whether your the timer‘s interval is recurring or not, meaning that if your timer will raise the “Timer Expired” event repeatedly or only once. Leave “Repeat” check box ticked for assuring that your timer raise the “Timer Expired” event repeatedly.

Finally, as mentioned earlier, “Timer Expired” is the name of the Formspider event raised by your timer. It’s the section where you can specify which Formspider action will be fired when your timer‘s interval has elapsed. Leave it blank for now, you will create this action as the next step of this tutorial. Click “OK” to create your timer.

Creating “dateTimePrinter” timer

As the final step, you will create necessary Formspider actions to start and stop your timer when “Start Timer” and “Stop Timer” buttons are pressed. You will create another action to print time information on your textArea when your timer is expired.

In your datasource schema, create a package called “timer_pkg” and open your newly created “timer_pkg” package in your favorite PL/SQL Editor. First of all, you will add a procedure named “addMessageToTextArea”. This is an internal utility procedure which appends the given message in your textArea named “textArea_dateTimeInfo”.

procedure addMessageToTextArea(in_message_tx varchar2) is
  v_value_cl clob;
begin
  v_value_cl := api_component.getvaluecl('mainPanel.textArea_dateTimeInfo');
  v_value_cl := v_value_cl || chr(10) || in_message_tx;
  api_component.setvalue('mainPanel.textArea_dateTimeInfo', v_value_cl);
end;

Next, you will create the procedures which will be used by “Start Timer” and “Stop Timer” buttons. Add a procedure named “startTimer” and ensure that the procedure is exposed in the package specification. This procedure uses api_timer.startTimer API to start your “dateTimePrinter” timer. It also uses “addMessageToTextArea” procedure that you have created earlier to add a message in your textArea informing the user that the timer is started successfully.

procedure startTimer is
begin
  api_timer.startTimer('dateTimePrinter');
  addMessageToTextArea('Timer started... ' || to_char(sysdate, 'DD/MM/YYYY HH24:MI:SS'));
end;

Add a procedure named “stopTimer” which uses api_timer.stopTimer API to stop your “dateTimePrinter” timer. It also uses the “addMessageToTextArea” procedure that you have created earlier to add a message in your textArea informing that the timer is stopped successfully.

procedure stopTimer is
begin
  api_timer.stoptimer('dateTimePrinter');
  addMessageToTextArea('Timer stopped... ' || to_char(sysdate, 'DD/MM/YYYY HH24:MI:SS'));
end;

Finally, you will create a procedure named “timerExpired” which will be used by the action which will be fired when your timer is expired. This procedure only adds a message in your textArea through the “addMessageToTextArea” procedure informing that your timer is expired.

procedure timerExpired is
begin
  addMessageToTextArea('Timer expired... ' || to_char(sysdate, 'DD/MM/YYYY HH24:MI:SS'));
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 will show up. Enter “timerExpired” as the action name and “timer_pkg.timerExpired” as the procedure. Click “OK” to save your action.

Creating “timerExpired” action

Expand “Timers” root node from the “Miscellaneous” tree and double-click the “dateTimePrinter” node to open your timer for edit, select “timerExpired” action from “Timer Expired” combo box to trigger “timerExpired” action when your timer is expired. Click “OK” to save your timer.

Assigning “timerExpired” action to timer's “Timer Expired” event

Finally, you will create the actions which will be used by “Start Timer” and “Stop Timer” buttons. Create a new action, enter “startTimer” as the action name and “timer_pkg.startTimer” as the procedure. Click “OK” to save your action. Then, create another action, enter “stopTimer” as the action name and “timer_pkg.stopTimer” as the procedure. Click “OK” to save your action.

Double-click and open the “mainPanel” in the editor. Add a buttonPress event to the “Start Timer” and “Stop Timer” buttons triggering the “startTimer” and “stopTimer” actions;

<panel>
  <tableLayout cellSpacing="5">
    <row height="30">
      <cell vAlign="Full">
        <button label="Start Timer">
          <events>
            <buttonPress action="startTimer"/>
          </events>
        </button>
      </cell>
      <cell vAlign="Full">
        <button label="Stop Timer">
          <events>
            <buttonPress action="stopTimer"/>
          </events>
        </button>
      </cell>
    </row>
    <row>
      <cell columnSpan="2" hAlign="Full" vAlign="Full">
        <textArea name="textArea_dateTimeInfo" domain="DefaultCLOB"/>
      </cell>
    </row>
  </tableLayout>
</panel>

Press “Run on Web” button for running your application.  Press “Start Timer” button to start your timer. Notice that your timer expires in every 5 seconds and a message is added on your textArea as expected. When you press “Stop Timer” button, your timer stops working.

You may click here to run the application.

Created Application is running