Action: ADD_FROM_CONTACT

ADD_FROM_CONTACT action allows you to select a pre-existing contact from your mobile device’s contact list. This action is used when your app wants to read the contact details and use it for its own purpose.

Attributes Value Mandatory
action_name ADD_FROM_CONTACT Yes
event_list comma separated list of events, eg: TAP Yes

How to use ADD_FROM_CONTACT?

  • Call this action on the screen which has some fields that can be filled from the device’s contact list
  • Add the user permission in the AndroidManifest.xml (For Android only)
<uses-permission android:name="android.permission.READ_CONTACTS" />

Once the action ADD_FROM_CONTACT is called, it invokes the contact list application. Once the contact is selected by the user, the contact list closes itself exposing your application’s screen that started the contact list application. This screen receives all the contact details passed to it from the contact list application just like the NEXT_SCREEN action passes data from one screen to next screen. See List of attributes for contact list application.

The AVM also calls an event ON_PICK_CONTACT. You can associate an action with this event to save the contact details to local database (using action EXECUTE_SQL) or to remote server (using action CALL_URL).

<action action_name="EXECUTE_SQL" event_list="ON_PICK_CONTACT"
    target="insert into user (name, address_home_street, address_home_city, address_home_state, address_home_postalCode, phone_Mobile) values (<name>, <address_home_street>, <address_home_city>, <address_home_state>, <address_home_postalCode>, <phone_Mobile>)"
    input_parameter_list="name, address_home_street, address_home_city, address_home_state, address_home_postalCode, phone_Mobile"/>

Example below shows the form in which the contact information is to be filled, a PUSHBUTTON control, tapping on which ADD_FROM_CONTACT is invoked and action defined on screen.

<screen name="add_from_contact" screen_type="SCREEN" width="100.0" height="100.0" scroll="VERTICAL"
    on_resume_update="true" >
<!-- this can be uncommented if you have a table called user with the columns in the query below.
    <actions>
        <action action_name="EXECUTE_SQL" event_list="ON_PICK_CONTACT"
               target="insert into user (name, street_home_address, city_home_address, address_home_state, address_home_postal_code, phone_mobile, phone_work_Fax, home_email, other_website_url) values (&lt;name>, &lt;address_home_street&gt;, &lt;address_city&gt;, &lt;address_state&gt;, &lt;address_postal_code&gt;, &lt;phone_mobile&gt;, &lt;phone_work Fax&gt;, &lt;email_home&gt;, &lt;website_url_other&gt;)"
            input_parameter_list="name, address_home_street, address_home_city, address_home_state, address_home_postal_code, phone_mobile, phone_work Fax, email_home, website_url_other"/>
    </actions>
-->
        <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="TEXT" appearance_name="black" x="2.0" y="4.0" width="29.0" height="8.0" default_value="Name"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="4.0" width="60.0" height="8.0"
                    field_name="name" keyboard_type="CAPS_WORDS" size="80" />
        <control type="TEXT" appearance_name="black" x="2.0" y="12.0" width="29.0" height="8.0" default_value="Street"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="12.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="20.0" width="29.0" height="8.0" default_value="City"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="20.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="28.0" width="29.0" height="8.0" default_value="State"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="28.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="36.0" width="29.0" height="8.0" default_value="Zip"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="36.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="44.0" width="29.0" height="8.0" default_value="Phone"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="44.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="52.0" width="29.0" height="8.0" default_value="Fax"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="52.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="60.0" width="29.0" height="8.0" default_value="Email"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="60.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="68.0" width="29.0" height="8.0" default_value="Website"/>
        <control type="EDIT" appearance_name="black_white_background" x="32.0" y="68.0" width="60.0" height="8.0"
            field_name="website_url_other" keyboard_type="EMAIL_ADDRESS" permission="READWRITE" size="80" />
        <control type="PUSHBUTTON" appearance_name="blue_button" x="5.0" y="78.0" width="90.0" height="8.0"
            default_value="Add from contacts">
            action action_name="ADD_FROM_CONTACT" event_list="TAP"/>
        </control>
    </controls>
</screen>

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

../_images/add_from_contact_form.png ../_images/emulator_contacts.png ../_images/add_from_contact_form_filled.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.

Reference tutorial

This chapter uses source code from 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.

Good Read

ADD_TO_CONTACT

List of attributes for contact list application

Attribute Value
prefix_name Prefix of the contact’s name (for ex. Mr., Ms, Dr.)
given_name First Name of the contact
family_name Last Name / Surname of the contact
display_name First_Name Last_Name
middle_name Middle name of the contact’s name
name First_Name Last_Name
suffix_name Suffix of the contact’s name (for ex. Jr., II)
home_phone Home Phone
mobile_phone Mobile Phone
work_phone Work Phone
work_fax_phone Work Fax
home_fax_phone Home Fax
pager_phone Pager
other_phone Other
callback_phone Callback
car_phone Car
company_main_phone Company Main
isdn_phone ISDN
main_phone Main
other_fax_phone Other Fax
radio_phone Radio
telex_phone Telex
tty_tdd_phone TTY TDD
work_mobile_phone Work Mobile Phone
work_pager_phone Work Pager Phone
assistant_phone Assistant Phone
mms_phone MMS Phone
custom_email Custom Email
home_email Home Email
work_email Work Email
other_email Other Email
mobile_email Mobile Email
po_box_home_address PO Box (Home Address)
street_home_address Street (Home Address)
city_home_address City (Home Address)
state_home_address State (Home Address)
postal_code_home_address Zip (Home Address)
country_home_address Country (Home Address)
po_box_work_address PO Box (Work Address)
street_work_address Street (Work Address)
city_work_address City (Work Address)
state_work_address State (Work Address)
postal_code_work_address Zip (Work Address)
country_work_address Country (Work Address)
po_box_other_address PO Box (Other Address)
street_other_address Street (Other Address)
city_other_address City (Other Address)
state_other_address State (Other Address)
postal_code_other_address Zip (Other Address)
country_other_address Country (Other Address)
po_box_custom_address PO Box (Custom Address)
street_custom_address Street (Custom Address)
city_custom_address City (Custom Address)
state_custom_address State (Custom Address)
postal_code_custom_address Zip (Custom Address)
country_custom_address Country (Custom Address)
company_name_work Name of the company (Work)
title_at_work Title at company (Work)
department_name_work Department Name (Work)
job_description_work Job Description (Work)
office_location_work Office Location (Work)
company_name_other Name of the company (Other)
title_at_other Title at company (Other)
department_name_other Department Name (Other)
job_description_other Job Description (Other)
office_location_other Office Location (Other)
company_name_custom Name of the company (Custom)
title_at_custom Title at company (Custom)
department_name_custom Department Name (Custom)
job_description_custom Job Description (Custom)
office_location_custom Office Location (Custom)
anniversary_date Anniversary Date
birthday_date BirthDate
custom_date Custom Date
other_date Other Date
homepage_url URL (HomePage)
blog_url URL (Blog)
profile_url URL (Profile)
home_url URL (Home)
work_url URL (Work)
ftp_url URL (FTP)
other_url URL (Other)