The Google picker is a "File Open" dialog for the information stored on Google Drive. The Google picker has these features:
- A similar look-and-feel to the Google Drive UI.
- Several views showing previews and thumbnails of Drive files.
- An inline, modal window, so users never leave the main application.
Application requirements
Applications using the Google picker must abide by all existing Terms of Service. Most importantly, you must correctly identify yourself in your requests.
Enable the Google Picker API
To get started using Google Picker API, you need to first use the setup tool, which guides you through creating a project in the Google API Console, enabling the API, and creating credentials.
If you haven't done so already, create your application's API key by clicking Create credentials > API key. Next, look for your API key in the API keys section.
If you haven't done so already, create your OAuth 2.0 credentials by clicking
Create credentials > OAuth client ID. After you've created the
credentials, you can see your client ID on the Credentials page. Click
the client ID for details, such as client secret, redirect URIs, JavaScript
origins address, and email address. Your application
must send an OAuth 2.0 token when creating a Picker
object with views that accesses
private user data.
Display the Google picker
The remainder of this guide covers how to load and display the Google picker from a Web app. To view the complete example, navigate to the Google Picker example.Load the Google Picker library
To load the Google Picker library, call gapi.load()
with the library name and a
callback function to invoke after a successful load:
// Use the API Loader script to load google.picker and gapi.auth. function onApiLoad() { gapi.load('auth2', onAuthApiLoad); gapi.load('picker', onPickerApiLoad); } </script> <!-- Load the Google API Loader script. --> <script type="text/javascript" src="https://apis.google.com/js/api.js?onload=onApiLoad"></script>
The onApiLoad()
function loads the authentication and Google Picker libraries. The
onPickerApiLoad()
callback function is called after the Google Picker library
successfully loads.
Implement the successful load callback function
The onPickerApiLoad()
callback function sets a flag to indicate that the Picker
library has successfully loaded. Then onPickerApiLoad
calls the
createPicker
function to create and display the Google Picker:
function onPickerApiLoad() { pickerApiLoaded = true; createPicker(); }
Display the Google Picker
The createPicker()
function checks to ensure the Google Picker API finished loading
and that an oauthToken is created. Then, this function creates a new instance of the Google Picker
and displays it:
// Create and render a Picker object for selecting from Google Drive function createPicker() { if (pickerApiLoaded && oauthToken) { var picker = new google.picker.PickerBuilder(). addView(google.picker.ViewId.DOCS). setOAuthToken(oauthToken). setDeveloperKey(developerKey). setCallback(pickerCallback). build(); picker.setVisible(true); } } }
To create a Picker instance, you must provide a View
, an oauthToken
, a
developerKey
, and a callback function to call upon success
(pickerCallback
).
A Picker
renders one view at a time. Specify at least one view,
either by ID (google.picker.ViewId.*
) or by creating an instance of a
type (google.picker.*View
). Specify the view by type for additional
control over how that view is rendered.
If more than one view is added to the Google Picker, users switch from one view to another by
clicking a tab on the left. Tabs can be logically grouped with ViewGroup
objects.
Implement the Picker callback
A Picker callback can be used to react to user interactions in the Google Picker, such as selecting a file or pressing Cancel.
// A simple callback implementation. function pickerCallback(data) { var url = 'nothing'; if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) { var doc = data[google.picker.Response.DOCUMENTS][0]; url = doc[google.picker.Document.URL]; } var message = 'You picked: ' + url; document.getElementById('result').innerHTML = message; }
The callback receives a JSON-encoded data
object. This object contains any
actions the user performs with the Google Picker (google.picker.Response.ACTION
).
If the user selects an item, the google.picker.Response.DOCUMENTS
array is also
populated. In this example the google.picker.Document.URL
is shown on the main page.
For details about the data fields, refer to the JSON Guide.
Filter specific file types
Use view groups as a way of filtering out specific items. In the following example, the "Google Drive" sub-view shows only documents and presentations.
var picker = new google.picker.PickerBuilder(). addViewGroup( new google.picker.ViewGroup(google.picker.ViewId.DOCS). addView(google.picker.ViewId.DOCUMENTS). addView(google.picker.ViewId.PRESENTATIONS)). setOAuthToken(oauthToken). setDeveloperKey(developerKey). setCallback(pickerCallback). build();
Tune the Google Picker's appearance
Use the PickerBuilder.enableFeature()
function to fine-tune the appearance of the
Google Picker window. For instance, if you only have a single view, you may want to hide the
navigation pane to give users more space to see items. Here's an example of a spreadsheets
search picker demonstrating this feature:
var picker = new google.picker.PickerBuilder(). addView(google.picker.ViewId.SPREADSHEETS). enableFeature(google.picker.Feature.NAV_HIDDEN). setDeveloperKey(developerKey). setCallback(pickerCallback). build();
Render the Google picker in other languages
Specify the UI language by providing the locale to the PickerBuilder
instance
using the setLocale(locale)
method. The following is a French example:
var picker = new google.picker.PickerBuilder(). addView(google.picker.ViewId.IMAGE_SEARCH). setLocale('fr'). setDeveloperKey(developerKey). setCallback(pickerCallback). build();
The following is the list of locales currently supported:
af am ar bg bn ca cs |
da de el en en-GB es es-419 |
et eu fa fi fil fr fr-CA |
gl gu hi hr hu id is |
it iw ja kn ko lt lv |
ml mr ms nl no pl pt-BR |
pt-PT ro ru sk sl sr sv |
sw ta te th tr uk ur |
vi zh-CN zh-HK zh-TW zu |
Google Picker example
Following is the entire Google Picker example:
The following picker example illustrates an image selector/uploader page that could be opened
from an Open or Upload Drive files button in a web app. This example demonstrates
how to set the AppId
value, and incorporates some useful picker features such as
enabling multi-select, hiding the navigation pane, and choosing the user account with the app's
current OAuth 2.0 token:
The AppId
and the client ID, used for authorizing access to a user's files, must
be contained in the same app. Within the API Console,
AppId can be identified as the "Project number" on the "IAM & Admin" > "Settings" page,
in the developer console.
After obtaining the file ID from the picker when opening files, an application can then fetch the file metadata and download the file content as described in the reference documentation for files.get.