Tutorial 19: How to use Domains

This tutorial explains how to build and use domains in a Forsmpider Application. A domain is a Formspider feature having two major functionalities; it’s primarily used to implement data type and length restrictions over components and even over datasource definition columns. Secondly, it can be also used to make default value assignments.

In this tutorial you will create a basic login screen containing a textField, a passwordField and a button. You will discover how to create various domains and how to use these domains in Formspider components in order to implement data type and length restrictions.

Login Screen Specification

Assume that you have following requirements and restrictions for your example login screen;

  • The login screen consists of two input fields for “username” and “password” values and a “sign in” button.
  • The “username” field that can contain maximum 20 alphanumerical characters.
  • The “password” field can contain maximum 6 numerical characters.

Having these specifications on the hand, you will start by creating your login screen user interface.

(You may click here to run the completed application.)

Creating User Interface

As the first step of the implementation, you have to create an application, create your login panel and place required components (“username”and “password” fields plus “sign in” button) into your login panel. Let’s start by creating the application.

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

Next, you will create a panel which will contain required components. To achieve this, 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 will show 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 named “username”, a passwordField named “password” and a button in your “loginPanel”.

<panel>
  <tableLayout cellSpacing="5">
    <row height="20">
      <cell width="40%" hAlign="Full" vAlign="Center">
        <textLabel label="Username" text-align="Right" font-style="Bold"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <textField name="username"/>
      </cell>
    </row>
    <row height="11">
      <cell width="40%"/>
      <cell hAlign="Full" vAlign="Center">
        <textLabel text-align="Left" label="(Max. 20 alphanumerical chars)" font-size="10"/>
      </cell>
    </row>
    <row height="20">
      <cell width="40%" hAlign="Full" vAlign="Center">
        <textLabel label="Password" text-align="Right" font-style="Bold"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <passwordField name="password"/>
      </cell>
    </row>
    <row height="11">
      <cell width="40%"/>
      <cell hAlign="Full" vAlign="Center">
        <textLabel text-align="Left" label="(Max. 6 digit number)" font-size="10"/>
      </cell>
    </row>
    <row height="20">
      <cell width="40%"/>
      <cell hAlign="Left" vAlign="Center" childWidth="75">
        <button label="Sign In"/>
      </cell>
    </row>
  </tableLayout>
</panel>

As the next step, you will add “loginPanel” to the “mainPanel” for displaying your login screen in the mainFrame. Double click the “mainPanel” under the “Panels” node of the “Containers” navigation tree to open it in the editor. Include the “loginPanel” to the “mainPanel” as shown below;

<panel>
  <tableLayout>
    <row height="100"/>
    <row heightPolicy="Dynamic">
      <cell vAlign="Center">
        <include panelName="loginPanel"/>
      </cell>
    </row>
  </tableLayout>
</panel>

Then, to meet the specifications, you have to restrict number and types of characters and to be entered in “username” textField and “password” passwordField. To achieve this you will use domains.

Creating a sample domain for “username” textField

Expand the “Miscellaneous” accordion panel, select the “Domains” node in the navigation tree and click the “+” button to create a new domain. Alternatively, you may right click the “Domains” node and select the “New” menu item from the pop-up menu. The “New Domain” dialog will show up.

Enter “userNameDomain” as Name. Since it’s specified that “username” field should support alphanumerical characters select VARCHAR2 option from Data Type combobox, this selection assures the data type restriction. Note that two additional fields, Length and Default Value are appeared in the screen.

For a VARCHAR2 data typed domain, Length is the section determining maximum size in bytes, for example entering a value 100 as Length to a VARCHAR2 domain produces exactly same data type with the PL/SQL varchar2(100 byte) declaration. Since your “username” field should allow maximum 20 characters, enter 20 as value to this section.

Default Value is the section where you can sprecify a default value for this domain. Whatever a component a datasource definition column using a domain does not possess an initial value, it will use its domain‘s default value as the initial value. Leave it blank for now and click “OK” to save your domain.


Creating “userNameDomain”

As the next step you will associate this domain with “username” textField.

Using sample domain in “username” textField

Open “loginPanel” in the editor. In your panel XML, enter the value “userNameDomain” as “username” textField’s domain attribute and save your panel. At this stage your panel XML should look like;

<panel>
  <tableLayout cellSpacing="5">
    <row height="20">
      <cell width="40%" hAlign="Full" vAlign="Center">
        <textLabel label="Username" text-align="Right" font-style="Bold"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <textField name="username" domain="userNameDomain"/>
      </cell>
    </row>
    <row height="11">
      <cell width="40%"/>
      <cell hAlign="Full" vAlign="Center">
        <textLabel text-align="Left" label="(Max. 20 alphanumerical chars)" font-size="10"/>
      </cell>
    </row>
    <row height="20">
      <cell width="40%" hAlign="Full" vAlign="Center">
        <textLabel label="Password" text-align="Right" font-style="Bold"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <passwordField name="password"/>
      </cell>
    </row>
    <row height="11">
      <cell width="40%"/>
      <cell hAlign="Full" vAlign="Center">
        <textLabel text-align="Left" label="(Max. 6 digit number)" font-size="10"/>
      </cell>
    </row>
    <row height="20">
      <cell width="40%"/>
      <cell hAlign="Left" vAlign="Center" childWidth="75">
        <button label="Sign In"/>
      </cell>
    </row>
  </tableLayout>
</panel>

Remember that you can use the same domain in multiple components. This means that if there is more than one component that should be restricted with 20 alphanumerical characters you can use the same “userNameDomain” domain in every single component.

Now run your application. Notice that the maximum number of characters to be entered in “username” field is 20.


Maximum number of characters to be entered in “username” field is 20

As the final step you will define the domain to be used in “password” passwordField.

Creating a sample domain for “password” passwordField

Create a new domain and open the “New Domain” dialog again.

Enter “passwordDomain” as Name. Since it’s specified that “password” field should only support numerical characters select NUMBER option from Data Type combobox this time. Note that five additional fields; Length, Minimum, Maximum, Precision and Default Value are appeared in the screen.

For a NUMBER data typed domain Length is the total number of digits and Precision is the number of digits to the right of the decimal point. So in PL/SQL world domain‘s Length property is corresponding to precision and domain‘s Precision property is corresponding to scale. For example if you enter 8 and 1 as Length and Precision values, you have exactly same data type with the PL/SQL number(8,1) declaration. Since your “password” field should allow maximum 6 digit numbers and should not allow floating numbers, you will enter 6 as Length and leave blank the Precision section, which produces the same data type with PL/SQL number(6) declaration.

Minimum and Maximum are optional attributes determining minimum and maximum values that the domain can contain. When specified, it’s not possible for a user to enter any value exceeding these limits.

Leave Default Value blank again and click “OK” to save your domain.


Creating “passwordDomain”

Using sample domain in “password” passwordField

Open “loginPanel” in the editor again. In your panel XML, enter the value “passwordDomain” as “password” passwordField‘s domain attribute and save your panel. At this stage your panel XML should look like;

<panel>
  <tableLayout cellSpacing="5">
    <row height="20">
      <cell width="40%" hAlign="Full" vAlign="Center">
        <textLabel label="Username" text-align="Right" font-style="Bold"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <textField name="username" domain="userNameDomain"/>
      </cell>
    </row>
    <row height="11">
      <cell width="40%"/>
      <cell hAlign="Full" vAlign="Center">
        <textLabel text-align="Left" label="(Max. 20 alphanumerical chars)" font-size="10"/>
      </cell>
    </row>
    <row height="20">
      <cell width="40%" hAlign="Full" vAlign="Center">
        <textLabel label="Password" text-align="Right" font-style="Bold"/>
      </cell>
      <cell hAlign="Left" vAlign="Center" childWidth="150">
        <passwordField name="password" domain="passwordDomain"/>
      </cell>
    </row>
    <row height="11">
      <cell width="40%"/>
      <cell hAlign="Full" vAlign="Center">
        <textLabel text-align="Left" label="(Max. 6 digit number)" font-size="10"/>
      </cell>
    </row>
    <row height="20">
      <cell width="40%"/>
      <cell hAlign="Left" vAlign="Center" childWidth="75">
        <button label="Sign In"/>
      </cell>
    </row>
  </tableLayout>
</panel>

Run your application again. This time notice that since “password” field domain is NUMBER data typed it’s not possible to enter any characters except digits and the maximum number of digits to be entered is 6.

You may click here to run the application.


Data type and length restrictions are satisfied