Item picker
Embed a box where the user picks one or more Items from Drive, and receive the Items that were picked.
The Item picker widget lists the Items in Drive for the user to choose from. When the user confirms, the widget sends the chosen Items to your page. The rest of the contract (credential, error) is in Widgets.
URL and parameters
The URL is <site>/widgets/item-picker. Every parameter is optional. A boolean is written true or false. A list is separated by commas.
| Parameter | Meaning |
|---|---|
single_select | true allows one Item only. Default false. |
types | Show only Items with these type values, for example folder,form. |
subtypes | Show only Items with these subtype values, for example table. |
selectable_types | Only these type values can be picked. The others are greyed out. Without it every type can be picked. |
selectable_subtypes | Only these subtype values can be picked, in the same way. |
disabled_items | The ids of Items that are shown but cannot be picked. |
default_parent | The id of the folder that opens first. Without it, My Drive. |
path_navigation | false stops the user from changing folder. Default true. |
importable | true allows only Items that data can be imported into. Default false. |
The user can also pick the folder that is open, when no Item is ticked and that folder can be picked under selectable_types and selectable_subtypes.
Messages
| action | Direction | Payload |
|---|---|---|
select | widget to your page | { items }, an array of the picked Items. Each has _id, name, type, subtype, parent, owner, permission, props and the other fields of an Item. |
cancel | widget to your page | None. Sent when the user closes the box or cancels. |
This widget takes no post-widget-parameters, so it sends no ready.
If the user picks the open root of My Drive, items holds one entry that has no _id, only a name that is translated to the language. To stop the root from being picked, set selectable_types to types that are not folders.
Example
Continuing the example in Widgets, change the widget name to item-picker, add the picker's parameters, and listen for select.
// add to URLSearchParams: single_select: 'true', selectable_types: 'form'
addEventListener('message', (e) => {
if (e.origin !== site || e.data.messageToken !== messageToken) return
if (e.data.action === 'select') {
const ids = e.data.payload.items.map((item) => item._id)
frame.remove()
}
if (e.data.action === 'cancel') frame.remove()
})Notes
- A greyed row is an Item that cannot be picked, because it does not match
selectable_typesorselectable_subtypesor is indisabled_items. A folder that does not match can still be opened, unless it is indisabled_items. selectdoes not close the iframe. Your page removes it.