Tutorial 11 - How to interact with device Contact List

What you will learn in this Tutorial

How to use ADD_TO_CONTACT action

How to use ADD_FROM_CONTACT action

Download Source Code - Tutorials - Source for this tutorial is in appemble-tutorial-actions
Reference Actions, ADD_TO_CONTACT action, ADD_FROM_CONTACT action

Introduction

Add_TO_CONTACT action is used to allow the user to add the contact info from your app to the phone contact list. ADD_FROM_CONTACT action is used to allow the user to add contact from device contact list to the your app.

How to use ADD_TO_CONTACT action

ADD_TO_CONTACT action invokes phone contact application and displays the values from the app in the new contact form of the contact application. On pressing Done, the contact is added to the contact list. target_parameter_list attribute gives the information that can will be added to the contact.

Lets create a screen phone_actions.xml, which takes name and phone number as input. Tapping on a button invokes ADD_TO_CONTACT action.

 <screen name="phoneactions" screen_type="SCREEN" allow_reorientation="true" allowed_layouts="BOTH" scroll="VERTICAL"
         width="100" height="100" menuOrder="0" menuName="Phone" tab_group_name="tabgroup1">
         <title_controls>
                 <control type="TEXT" x="0" y="1" width="100" height="6" default_value="Test Actions"
                          appearance_name="white" data_type="VARCHAR">
                 </control>
             </title_controls>
         <controls>
                 <control type="TEXT" x="2" y="24" width="25" height="8" appearance_name="black" data_type="VARCHAR"
                                  default_value="Display Name" word_wrap="1"/>
                 <control type="EDIT" x="35" y="24" width="60" height="8" appearance_name="edit_box" data_type="VARCHAR" field_name="name"
                                  size="80" keyboard_type="CAP_WORDS"/>
                 <control type="TEXT" x="2" y="34" width="30" height="8" appearance_name="black" data_type="VARCHAR"
                                  default_value="Phone" keyboard_type="PHONE"/>
                 <control type="EDIT" x="35" y="34" width="60" height="8" appearance_name="edit_box" data_type="VARCHAR"
                          field_name="phone_no_to_add" size="80" keyboard_type="PHONE"/>
                 <control type="PUSHBUTTON" x="35" y="44" width="60" height="8" appearance_name="blue_button" data_type="VARCHAR"
                                  default_value="ADD_TO_CONTACT">
                                 <actions>
                                              <action event_list="TAP" action_name="ADD_TO_CONTACT"
                                                      target="" input_parameter_list="name,phone_no_to_add" target_parameter_list="display_name, home_phone"/>
                                         </actions>
                         </control>
     </controls>
 </screen>

Note

target_parameter_list=”display_name, home_phone” (This is mandatory and cannot be changed). In this tutorial, name and home phone are the parameters being added. You can create a form with more fields corresponding to target_parameter_list supported. See ADD_TO_CONTACT attributes and values.

You can test the action using appemble-tutorial-actions. If you have not downloaded tutorial source code, click on Download Source Code - Tutorials

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

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

Enter the name and phone number and tap on button ADD_TO_CONTACT. It invokes the contact application with the values for new contact pre-filled. Click on Done and the contact will be added to the device contact list.

The figure on left shows the form where the user enters the information. On tapping the ADD_TO_CONTACT button, the contact app is invoked. The image shown below is generated from Android Simulator.

../_images/add_tocontact2.png ../_images/add_tocontact11.png

iOS

On tapping the ADD_TO_CONTACT button, the contact app is invoked and All Contacts screen is displayed. Tapping on Cancel will bring you back to the your app. To check the contact details, you will have to open your Contacts app and tap on the contact you added. You will see the name and phone number displayed as per the user data added in the form.

../_images/ios_addtocontactform1.png ../_images/ios_contactinfo1.png

How to use ADD_FROM_CONTACT action

ADD_FROM_CONTACT action invokes phone contact application and displays contact list. On selecting the contact, it captures the information and sends it to your app. In the tutorial, a form is created. When ADD_FROM_CONTACT is invoked and contact selected, the form in the app is populated with the contact values. See the List of attributes for contact list application.

Note

The field_name in your form / data tables MUST match the contact list attributes. For example field_name=”phone_home”, field_name=”name_display”

Lets create a file - add_from_contact.xml

 <screen name="add_from_contact" screen_type="SCREEN" width="100.0" height="100.0" scroll="VERTICAL" >
    <title_controls>
        <control type="PUSHBUTTON" appearance_name="blue_button_small" x="0.0" y="1" width="16.0" height="7.0"
            default_value="Done">
            <action action_name="CLOSE_SCREEN" event_list="TAP" />
        </control>
        <control type="TEXT" x="0" y="1" width="100" height="6" default_value="ADD_FROM_CONTACT Action"
            appearance_name="white" data_type="VARCHAR"/>
    </title_controls>
    <controls>
        <control type="PUSHBUTTON" appearance_name="blue_button" x="5.0" y="2.0" width="90.0" height="8.0"
                         default_value="Add from contacts">
                         <action action_name="ADD_FROM_CONTACT" event_list="TAP"/>
        </control>
        <control type="TEXT" appearance_name="black" x="2.0" y="12.0" width="29.0" height="8.0" default_value="Name"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="12.0" width="60.0" height="8.0"
                    field_name="name_display" keyboard_type="CAPS_WORDS" permission="READWRITE" size="80" />
        <control type="TEXT" appearance_name="black" x="2.0" y="20.0" width="29.0" height="8.0" default_value="Street"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="20.0" width="60.0" height="8.0"
            field_name="address_home_street" keyboard_type="CAPS_WORDS" permission="READWRITE" size="80" />
        <control type="TEXT" appearance_name="black" x="2.0" y="28.0" width="29.0" height="8.0" default_value="City"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="28.0" width="60.0" height="8.0"
            field_name="address_home_city" keyboard_type="CAPS_WORDS" permission="READWRITE" size="80" />
        <control type="TEXT" appearance_name="black" x="2.0" y="36.0" width="29.0" height="8.0" default_value="State"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="36.0" width="60.0" height="8.0"
            field_name="address_home_state" keyboard_type="CAP_CHARACTERS" permission="READWRITE" size="80" />
        <control type="TEXT" appearance_name="black" x="2.0" y="44.0" width="29.0" height="8.0" default_value="Zip"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="44.0" width="60.0" height="8.0"
            field_name="address_home_postal_code" keyboard_type="PHONE" permission="READWRITE" size="80" />
        <control type="TEXT" appearance_name="black" x="2.0" y="52.0" width="29.0" height="8.0" default_value="Phone"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="52.0" width="60.0" height="8.0"
            field_name="phone_home" keyboard_type="PHONE" permission="READWRITE" size="80" />
        <control type="TEXT" appearance_name="black" x="2.0" y="60.0" width="29.0" height="8.0" default_value="Fax"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="60.0" width="60.0" height="8.0"
            field_name="phone_home_fax" keyboard_type="PHONE" permission="READWRITE" size="80" />
        <control type="TEXT" appearance_name="black" x="2.0" y="68.0" width="29.0" height="8.0" default_value="Email"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="68.0" width="60.0" height="8.0"
            field_name="email_home" keyboard_type="EMAIL_ADDRESS" permission="READWRITE" size="80" />
        <control type="TEXT" appearance_name="black" x="2.0" y="76.0" width="29.0" height="8.0" default_value="Website"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="76.0" width="60.0" height="8.0"
            field_name="website_url_homepage" keyboard_type="EMAIL_ADDRESS" permission="READWRITE" size="80" />
    </controls>
</screen>

Test the action using appemble-tutorial-actions. If you have not downloaded tutorial source code, click on Download Source Code - Tutorials

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

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

Tap on Add from Contacts button. It will invoke the contact application. Select the contact. You should see your form filled in.

The figure on left shows the form with filled values after tapping Add from cantacts button.

../_images/add_from_contact_form1.png ../_images/emulator_contacts1.png ../_images/add_from_contact_form_filled1.png

Note

Only those values that exist in the contact application for the selected contact will be displayed. For example if for the selected user, only name and phone number have values, then the form in the application will display only those fields filled. Rest of the fields will be empty.