Added help menu options to People app

This has been implemented with the idea to enable the creation of help
menu options in a standard way throughout the Android platform.  One
particularly important feature is to hide the exact URL that is being
used to invoke the help pages via the browser via using vendor-specific
overlays of string resources.

Also, other standard context for the help like the preferred language and
app version code are incorporated automatically via the HelpUtils function.

Bug:6206323
Change-Id: I5a1fff4d99ac93d3a6aa05da91f465fad072cb8a

9 files changed, 208 insertions, 9 deletions

diff --git a/res/menu-sw580dp-w720dp/people_options.xml b/res/menu-sw580dp-w720dp/people_options.xml
index 6974d8035..cb65cc893 100644
--- a/res/menu-sw580dp-w720dp/people_options.xml
+++ b/res/menu-sw580dp-w720dp/people_options.xml
@@ -44,15 +44,21 @@
 
     <item
         android:id="@+id/menu_clear_frequents"
+        android:orderInCategory="3"
         android:title="@string/menu_clear_frequents" />
 
     <item
         android:id="@+id/menu_accounts"
-        android:orderInCategory="3"
+        android:orderInCategory="4"
         android:title="@string/menu_accounts" />
 
     <item
         android:id="@+id/menu_settings"
-        android:orderInCategory="4"
+        android:orderInCategory="5"
         android:title="@string/menu_settings" />
+
+    <item
+        android:id="@+id/menu_help"
+        android:orderInCategory="6"
+        android:title="@string/menu_help" />
 </menu>
diff --git a/res/menu-sw580dp/people_options.xml b/res/menu-sw580dp/people_options.xml
index 07d9c949b..42c47497b 100644
--- a/res/menu-sw580dp/people_options.xml
+++ b/res/menu-sw580dp/people_options.xml
@@ -47,15 +47,21 @@
 
     <item
         android:id="@+id/menu_clear_frequents"
+        android:orderInCategory="3"
         android:title="@string/menu_clear_frequents" />
 
     <item
         android:id="@+id/menu_accounts"
-        android:orderInCategory="3"
+        android:orderInCategory="4"
         android:title="@string/menu_accounts" />
 
     <item
         android:id="@+id/menu_settings"
-        android:orderInCategory="4"
+        android:orderInCategory="5"
         android:title="@string/menu_settings" />
+
+    <item
+        android:id="@+id/menu_help"
+        android:orderInCategory="6"
+        android:title="@string/menu_help" />
 </menu>
diff --git a/res/menu/edit_contact.xml b/res/menu/edit_contact.xml
index 93c19dc3b..51d9ab0c5 100644
--- a/res/menu/edit_contact.xml
+++ b/res/menu/edit_contact.xml
@@ -32,4 +32,8 @@
         android:id="@+id/menu_discard"
         android:alphabeticShortcut="q"
         android:title="@string/menu_discard" />
+
+    <item
+        android:id="@+id/menu_help"
+        android:title="@string/menu_help" />
 </menu>
diff --git a/res/menu/people_options.xml b/res/menu/people_options.xml
index 4003038e9..8c91e88b3 100644
--- a/res/menu/people_options.xml
+++ b/res/menu/people_options.xml
@@ -51,4 +51,8 @@
     <item
         android:id="@+id/menu_settings"
         android:title="@string/menu_settings" />
+
+    <item
+        android:id="@+id/menu_help"
+        android:title="@string/menu_help" />
 </menu>
diff --git a/res/values/donottranslate_config.xml b/res/values/donottranslate_config.xml
index b36dbe1b4..d3b742019 100644
--- a/res/values/donottranslate_config.xml
+++ b/res/values/donottranslate_config.xml
@@ -130,4 +130,17 @@
          Setting this flag to false in a resource overlay allows you to
          entirely disable SIM import on a per-product basis. -->
     <bool name="config_allow_sim_import">true</bool>
+
+
+    <!-- Help URL pointing to main TOC for People. This is intentionally empty because
+         the overlay will fill this in during build time. -->
+    <string name="help_url_people_main"></string>
+
+    <!-- Help URL pointing to adding contacts in People. This is intentionally empty because
+         the overlay will fill this in during build time. -->
+    <string name="help_url_people_add"></string>
+
+    <!-- Help URL pointing to editing contacts in People. This is intentionally empty because
+         the overlay will fill this in during build time. -->
+    <string name="help_url_people_edit"></string>
 </resources>
diff --git a/res/values/strings.xml b/res/values/strings.xml
index c5d070343..b2480cd9b 100644
--- a/res/values/strings.xml
+++ b/res/values/strings.xml
@@ -1452,6 +1452,9 @@
     <!-- Menu item for the settings activity [CHAR LIMIT=64] -->
     <string name="menu_settings" msgid="377929915873428211">Settings</string>
 
+    <!-- Menu item for invoking contextual help [CHAR LIMIT=64] -->
+    <string name="menu_help">Help</string>
+
     <!-- The preference section title for contact display options [CHAR LIMIT=128] -->
     <string name="preference_displayOptions">Display options</string>
 
diff --git a/src/com/android/contacts/activities/PeopleActivity.java b/src/com/android/contacts/activities/PeopleActivity.java
index 0283e0677..eff3294a4 100644
--- a/src/com/android/contacts/activities/PeopleActivity.java
+++ b/src/com/android/contacts/activities/PeopleActivity.java
@@ -57,6 +57,7 @@ import com.android.contacts.preference.DisplayOptionsPreferenceFragment;
 import com.android.contacts.util.AccountFilterUtil;
 import com.android.contacts.util.AccountPromptUtils;
 import com.android.contacts.util.AccountsListAdapter;
+import com.android.contacts.util.HelpUtils;
 import com.android.contacts.util.UriUtils;
 import com.android.contacts.util.AccountsListAdapter.AccountListFilter;
 import com.android.contacts.util.Constants;
@@ -1395,6 +1396,7 @@ public class PeopleActivity extends ContactsActivity
         }
 
         final MenuItem clearFrequentsMenu = menu.findItem(R.id.menu_clear_frequents);
+        final MenuItem helpMenu = menu.findItem(R.id.menu_help);
 
         final boolean isSearchMode = mActionBarAdapter.isSearchMode();
         if (isSearchMode) {
@@ -1402,6 +1404,7 @@ public class PeopleActivity extends ContactsActivity
             addGroupMenu.setVisible(false);
             contactsFilterMenu.setVisible(false);
             clearFrequentsMenu.setVisible(false);
+            helpMenu.setVisible(false);
         } else {
             switch (mActionBarAdapter.getCurrentTab()) {
                 case TabState.FAVORITES:
@@ -1428,6 +1431,7 @@ public class PeopleActivity extends ContactsActivity
                     clearFrequentsMenu.setVisible(false);
                     break;
             }
+            HelpUtils.prepareHelpMenuItem(this, helpMenu, R.string.help_url_people_main);
         }
         final boolean showMiscOptions = !isSearchMode;
         makeMenuItemVisible(menu, R.id.menu_search, showMiscOptions);
diff --git a/src/com/android/contacts/editor/ContactEditorFragment.java b/src/com/android/contacts/editor/ContactEditorFragment.java
index 275a46362..2d61fbcb4 100644
--- a/src/com/android/contacts/editor/ContactEditorFragment.java
+++ b/src/com/android/contacts/editor/ContactEditorFragment.java
@@ -36,6 +36,7 @@ import com.android.contacts.model.EntityModifier;
 import com.android.contacts.model.GoogleAccountType;
 import com.android.contacts.util.AccountsListAdapter;
 import com.android.contacts.util.AccountsListAdapter.AccountListFilter;
+import com.android.contacts.util.HelpUtils;
 
 import android.accounts.Account;
 import android.app.Activity;
@@ -895,14 +896,31 @@ public class ContactEditorFragment extends Fragment implements
         // This supports the keyboard shortcut to save changes to a contact but shouldn't be visible
         // because the custom action bar contains the "save" button now (not the overflow menu).
         // TODO: Find a better way to handle shortcuts, i.e. onKeyDown()?
-        menu.findItem(R.id.menu_done).setVisible(false);
+        final MenuItem doneMenu = menu.findItem(R.id.menu_done);
+        final MenuItem splitMenu = menu.findItem(R.id.menu_split);
+        final MenuItem joinMenu = menu.findItem(R.id.menu_join);
+        final MenuItem helpMenu = menu.findItem(R.id.menu_help);
+
+        // Set visibility of menus
+        doneMenu.setVisible(false);
 
         // Split only if more than one raw profile and not a user profile
-        menu.findItem(R.id.menu_split).setVisible(mState != null && mState.size() > 1 &&
-                !isEditingUserProfile());
-        // Cannot join a user profile
-        menu.findItem(R.id.menu_join).setVisible(!isEditingUserProfile());
+        splitMenu.setVisible(mState != null && mState.size() > 1 && !isEditingUserProfile());
 
+        // Cannot join a user profile
+        joinMenu.setVisible(!isEditingUserProfile());
+
+        // help menu depending on whether this is inserting or editing
+        if (Intent.ACTION_INSERT.equals(mAction)) {
+            // inserting
+            HelpUtils.prepareHelpMenuItem(getActivity(), helpMenu, R.string.help_url_people_add);
+        } else if (Intent.ACTION_EDIT.equals(mAction)) {
+            // editing
+            HelpUtils.prepareHelpMenuItem(getActivity(), helpMenu, R.string.help_url_people_edit);
+        } else {
+            // something else, so don't show the help menu
+            helpMenu.setVisible(false);
+        }
 
         int size = menu.size();
         for (int i = 0; i < size; i++) {
diff --git a/src/com/android/contacts/util/HelpUtils.java b/src/com/android/contacts/util/HelpUtils.java
new file mode 100644
index 000000000..814e3abae
--- /dev/null
+++ b/src/com/android/contacts/util/HelpUtils.java
@@ -0,0 +1,141 @@
+/*
+ * Copyright (C) 2012 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.contacts.util;
+
+import android.content.Context;
+import android.content.Intent;
+import android.content.pm.PackageInfo;
+import android.content.pm.PackageManager.NameNotFoundException;
+import android.net.Uri;
+import android.text.TextUtils;
+import android.util.Log;
+import android.view.MenuItem;
+
+import java.util.Locale;
+
+/**
+ * Functions to easily prepare contextual help menu option items with an intent that opens up the
+ * browser to a particular URL, while taking into account the preferred language and app version.
+ */
+public class HelpUtils {
+    private final static String TAG = HelpUtils.class.getName();
+
+    /**
+     * Help URL query parameter key for the preferred language.
+     */
+    private final static String PARAM_LANGUAGE_CODE = "hl";
+
+    /**
+     * Help URL query parameter key for the app version.
+     */
+    private final static String PARAM_VERSION = "version";
+
+    /**
+     * Cached version code to prevent repeated calls to the package manager.
+     */
+    private static String sCachedVersionCode = null;
+
+    /** Static helper that is not instantiable*/
+    private HelpUtils() { }
+
+    /**
+     * Prepares the help menu item by doing the following.
+     * - If the string corresponding to the helpUrlResourceId is empty or null, then the help menu
+     *   item is made invisible.
+     * - Otherwise, this makes the help menu item visible and sets the intent for the help menu
+     *   item to view the URL.
+     *
+     * @return returns whether the help menu item has been made visible.
+     */
+    public static boolean prepareHelpMenuItem(Context context, MenuItem helpMenuItem,
+            int helpUrlResourceId) {
+        String helpUrlString = context.getResources().getString(helpUrlResourceId);
+        return prepareHelpMenuItem(context, helpMenuItem, helpUrlString);
+    }
+
+    /**
+     * Prepares the help menu item by doing the following.
+     * - If the helpUrlString is empty or null, the help menu item is made invisible.
+     * - Otherwise, this makes the help menu item visible and sets the intent for the help menu
+     *   item to view the URL.
+     *
+     * @return returns whether the help menu item has been made visible.
+     */
+    public static boolean prepareHelpMenuItem(Context context, MenuItem helpMenuItem,
+            String helpUrlString) {
+        if (TextUtils.isEmpty(helpUrlString)) {
+            // The help url string is empty or null, so set the help menu item to be invisible.
+            helpMenuItem.setVisible(false);
+
+            // return that the help menu item is not visible (i.e. false)
+            return false;
+        } else {
+            // The help url string exists, so first add in some extra query parameters.
+            final Uri fullUri = uriWithAddedParameters(context, Uri.parse(helpUrlString));
+
+            // Then, create an intent that will be fired when the user
+            // selects this help menu item.
+            Intent intent = new Intent(Intent.ACTION_VIEW, fullUri);
+            intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK
+                    | Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
+
+            // Set the intent to the help menu item, show the help menu item in the overflow
+            // menu, and make it visible.
+            helpMenuItem.setIntent(intent);
+            helpMenuItem.setShowAsAction(MenuItem.SHOW_AS_ACTION_NEVER);
+            helpMenuItem.setVisible(true);
+
+            // return that the help menu item is visible (i.e., true)
+            return true;
+        }
+    }
+
+    /**
+     * Adds two query parameters into the Uri, namely the language code and the version code
+     * of the app's package as gotten via the context.
+     * @return the uri with added query parameters
+     */
+    private static Uri uriWithAddedParameters(Context context, Uri baseUri) {
+        Uri.Builder builder = baseUri.buildUpon();
+
+        // Add in the preferred language
+        builder.appendQueryParameter(PARAM_LANGUAGE_CODE, Locale.getDefault().toString());
+
+        // Add in the package version code
+        if (sCachedVersionCode == null) {
+            // There is no cached version code, so try to get it from the package manager.
+            try {
+                // cache the version code
+                PackageInfo info = context.getPackageManager().getPackageInfo(
+                        context.getPackageName(), 0);
+                sCachedVersionCode = Integer.toString(info.versionCode);
+
+                // append the version code to the uri
+                builder.appendQueryParameter(PARAM_VERSION, sCachedVersionCode);
+            } catch (NameNotFoundException e) {
+                // Cannot find the package name, so don't add in the version parameter
+                // This shouldn't happen.
+                Log.wtf(TAG, "Invalid package name for context", e);
+            }
+        } else {
+            builder.appendQueryParameter(PARAM_VERSION, sCachedVersionCode);
+        }
+
+        // Build the full uri and return it
+        return builder.build();
+    }
+}