Tutorial 5 How to create a form and store data locally on the device

What you will learn in this Tutorial

Define User Interface of a form

Data sourcing for the form

Actions EXECUTE_SQL, NEXT_SCREEN, CLOSE_SCREEN

Download Source Code - Tutorials - Source for this tutorial is in``appemble-tutorial-form``
Learn more FAQ
Good Read Tutorial - How to add validation function in a form?
Reference EDIT control - Keyboard types , actions

Introduction

In this tutorial you will learn about how to create a form screen, create data source for the form, get user input, save data to a local device database by attaching an action to a control. The example used for this tutorial is a signup and profile forms. A form consists of TEXT controls which are used as labels. It consists of EDIT controls which are used for getting user data. It has pushbuttons to which actions are attached. In this tutorial, you will learn about EXECUTE_SQL, NEXT_SCREEN and CLOSE_SCREEN actions which are attached to pushbuttons. You will also get a glimpse of how to concatenate actions.

Android

../_images/empty_regform_small.png ../_images/regform_small1.png ../_images/profile_small.png

iOS

../_images/iOS_emptyform.png ../_images/ios_formfilled1.png ../_images/ios_profile.png

The form tutorial will teach you about Appemble methodology of developing an app which is to:

  1. Define UI
  2. Data source
  3. Attach actions and events

Define User Interface of a form

In the sample registration form in the fig shown above, there are 4 TEXT controls - First Name, Last Name, Email and Password. There are 4 EDIT controls for the user to enter data and there is one PUSHBUTTON control to save user data.

Create regform.xml

Step 1. Define control type="TEXT" for labels First Name, Last Name, Email, Password. In the attribute default_value, give the text to be displayed on the screen. For example default_value="First Name"

<control name=”labelfirstname” type=”TEXT” x=”2” y=”3” width=”30” height=”8”
appearance_name=”black” data_type=”VARCHAR” default_value="First Name"/>

Note

PASSWORD field is an edit field but displays ** instead of the actual letters. This is done by defining the control type=”PASSWORD”

Step 2. Define control type="EDIT" for each field in which the user can enter data. It is a good practice to have opaque appearance for EDIT control. appearance name is defined in the appearance.xml

<control name=”editfirstname” type=”EDIT” x=”35” y=”2” width=”50” height=”8”

appearance_name="edit_box" data_type=”VARCHAR” field_name=”firstname” default_value=”” size=”80” keyboard_type=”CAP_WORDS”/>

Note: keyboard_type=”CAP_WORDS” is used to have first letter of the word as Upper case.

Step 3. Define control type="PUSHBUTTON". In the default_value the display of the button can be set to Save

<control name=”savebutton” type=”PUSHBUTTON” x=”10” y=”50” width=”80” height=”10”
appearance_name=”blue_button” data_type=”VARCHAR” word_wrap=”1” default_value=”Save and display values in Profile” >

UI definition for the form is now complete. Next set the data sourcing for the form.

Data sourcing for the form

Data sourcing means defining the data flow in your mobile app. Learn more about data sourcing.

Step 1. Create a table called user_details in yourproject/assets/yourproject-content.sqlite

CREATE TABLE [user_details] (
[lastname] VARCHAR(50), [firstname] VARCHAR(50), [email] VARCHAR(80), [password] VARCHAR(30));

Step 2. Control type="EDIT" has an attribute called field_name. Whenever dynamic or user input data needs to be stored or retrieved, this attribute is used. Value of field_name for “EDIT” control corresponds to the field name in the database table. For example:

<control name=”editfirstname” type=”EDIT” .................``field_name=”firstname”`` />

Now define field_name attribute for each EDIT control in the form.

Step 3. Save the data to user_details table. This action is initiated by pushing the PUSHBUTTON. See details in the next section.

Actions EXECUTE_SQL, NEXT_SCREEN, CLOSE_SCREEN

In this tutorial, on press of PUSHBUTTON, 3 actions are executed.

  1. Insert user input data to the user_details table - This is done by using EXECUTE_SQL action which allows using a query to operate on data
  2. Go to next screen called Profile - This is done by using NEXT_SCREEN action which allows you to navigate from one screen to the other.
  3. Close the current registration screen - This is done using CLOSE_SCREEN action which initiates closing of a screen. CLOSE_SCREEN removes the screen from the application stack exposing the underlying screen.

Actions are nested in this example. When one action is complete, the next action is executed.

<control type="PUSHBUTTON"............default_value="Save and display values in Profile"....>
     <actions>
    <action action_name="EXECUTE_SQL" target="sql query" input_parameter_list="field1, field2..">
        <action action_name="NEXT_SCREEN" target="userprofile"...>
            <action action_name="CLOSE_SCREEN"/>
        </action>
     </action>
     </actions>
</control>

Source code for form tutorial

regform.xml

<screens>
    <screen name="regform" screen_type="SCREEN" initial_layout="PORTRAIT"
            allowed_layouts="BOTH" scroll="VERTICAL" width="100" height="100">
        <title_controls>
            <control type="TEXT" x="0" y="1" width="100" height="6"
                    default_value="Sample Registration Form"
                    appearance_name="white" data_type="VARCHAR">
            </control>
        </title_controls>
        <controls>
            <control name="labelfirstname" type="TEXT" x="2" y="3"
                    width="30" height="8"
                    appearance_name="black" data_type="VARCHAR"
                    default_value="First Name"/>
            <control name="editfirstname" type="EDIT" x="35" y="2"
                    width="50" height="8"
                    appearance_name="edit_box" data_type="VARCHAR"
                    field_name="firstname"
                    default_value="" size="80"
                    keyboard_type="CAP_WORDS"/>
            <control name="labellastname" type="TEXT" x="2" y="12"
                    width="30" height="8"
                    appearance_name="black" data_type="VARCHAR"
                    default_value="Last Name"/>
            <control name="editlastname" type="EDIT" x="35" y="12"
                    width="50"
                    height="8" appearance_name="edit_box"
                    data_type="VARCHAR"
                    field_name="lastname"
                    default_value="" size="80"
                    keyboard_type="CAP_WORDS"/>
            <control name="labelemail" type="TEXT" x="2" y="22" width="30"
                    height="8" appearance_name="black"
                    data_type="VARCHAR"
                    default_value="Email"/>
            <control name="editemail" type="EDIT" x="35" y="22" width="50"
                    height="8" appearance_name="edit_box"
                    data_type="VARCHAR" field_name="email"
                    default_value="" size="80" hint="Enter email"
                    keyboard_type="EMAIL_ADDRESS"/>
            <control name="labelpassword" type="TEXT" x="2" y="32"
                    width="30" height="8"
                    appearance_name="black" data_type="VARCHAR"
                    default_value="Password"/>
            <control name="editpassword" type="PASSWORD" x="35" y="32"
                    width="50"
                    height="8" appearance_name="edit_box"
                    data_type="VARCHAR"
                    field_name="password" size="80"/>

            <control name="savebutton" type="PUSHBUTTON" x="10" y="50"
                    width="80" height="10"
                    appearance_name="blue_button" data_type="VARCHAR"
                    word_wrap="1"
                    default_value="Save and display values in Profile">
                <!-- attaching action to this control -->
                <actions>
                    <action event_list="TAP" action_name="EXECUTE_SQL"
                            target="insert into user_details(lastname,
                            firstname, email, password) VALUES
                            (&apos;&lt;lastname&gt;&apos;,&apos;&lt;
                            firstname&gt;&apos;,&apos;&lt;email&gt;&apos;
                            ,&apos;&lt;password&gt;&apos;)"
                            input_parameter_list="lastname, firstname,
                            email, password" >
                        <action event_list="TAP"
                                action_name="NEXT_SCREEN"
                                target="userprofile"
                                input_parameter_list="firstname,
                                lastname, email, password">
                            <action event_list="TAP"
                                    action_name="CLOSE_SCREEN"
                                    input_parameter_list="firstname,
                                    lastname,
                                    email, password" />
                        </action>
                    </action>
                </actions>
            </control>
            <control type="TEXT" x="2" y="70" width="96" height="10"
                    word_wrap="1"
                    appearance_name="black_ita" data_type="VARCHAR"
                    default_value="There is no validation for this
                sample registration form"/>
        </controls>
    </screen>
</screens>

The display properties of the text are determined by appearance_name. To define different appearances, create a new file or edit a file called “appearance.xml” in the app-def folder:

In appearance.xml, create a new appearance. This appearance name can be reused for any control in the app.

<appearances>
    <appearance name="black" font_family="Sans-Serif" font_name="Helvetica"
            font_size="3"
            font_color="#000000" background_color="#FFFFFF" alpha="0"
            justify="LEFT" />
    <appearance name="black_ita" font_family="Sans-Serif" font_name="Helvetica"
            font_size="2.5"
            font_color="#000000" background_color="#FFFFFF" alpha="0"
            justify="LEFT" font_style_italic="1"/>
    <appearance name="white" font_family="Sans-Serif" font_name="Helvetica"
            font_size="3"
            font_color="#FFFFFF" background_color="#000000" alpha="0"
            justify="CENTER" font_style_bold="1"
            font_style_emboss="1"/>
    <appearance name="edit_box" font_family="Sans-Serif" font_name="Helvetica"
            font_size="3"
            font_color="#000000" background_color="#FFFFFF" alpha="255"
            justify="LEFT" />
    <appearance name="blue_button" font_family="Sans-Serif" font_name="Helvetica"
            font_size="3"
            font_color="#FFFFFF" background_color="#009AD9" alpha="255"
            justify="CENTER" font_style_bold="1"/>
    <appearance name="grey_button" font_family="Sans-Serif" font_name="Helvetica"
            font_size="3"
            font_color="#000000" background_color="#FFFFFF" alpha="255"
            justify="CENTER" font_style_bold="1"/>
</appearances>

Now declare that regform screen is the first screen to be displayed. This is declared in a file in your app-def folder called application.xml

<screen_deck name="form_tutorial" version="1.0"
        short_description="Form Tutorial app"
        long_description="Form Tutorial app" size="1024"
        publisher_name="Appemble"
        publish_date="2012-09-27" starting_screen_name="regform"
        background="tu_background.png"
        title_background="tu_titlebar.png"/>

Also create profile screen. You can learn how to retrieve data from the data table user_details and allow the user to change user data input before.

<screens>
    <screen name="userprofile" screen_type="SCREEN" initial_layout="PORTRAIT"
            allowed_layouts="BOTH" scroll="VERTICAL"
            width="100" height="100" local_data_source="select lastname, firstname,
        email, password from user_details where email=&apos;&lt;email&gt;&apos;" >
        <title_controls>
            <control type="TEXT" x="0" y="1" width="100" height="6"
                    default_value="Profile"
                    appearance_name="white" data_type="VARCHAR">
            </control>
        </title_controls>

        <controls>
            <control name="labelfirstname" type="TEXT" x="2" y="3" width="30"
                    height="8"
                    appearance_name="black" data_type="VARCHAR"
                    default_value="First Name"/>
            <control name="editfirstname" type="EDIT" x="35" y="2" width="50"
                    height="8"
                    appearance_name="edit_box" data_type="VARCHAR"
                    field_name="firstname"
                    default_value="" size="80"/>
            <control name="labellastname" type="TEXT" x="2" y="12" width="30"
                    height="8"
                    appearance_name="black" data_type="VARCHAR"
                    default_value="Last Name"/>
            <control name="editlastname" type="EDIT" x="35" y="12" width="50"
                    height="8"
                    appearance_name="edit_box" data_type="VARCHAR"
                    field_name="lastname"
                    default_value="" size="80"/>
            <control name="labelemail" type="TEXT" x="2" y="22" width="30"
                    height="8"
                    appearance_name="black" data_type="VARCHAR"
                    default_value="Email"/>
            <control name="editemail" type="TEXT" x="35" y="22" width="50"
                    height="8"
                    appearance_name="black" data_type="VARCHAR"
                    field_name="email"
                    default_value="" size="80"/>
            <control name="labelpassword" type="TEXT" x="2" y="32" width="30"
                    height="8"
                    appearance_name="black" data_type="VARCHAR"
                    default_value="Password"/>
            <control name="editpassword" type="PASSWORD" x="35" y="32"
                    width="50" height="8"
                    appearance_name="edit_box" word_wrap="0" data_type="VARCHAR"
                    field_name="password"
                    default_value="" size="80"/>

            <control name="savebutton" type="PUSHBUTTON" x="20" y="50"
                    width="30" height="10"
                    appearance_name="blue_button" data_type="VARCHAR"
                    default_value="Update" >
                <!-- attaching action to this control -->
                <actions>
                    <action event_list="TAP" action_name="EXECUTE_SQL"
                            target="update user_details SET lastname=&apos;&lt;lastname&gt;
                        &apos;, firstname=&apos;&lt;firstname&gt;&apos;, password=&apos;
                        &lt;password&gt;&apos; where email=&apos;&lt;email&gt;&apos;"
                            input_parameter_list="lastname, firstname, email, password" >
                        <action event_list="TAP" action_name="NEXT_SCREEN"
                                target="profilesaved">
                            <action event_list="TAP" action_name="CLOSE_SCREEN"/>
                        </action>
                    </action>
                </actions>
            </control>
            <control name="cancelbutton" type="PUSHBUTTON" x="55" y="50"
                    width="30" height="10"
                    appearance_name="grey_button" data_type="VARCHAR"
                    default_value="Cancel" >
                <actions>
                    <action event_list="TAP" action_name="NEXT_SCREEN"
                            target="regform">
                        <action event_list="TAP" action_name="CLOSE_SCREEN"/>
                    </action>
                </actions>
            </control>
        </controls>
    </screen>
</screens>

userprofile screen has cancel button and update button. When Update is tapped the user data is saved back to the data table and you go to profilesaved screen.

profilesaved.xml

<screens>
    <screen name="profilesaved" screen_type="SCREEN"
            initial_layout="PORTRAIT"
            allowed_layouts="BOTH" scroll="VERTICAL"
            width="100" height="100" >
        <title_controls>
            <control type="TEXT" x="0" y="1" width="100"
                    height="6" default_value="Profile Updated"
                    appearance_name="white" data_type="VARCHAR">
            </control>
        </title_controls>

        <controls>
            <control type="TEXT" x="10" y="10" width="80"
                    height="8" permission="READONLY"
                    appearance_name="black" word_wrap="1"
                    data_type="VARCHAR"
                    default_value="Your Profile has been updated successfully!"/>
            <control type="PUSHBUTTON" x="35" y="40" width="30"
                    height="10" permission="READONLY"
                    appearance_name="blue_button" data_type="VARCHAR"
                    default_value="Back" >
                <!-- attaching action to this control -->
                <actions>
                    <action event_list="TAP" action_name="NEXT_SCREEN"
                            target="regform">
                        <action event_list="TAP" action_name="CLOSE_SCREEN"/>
                    </action>
                </actions>
            </control>
        </controls>
    </screen>
</screens>

Now your app is ready for launch.

Android - Right click on the project and click on Run as Android application.

iOS - Click on Product -> Run.

Download and Run Tutorials

This chapter uses source code from appemble-tutorial-form. If you have not downloaded tutorial source code, click on Download Source Code - Tutorials

Android - Right click on appemble-tutorial-form and click on Run as Android application.

iOS - Select scheme appemble-tutorial-form and iPhone x.x simulator. Click on Product -> Run.

FAQ

Can I save the form values to a remote server?

Yes, that can be certainly done. Upon tap of a save button, the action CALL_URL can be called which can take the data from the form and send it as an HTTP request to the remote server. A custom function can also be written to make the HTTP call, receive the server response and even display it back to the user.

How can I validate user input?

User input can be validated by writing custom function. Custom functions are written in the native language that is for Android they will be written in Java. A Tutorial - How to add validation function in a form? is a good start for knowing more.

Is it possible to display a different keyboard for email address?

Yes you can associate a keyboard type to every edit field. The list of supported keyboard type can be read in the reference section EDIT control - Keyboard types .

What are concatenated or nested actions?

At times, it is required that more than one action is to be performed on an event. For instance in this tutorial, the screen “userprofile” has a push button titled “Save and display values in Profile”. There are two actions associated with it. The first one is EXECUTE_SQL which saves the user input to the data table. Then it calls the action NEXT_SCREEN to display the Profile screen. The NEXT_SCREEN is called only if the action EXECUTE_SQL returns true. In case the SQL query fails the action NEXT_SCREEN will not be called.

What is the purpose of CLOSE_SCREEN action?

The action CLOSE_SCREEN simply removes the screen from the application stack exposing the underlying screen.

Can I define more two or more actions as peers?

Yes you can define two actions as peers. So upon receiving the event, both actions will be triggered. The second action would not wait for the completion of the first one, nor its execution will be depend on the return value of the first action.