Service Company Tutorial, Chapter 5: Implementing the Main Layout and Login Screen

This chapter of the tutorial describes how to create a main panel defining the main layout of the application UI and how to create panels to implement the login screen.

Remember that in the previous chapters, you defined the business problem and implemented the security and internationalization infrastructure. You can access the previous chapters of the tutorial through the following links:

You can also install the application in your local Formspider installation following the installation guide below:
SRDEMO Installation Guide

This chapter contains the following topics:

  • Analyzing the main layout
  • Implementing the main panel
    • Header Section Overview
    • Implementing the Header Section
    • Footer Section Overview
    • Implementing the Footer Section
  • Login Screen Overview
  • Implementing the Login Screen
    • Login Section Overview
    • Implementing the Login Section
    • Implementing the Information Section
  • Testing
  • Summary

Implementing the Main Layout and Login Screen

As a best practice, a Formspider application should contain a panel (generally named as “mainPanel”) defining the main layout of the application. This panel acts as a general container for all remaining panels that are dynamically displayed as a result of the application flow (e.g. Login panel, Welcome panel…) or that are statically displayed during the application life cycle (e.g. Fixed menus, images..). You start by analyzing the main layout of the application.

Analyzing the main layout

The following screenshots taken from the Login and Welcome screens, depict details of the main layout;

Login Screen

Welcome Screen

  1. There is a static section at the top of the application. It’s described as static since its content does not change during the application flow. It contains an image and two links labeled as “English” and “Italian” which are used to manage the current language of the application.

    Additionally, when a user is logged in, it displays the user information, “Logout” and “Help” links as well as the other links enabling users to navigate to the screens that they are authorized to use. This section will be called as the header section.

  2. There is a dynamic section at the center. It’s described as dynamic since its content changes depending on the application flow. The application screens (e.g. Login, Welcome, Triage..) are displayed in this section. This section will be called as the center section.
  3. There is a static line at the bottom of the application.
  4. There is a static section at the bottom of the application, displaying the “About this sample” link and copyright information. This section will be called as the footer section.

Implementing the Main Panel

In Formspider, in order to simplify the development and increase maintainability, it’s a best practice to split a screen into smaller sections and implement each section as a separate panel. Therefore, implementing the main panel compromises the creation of the necessary panels for the two static sections described above (header and footer sections) and the creation of the main panel itself containing these two sections as well as the center section where the screens will be added during run-time.

Header Section Overview

The following screenshot depicts details of the header section:

Header Section

  1. The top left of this section contains the brand image of the ACME Corporation.
  2. The first row of at the top right side contains a button and a hyperLink labeled “Logout”. The action that is specified for these components logs out the user from the application. This row also contains a button and a hyperLink labeled “Help”. The action that is specified for these components displays the help screen.
  3. The second row of at the top right side contains two hyperLinks labeled “English” and “Italian”. The actions that are specified for these hyperlinks set the current language of the application.
  4. The third row of the top right side of this section contains a panel where the main menu of the application is displayed. The main menu consists of the hyperLinks enabling users to navigate to the screens that they are authorized to use.
  5. The center of this section contains a panel where the child menu of the selected main menu item will be displayed.
  6. The bottom right of this section contains a textLabel displaying id of the currently logged in user.

In this tutorial, table layout will be used to design application screens. You can check this tutorial for the detailed explanation about how to use the table layout. The layout of this section can be expressed with the following table structure:

Layout of the header section

Before creating the panel for the header section, you will start by creating its sub-panels; the first one for the main menu and the second one for the child menu.

Creating Panel for the Main Menu

Open Formspider IDE and select SRDEMO from the “Application” combobox (note that the application is already created in the chapter 2). 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.

Creating a new panel

Enter “mainMenu” as the “Name” and “#e9e8e8” as “Background Color”. Since this menu should not be displayed initially on the login screen, uncheck the “Visible” checkBox. Click “OK” to create and open the panel in the editor.

Creating “mainMenu” panel

Add a hyperLink for each of the following menus: “My Service Requests”, “Advanced Search”, “New Service Request” and “Management”. Note that multilingual keys are used as the label values. You can find a detailed explanation about the multilingual keys and the internationalization infrastructure of the application in the chapter 4 of the tutorial.

The panel XML should look like:

<panel backgroundColor="#e9e8e8" visible="N">
  <tableLayout>
    <row name="mainRow">
      <cell name="serviceRequests" childWidth="120">
        <hyperLink font-style="Plain" font-size="11" text-align="Center" label="#{lang.srdemo.menu.my}"/>
      </cell>
      <cell name="advancedSearch" childWidth="120">
        <hyperLink font-style="Plain" font-size="11" text-align="Center" label="#{lang.srdemo.menu.advanced}"/>
      </cell>
      <cell name="newServiceRequest" childWidth="120">
        <hyperLink font-style="Plain" font-size="11" text-align="Center" label="#{lang.srdemo.menu.new}"/>
      </cell>
      <cell name="management" childWidth="120">
        <hyperLink font-style="Plain" font-size="11" text-align="Center" label="#{lang.srdemo.menu.manage}"/>
      </cell>
    </row>
  </tableLayout>
</panel>
Creating Panel for the Child Menu

Similarly to the main menu, each child menu will be implemented as a panel. Therefore if a parent menu item has a child menu that needs to be displayed, you have to create a separate panel for this child menu. You will create child menu panels in the future chapters of the tutorial, when it’s necessary. For now, create an empty child menu panel which will be used if a parent menu item is not selected yet or if the selected parent menu item has not any child menu.

Create a new panel, enter “emptyChildMenu” as the “Name” and “#0099cc” as “Background Color”. The panel XML should look like:

<panel backgroundColor="#0099cc"/>

You can now create the panel for the header section following its overview. Create a new panel, enter “mainPanel_header” as the “Name” and “White” as “Background Color”.

  1. Add an image component. The image component can display an image with the given URL or an image file that is locally stored in the middle-tier by using the relative path of the image file as the URL value. To display an image that is locally stored in the middle-tier:
    • Create a folder named “SRDEMO” under the “apps” folder existing in the middle-tier installation.
    • Under the “apps\SRDEMO” folder, create a new folder with a name of your choice (“images” for example).
    • Copy the “SRBranding.gif” image file under the “apps\SRDEMO\images” folder. Click here to download all images that are used in this application and copy these images under the “apps\SRDEMO\images” folder.

    Now you may use “./apps/SRDEMO/images/SRBranding.gif” as the URL value to display SRBranding.gif file through the image component.

  2. Add a button named “button_headerLogout”, a hyperLink named “hlink_headerLogout” and labeled “Logout”. The action that is specified for these components logs out the user from the application. Set the value of the icon attribute of the button component as “/apps/SRDEMO/images/logout.gif”, this attribute enables you to display the specified image file as the icon of your button. In fact, its usage is exactly same with the URL attribute of the image component. Since these two components should not be displayed initially (on the Login screen), enter “N” as the visible value for the both components.

    Add a button named “button_headerHelp”, a hyperLink named “hlink_headerHelp” and labeled “Help”. The action that is specified for these components displays the Help screen. Enter “/apps/SRDEMO/images/help.gif” as the icon value for the button component and “N” as visible value for the both components.

  3. Add two hyperLinks labeled “English” and “Italian”. The actions that are specified for these hyperlinks set the current language of the application.
  4. Include the “mainMenu” panel to this panel.
  5. Include the “emptyChildMenu” panel to this panel.
  6. Add a textLabel named “txtLabel_loggedUser” displaying id of the currently logged in user. Since it displays a dynamic value, its label will be set in run-time. Note that since this textLabel should be initially hidden (on the Login screen) 0 is specified as the height value of the row named “loggedUserInfoRow” containing this component.

The “mainPanel_header” panel can be represented with the table and XML below, note that green area represents empty cells.

Table representation of the “mainPanel_header”

<panel backgroundColor="White">
  <tableLayout>
    <row height="8"/>
    <row height="25">
      <!--1-->
      <cell rowSpan="3" hAlign="Left" vAlign="Center" childWidth="340" childHeight="69">
        <image url="./apps/SRDEMO/images/SRBranding.gif"/>
      </cell>
      <!--1-->
      <!--2.1-->
      <cell hAlign="Right" childWidth="23" childHeight="20">
        <button name="button_headerLogout" visible="N" backgroundColor="White" icon="/apps/SRDEMO/images/logout.gif"/>
      </cell>
      <!--2.1-->
      <!--2.2-->
      <cell width="42" hAlign="Left" childWidth="38">
        <hyperLink font-color="#003399" font-style="Plain" name="hlink_headerLogout" visible="N" label="#{lang.srdemo.menu.logout}"/>
      </cell>
      <!--2.2-->
      <!--2.3-->
      <cell width="26" hAlign="Right" childWidth="23" childHeight="20">
        <button name="button_headerHelp" visible="N" backgroundColor="White" icon="/apps/SRDEMO/images/help.gif"/>
      </cell>
      <!--2.3-->
      <!--2.4-->
      <cell width="30" hAlign="Full">
        <hyperLink font-color="#003399" font-style="Plain" name="hlink_headerHelp" visible="N" label="#{lang.srdemo.menu.help}"/>
      </cell>
      <!--2.4-->
      <!--empty cell-->
      <cell width="16"/>
      <!--empty cell-->
    </row>
    <row height="25">
      <!--3.1-->
      <cell columnSpan="2" hAlign="Full">
        <hyperLink font-color="Blue" font-style="Underlined" text-align="Right" label="#{lang.srheader.english}"/>
      </cell>
      <!--3.1-->
      <!--3.2-->
      <cell columnSpan="2" hAlign="Full">
        <hyperLink font-color="Blue" font-style="Underlined" text-align="Right" label="#{lang.srheader.italian}"/>
      </cell>
      <!--3.2-->
    </row>
    <row height="25" name="mainMenuRow">
      <!--4-->
      <cell columnSpan="4" hAlign="Right" vAlign="Full" name="mainMenuCell" childWidth="480">
        <include panelName="mainMenu"/>
      </cell>
      <!--4-->
    </row>
    <row height="2" name="childMenuRow">
      <!--5-->
      <cell columnSpan="6" hAlign="Full" vAlign="Full" name="childMenuCell">
        <include panelName="emptyChildMenu"/>
      </cell>
      <!--5-->
    </row>
    <row height="0" name="loggedUserInfoRow">
      <!--6-->
      <cell columnSpan="6" hAlign="Full">
        <textLabel font-size="16" name="txtLabel_loggedUser" text-align="Right"/>
      </cell>
      <!--6-->
    </row>
  </tableLayout>
</panel>

Footer Section Overview

The following screenshot depicts details of the footer section:

Footer Section

  1. The left side of this section contains a textLabel displaying the copyright information.
  2. The right side of this section contains a hyperlink labeled “About this sample”. The action that is specified for this hyperlink displays the about screen that will be implemented later.

Create a new panel, enter “mainPanel_footer” as the “Name” and “White” as “Background Color”. The panel XML should look like:

<panel backgroundColor="White">
  <tableLayout>
    <row height="10"/>
    <row height="0" name="footerRow">
      <!--1-->
      <cell hAlign="Full" vAlign="Full">
        <textLabel font-size="10" name="txtLabel_copyright" label="#{lang.srdemo.copyright}" text-align="Right"/>
      </cell>
      <!--1-->
      <cell width="12"/>
      <!--2-->
      <cell hAlign="Full" vAlign="Top" name="about">
        <hyperLink font-color="Blue" font-size="10" text-align="Left" label="#{lang.srdemo.about}"/>
      </cell>
      <!--2-->
    </row>
  </tableLayout>
</panel>

Note that since the textLabel and the hyperlink components should be initially hidden (on the Login screen) 0 is specified as the height value of the row named “footerRow” containing these two components.

Since the header and the footer sections are now implemented, it’s time to assemble them in the main panel. As mentioned before, Formspider automatically creates an empty panel named “mainPanel” when you create an application. Use this panel as the main panel of the application.

Expand the “Panels” node from the “Containers” tree and double click the “mainPanel” to open it in the editor.

  1. Enter “White” as the backgroundColor of the panel.
  2. As the header section, include the “mainPanel_header” panel to this panel.
  3. As the center section, add a table row containing an empty cell named “mainCenterCell”.
  4. Add a line using the line component.
  5. As the footer section, include the “mainPanel_footer” panel to this panel.

The “mainPanel” can be represented with the following table, note that green area represents empty cells.

Table representation of the “mainPanel”

<panel backgroundColor="White">
  <tableLayout>
    <row heightPolicy="Dynamic">
      <!--empty cell-->
      <cell width="10" rowSpan="5"/>
      <!--empty cell-->
      <!--1-->
      <cell>
        <include panelName="mainPanel_header"/>
      </cell>
      <!--1-->
      <!--empty cell-->
      <cell width="10" rowSpan="5"/>
      <!--empty cell-->
    </row>
    <!--2-->
    <row heightPolicy="Dynamic">
      <cell hAlign="Full" vAlign="Full" name="mainCenterCell"/>
    </row>
    <row height="13"/>
    <!--2-->
    <!--3-->
    <row height="2">
      <cell hAlign="Full" vAlign="Full">
        <line color="#0099cc"/>
      </cell>
    </row>
    <!--3-->
    <!--4-->
    <row name="footerRow">
      <cell hAlign="Full" vAlign="Top">
        <include panelName="mainPanel_footer"/>
      </cell>
    </row>
    <!--4-->
  </tableLayout>
</panel>

Login Screen Overview

Login is the first screen that displays automatically when the user first attempts to access the application. The following screenshot depicts details of the Login screen:

Login Screen

  1. There is a section containing two textLabels at the top of the screen.
    • The first textLabel represents the title of the screen, which is different for each screen.
    • The second textLabel represents the error message to be displayed when an invalid email id-password pair is provided by the user.

    This section will be called as the title section.

  2. There is a section containing “Email Id” and “Password” fields and a “Sign On” button at the bottom left of the screen. This section will be called as the login section.
  3. This section contains a textLabel displaying the demo message. It will be called as the information section.

Implementing the Login Screen

Implementing the Login screen compromises the creation of the necessary panels for the sections described above.

Login Section Overview

The following screenshot depicts details of the login section:

Login Section

  1. The top left cell contains a textLabel with the value “Your Mail Id:” serving as label for the cell in the right.
  2. The top right cell contains a textField component for entering the user id.
  3. The center left cell contains a textLabel with the value “Password:” serving as label for the cell in the right.
  4. The center right cell contains a passwordField for entering a password.
  5. The bottom right cell contains a button labeled “Sign On”. When pressed, the action specified for this button authenticates the user, displaying an error message described int the title section if unsuccessful.

The login section can be represented with the table below, note that green area represents the empty cell.

Table representation of the login section

Implementing the Login Section

Create a new panel, enter “SRWelcome_login” as the “Name” and “White” as “Background Color”. The panel XML should look like:

<panel backgroundColor="White">
  <tableLayout>
    <!-- Dummy row to adjust column widths -->
    <row height="0">
      <cell width="124"/>
      <cell width="192"/>
    </row>
    <row height="48"/>
    <row height="30">
      <!--1-->
      <cell hAlign="Left" vAlign="Center" childWidth="97" childHeight="19">
        <textLabel font-family="Serif" font-style="Bold" font-size="16" label="#{lang.srlogin.username}" text-align="Left"/>
      </cell>
      <!--1-->
      <!--2-->
      <cell hAlign="Left" vAlign="Center" childWidth="155" childHeight="22">
        <textField name="txtField_userName" autoComplete="Y"/>
      </cell>
      <!--2-->
    </row>
    <row height="30">
      <!--3-->
      <cell hAlign="Left" vAlign="Center" childWidth="97" childHeight="19">
        <textLabel font-family="Serif" font-style="Bold" font-size="16" label="#{lang.srlogin.password}" text-align="Left"/>
      </cell>
      <!--3-->
      <!--4-->
      <cell hAlign="Left" vAlign="Center" childWidth="155" childHeight="22">
        <passwordField name="passField_password"/>
      </cell>
      <!--4-->
    </row>
    <row height="30">
      <!--empty cell-->
      <cell/>
      <!--empty cell-->
      <!--5-->
      <cell hAlign="Left" vAlign="Center" childWidth="63" childHeight="22">
        <button label="#{lang.srlogin.signOn}"/>
      </cell>
      <!--5-->
    </row>
  </tableLayout>
</panel>

Note the “dummy” row added at the top of the panel:

    <!-- Dummy row to adjust column widths -->
    <row height="0">
      <cell width="124"/>
      <cell width="192"/>
    </row>

When using the table layout, it’s a best practice to add such a “dummy” row. This usage has the following advantages:

  • Enables other developers to quickly understand and recognize the layout of the panel.
  • Reduces repetitions and increases maintainability since the width value of the cells are only defined in a single row.
  • Simplifies editing the layout since the width value of the cells are only defined in a single row.

Implementing the Information Section

Create a new panel, enter “SRWelcome_info” as the “Name” and “White” as “Background Color”. This panel contains a single textLabel displaying the information message:

<panel backgroundColor="White">
  <tableLayout>
    <row heightPolicy="Dynamic">
      <cell hAlign="Full" vAlign="Full">
        <textLabel font-family="Serif" font-size="16" label="#{lang.srlogin.info}" text-align="Left"/>
      </cell>
    </row>
  </tableLayout>
</panel>

Since the header and the footer sections are now implemented, it’s time to assemble them in the login panel. The login screen can be represented with the table below:

Table representation of the login screen

Create a new panel, enter “SRWelcome” as the “Name” and “White” as “Background Color”.

  1. As the title section, add a textLabel with “Sign in to SRDemo” as the value, this textLabel is the title of the screen. Add a second textLabel with “Invalid User Id and Password” value, this textLabel is displayed when the provided email id-password pair is invalid.
  2. As the login section, include the “SRWelcome_login” panel to this panel.
  3. As the information section, include the “SRWelcome_info” panel to this panel.

The panel XML should look like:

<panel backgroundColor="White">
  <tableLayout>
    <!-- Dummy row to adjust column widths -->
    <row height="0">
      <cell width="318"/>
      <cell/>
    </row>
    <!--1-->
    <row height="83">
      <cell columnSpan="2" hAlign="Full" vAlign="Center" childHeight="37">
        <textLabel font-family="Serif" font-style="Bold" font-size="32" label="#{lang.srlogin.pageTitle}" text-align="Left"/>
      </cell>
    </row>
    <row height="10"/>
    <row height="0" name="errorMessageRow">
      <cell columnSpan="2" hAlign="Full" vAlign="Center" childHeight="23">
        <textLabel font-family="Serif" font-style="Bold" font-size="18" label="#{lang.srdemo.badLogin}" text-align="Left"/>
      </cell>
    </row>
    <row heightPolicy="Dynamic">
      <!--2-->
      <cell hAlign="Full" vAlign="Center">
        <include panelName="SRWelcome_login"/>
      </cell>
      <!--2-->
      <!--3-->
      <cell hAlign="Full" vAlign="Full">
        <include panelName="SRWelcome_info"/>
      </cell>
      <!--3-->
    </row>
    <row height="70"/>
  </tableLayout>
</panel>

Since the “SRWelcome” is the panel that should be displayed when the application is run, include this panel to the center section of the “mainPanel” (in the “mainCenterCell”) by editing its XML as follows:

<panel backgroundColor="White">
  <tableLayout>
    <row heightPolicy="Dynamic">
      <!--empty cell-->
      <cell width="10" rowSpan="5"/>
      <!--empty cell-->
      <!--1-->
      <cell>
        <include panelName="mainPanel_header"/>
      </cell>
      <!--1-->
      <!--empty cell-->
      <cell width="10" rowSpan="5"/>
      <!--empty cell-->
    </row>
    <!--2-->
    <row heightPolicy="Dynamic">
      <cell hAlign="Full" vAlign="Full" name="mainCenterCell">
        <include panelName="SRWelcome"/>
      </cell>
    </row>
    <row height="13"/>
    <!--2-->
    <!--3-->
    <row height="2">
      <cell hAlign="Full" vAlign="Full">
        <line color="#0099cc"/>
      </cell>
    </row>
    <!--3-->
    <!--4-->
    <row name="footerRow">
      <cell hAlign="Full" vAlign="Top">
        <include panelName="mainPanel_footer"/>
      </cell>
    </row>
    <!--4-->
  </tableLayout>
</panel>

Expand the “Windows” node and then the “Mainframe” node from the “Containers” tree. Double click the “mainFrame” node to open it in the editor. Set “Y” as the maximizeOnStartUp value to automatically maximize the mainFrame window when the application is started, “White” as backgroundColor value and “N” as titleBarVisible value to hide the title bar of the window:

<mainframe backgroundColor="White" title="SRDEMO" width="500" height="500" maximizeOnStartUp="Y" titleBarVisible="N">
  <borderLayout>
    <cell docking="Center">
      <include panelName="mainPanel"/>
    </cell>
  </borderLayout>
</mainframe>

Testing

Press “Run on Web” button to run the application, the login screen is displayed. Resize the browser window, note that since you use the table layout to design the screens, Formspider table layout manager preserves the ratios between the areas that the UI components cover.

1680x1050

1280x1024

1024x768

800x600

The screen designed with table layout works in all screen resolutions without any effort required from the developer. Note how the message displayed in the information section of the login screen dynamically breaks into multiple lines following the screen size and how the textLabels displaying at the top right of the screen preserve their relative positions.

Summary

In this chapter you started implementing the application screens by building the main layout and creating the login screen using table layout. You performed the following key tasks:

  • Implemented the main layout
  • Implemented the login screen
  • Tested the implemented screen
  • Claudio Arriagada

    Thanks for include this example in the learning centes. For sure it will be very helpfull for as.