|
| 1 | +OneNotePickerLibrary for Android README |
| 2 | +================================ |
| 3 | + |
| 4 | +### Version info |
| 5 | +Version 1.0 |
| 6 | + |
| 7 | +###Android requirements for using the library |
| 8 | +--------------- |
| 9 | +* JDK 1.6 or higher |
| 10 | +* Works on Android 2.2 (Froyo) and higher |
| 11 | +* Targeted for Android 4.4 (KitKat) |
| 12 | +* INTERNET permissions in AndroidManifest.xml |
| 13 | + |
| 14 | +### Prerequisites |
| 15 | + |
| 16 | +**Tools and Libraries** you will need to download, install, and configure for your development environment to use the OneNotePickerLibrary. |
| 17 | + |
| 18 | +Be sure to verify the prerequisites for these too. |
| 19 | + |
| 20 | +* [Google Android Developer Tools bundle](http://developer.android.com/sdk/index.html) |
| 21 | +* [JDK 1.6 or higher](http://www.oracle.com/technetwork/java/javase/downloads/index.html) |
| 22 | + |
| 23 | +**Accounts** |
| 24 | + |
| 25 | +* As the user, you'll need to [have a Microsoft account](http://msdn.microsoft.com/EN-US/library/office/dn575426.aspx) |
| 26 | +so your project can authenticate with the [Microsoft Live connect SDK](https://github.com/liveservices/LiveSDK-for-Android). |
| 27 | + |
| 28 | +###Reference the Library |
| 29 | + |
| 30 | +To compile the source code,... |
| 31 | + |
| 32 | +* Download the repo as a ZIP file to your local computer, and extract the files. Or, clone the repository into a local copy of Git. |
| 33 | +* Start Eclipse, if it is not already running. |
| 34 | +* Choose "File > Import." |
| 35 | +* Expand "Android." Choose "Existing Android Code into Workspace," and then click "Next." |
| 36 | +* Choose "Browse" to select a root directory. |
| 37 | +* Go to and select this folder within the downloaded project files, and then click "OK." |
| 38 | +* In the **Projects** box, make sure both the "OneNotePickerLib" and "android-support-v7-appcompat" projects are selected. |
| 39 | +* Make sure that the "Copy projects into workspace" check box is selected. Click "Finish." |
| 40 | + Eclipse adds both projects to the **Package Explorer** pane and then |
| 41 | + compiles the library in the background. |
| 42 | +* You can now reference the compiled library from your Eclipse Android projects. |
| 43 | + |
| 44 | + |
| 45 | +To reference the compiled library in an Eclipse Android project,... |
| 46 | + |
| 47 | +* In Eclipse, display the **Package Explorer** pane, if it is not already visible. |
| 48 | +* Right-click your project's name, and then choose "Properties." |
| 49 | +* In the list of project properties, choose "Android." |
| 50 | +* In the Library area, click "Add." |
| 51 | +* Click "OneNotePickerLib" and then click "OK." |
| 52 | +* Click "OK." Eclipse sets a reference to the compiled library source code |
| 53 | + project, and you can now call the "OneNotePickerActivity" from your own |
| 54 | + Android project. |
| 55 | + |
| 56 | +**Note**: Before you run your project, you must add the Internet permission to your |
| 57 | + project's manifest, as shown in the following steps. If you don't add the |
| 58 | + Internet permission, your app may have problems accessing OneNote |
| 59 | + web services. |
| 60 | + |
| 61 | +To add the Internet permission to your project's manifest,... |
| 62 | + |
| 63 | +* Make sure that your project is open. In the **Package Explorer** pane, open the AndroidManifest.xml file. |
| 64 | +* In the editor, click the **Permissions** tab. |
| 65 | +* Choose "Add." |
| 66 | +* Choose "Uses Permission," and then click "OK." |
| 67 | +* In the "Name" list, choose "android.permission.INTERNET." |
| 68 | +* Save the AndroidManifest.xml file. |
| 69 | + |
| 70 | +### Using the library |
| 71 | + |
| 72 | +The **OneNotePickerLibrary** provides a class called **OneNotePickerActivity.class** that extends Activity. You implement this class with an [Intent](http://developer.android.com/reference/android/content/Intent.html). To handle return values from this class, you need to implement the [onActivityResult](http://developer.android.com/reference/android/app/Activity.html) method. |
| 73 | + |
| 74 | +####Input |
| 75 | + |
| 76 | +Specify the required and optional properties for the **OneNotePickerActivity.class** by setting these "extras" by using the **putExtra** method on the **Intent**: |
| 77 | + |
| 78 | +* **ACCESS_TOKEN** (Required): A **String** that specifies the access token to be used for authentication. See [Authenticate the user for the OneNote API](http://msdn.microsoft.com/en-us/library/office/dn575435(v=office.15).aspx) to learn how to authenticate your product. |
| 79 | +* **NAV_TEXT_COLOR** (Optional): A **Color** object that specifies the color of the properties in the action bar (the text, back arrow, and cancel button). If this is not set, then the default color will be used. |
| 80 | +* **THEME_COLOR** (Optional): An **Enum** value (**OneNotePickerThemeColor.LIGHT** and **OneNotePickerThemeColor.DARK**) that specifies the light or dark theme. |
| 81 | + |
| 82 | +####Output |
| 83 | + |
| 84 | +The activity returns a **resultCode** of either RESULT\_OK, when the user successfully selects a section or RESULT\_CANCELLED when the user either cancels the operation or the operation fails due to an error. |
| 85 | + |
| 86 | +When the **resultCode** value is RESULT\_OK, the **OneNotePickerActivity** class returns the following values through the **getExtras** method on the **data** object returned by your implementation of the **onActivityResult(int requestCode, int resultCode, Intent data)** method: |
| 87 | + |
| 88 | +* **SECTION_ID**: A **String** that specifies the ID of the selected section. |
| 89 | +* **SECTION_NAME**: A **String** that specifies the name of the selected section. |
| 90 | +* **PAGES_URL**: A **URL** that specifies the REST URL to use to create or get pages in the selected section. |
| 91 | +* **CREATED_TIME**: A **Date** object that specifies the date/time when the selected section was created. |
| 92 | +* **MODIFIED_TIME**: A **Date** object that specifies the date/time when any page in the selected section was last modified. |
| 93 | +* **LAST_MODIFIED_BY**: A **String** that specifies the name of the user who last modified any page in the selected section. |
| 94 | + |
| 95 | +When the **resultCode** value is RESULT\_CANCELLED, the **OneNotePickerActivity** class returns a Boolean value for USER\_CANCELLED through the **getExtras** method on the **data** object returned by your implementation of **onActivityResult**. This means that the user has cancelled the operation by using the back arrow or the cancel button. |
| 96 | + |
| 97 | +If the value of USER\_CANCELLED is false, the class also returns a Boolean value for API\_ERROR. If the value of API\_ERROR is true, the OneNote API has returned an error code and information about the error. |
| 98 | + |
| 99 | +When the value for API_ERROR is true, the **OneNotePickerActivity** class returns the following values: |
| 100 | + |
| 101 | +* **API\_ERROR_CODE**: A **String** that specifies the value of the error code returned by the OneNote API. See [OneNote API error and warning codes](http://msdn.microsoft.com/en-us/library/office/dn750990(v=office.15).aspx) for a list of possible error codes. |
| 102 | +* **API\_ERROR_URL**: A **URL** that specifies the value of the explanatory error URL returned by the OneNote API. |
| 103 | +* **API\_ERROR_STRING**: A **String** that contains a description of the error. |
| 104 | + |
| 105 | +If the value of API\_ERROR is false, the platform has thrown an exception because of an error that originates on the device. In this case, the **OneNotePickerActivityClass** returns an **Exception** object. |
| 106 | + |
| 107 | +When the values for USER\_CANCELLED and API_ERROR are both false, the **OneNotePickerActivity** class returns an exception through the following value: |
| 108 | + |
| 109 | +* **SYSTEM_EXCEPTION**: An **Exception** object returned by the platform due to an error on the device. |
| 110 | + |
| 111 | +####Example |
| 112 | + |
| 113 | +The following example shows how to create a new **Intent** with the **OneNotePickerActivity** class, set the required and optional values, and handle errors and exceptions that might be returned: |
| 114 | + |
| 115 | + private void pickOneNoteSection() { |
| 116 | + |
| 117 | + //Create Intent |
| 118 | + Intent oneNotePickerIntent = new Intent(this, OneNotePickerActivity.class); |
| 119 | + |
| 120 | + //Set Properties |
| 121 | + |
| 122 | + oneNotePickerIntent.putExtra("ACCESS_TOKEN", "<Insert OAuth Ticket>"); |
| 123 | + oneNotePickerIntent.putExtra("NAV_TEXT_COLOR", new Color().rgb(128,57,123)); |
| 124 | + |
| 125 | + //Start Picker - Assumes that a value for "REQUEST_CODE" has already been set |
| 126 | + |
| 127 | + startActivityForResult(oneNotePickerIntent, REQUEST_CODE); |
| 128 | + |
| 129 | + } |
| 130 | + |
| 131 | + @Override |
| 132 | + |
| 133 | + protected void onActivityResult(int requestCode, int resultCode, Intent data) { |
| 134 | + |
| 135 | + //PICKER COMPLETES WITH SELECTED SECTION |
| 136 | + |
| 137 | + |
| 138 | + if (resultCode == RESULT_OK && requestCode == REQUEST_CODE) { |
| 139 | + |
| 140 | + //LOAD VALUES |
| 141 | + |
| 142 | + String sectionID = data.getExtras().getString("SECTION_ID"); |
| 143 | + String sectionName = data.getExtras().getString("SECTION_NAME"); |
| 144 | + URL pagesURL = (URL)data.getExtras().get("PAGES_URL"); |
| 145 | + Date createdTime = (Date)data.getExtras().get("CREATED_TIME"); |
| 146 | + Date modifiedTime = (Date)data.getExtras().get("MODIFIED_TIME"); |
| 147 | + String lastModifiedBy = data.getExtras().getString("LAST_MODIFIED_BY"); |
| 148 | + |
| 149 | + //DO SOMETHING WITH THE INFO |
| 150 | + |
| 151 | + } |
| 152 | + |
| 153 | + //PICKER CANCELLED OR generated an error |
| 154 | + |
| 155 | + else if (resultCode == RESULT_CANCELLED && requestCode == REQUEST_CODE){ |
| 156 | + |
| 157 | + if(data.getExtras().getBoolean("USER_CANCELLED")){ |
| 158 | + |
| 159 | + //USER CANCELLED OPERATION. |
| 160 | + |
| 161 | + } |
| 162 | + |
| 163 | + else if(data.getExtras().getBoolean("API_ERROR")){ |
| 164 | + |
| 165 | + //API BASED ERROR. LOAD ERROR INFO |
| 166 | + |
| 167 | + String apiErrorCode = data.getExtras().getString("API_ERROR_CODE"); |
| 168 | + String apiErrorString = data.getExtras().getString("API_ERROR_STRING"); |
| 169 | + URL apiErrorURL = (URL)data.getExtras().get("API_ERROR_URL"); |
| 170 | + |
| 171 | + //DO SOMETHING WITH ERROR INFO |
| 172 | + |
| 173 | + } |
| 174 | + |
| 175 | + else { |
| 176 | + |
| 177 | + //SYSTEM EXCEPTION. LOAD EXCEPTION |
| 178 | + |
| 179 | + Exception e = (Exception)data.getExtras().get("SYSTEM_EXCEPTION"); |
| 180 | + |
| 181 | + //HANDLE EXCEPTION |
| 182 | + |
| 183 | + } |
| 184 | + } |
| 185 | + } |
| 186 | + |
| 187 | +### OneNote API functionality used by this library |
| 188 | + |
| 189 | +The following aspects of the API are used in this library. You can |
| 190 | +find additional documentation at the links below. |
| 191 | + |
| 192 | +* [GET notebooks to which the user has access](http://msdn.microsoft.com/en-us/library/office/dn769050(v=office.15).aspx) |
| 193 | +* [GET section groups to which the user has access](http://msdn.microsoft.com/en-us/library/office/dn769052(v=office.15).aspx) |
| 194 | +* [GET a specific section group to which the user has access](http://msdn.microsoft.com/en-us/library/office/dn770192(v=office.15).aspx) |
| 195 | +* [GET sections to which the user has access](http://msdn.microsoft.com/en-us/library/office/dn769049(v=office.15).aspx) |
| 196 | +* [GET a specific section to which the user has access](http://msdn.microsoft.com/en-us/library/office/dn770191(v=office.15).aspx) |
0 commit comments