Aller au contenu

Embed the file-picker in your site

To embed the File-picker, you have to use an <iframe> tag:

<iframe
  src="https://filepicker.cernbox.cern.ch/?origin=https://mysite.cern.ch"
></iframe>

The source URL is https://filepicker.cernbox.cern.ch, and it must be passed an origin query parameter containing the URL of the iframe parent.

Warning

Remember, you have to specify the protocol (usually https://) in the origin.

This enables the iframe to check it against a list of approved sites before setting it as targetOrigin argument of the postMessage the File-picker does. Otherwise if the parent is vulnerable the iframe could be hijacked and the message captured, including the user token.

By default anything under cern.ch is allowed. Outside sources can open an issue requesting addition to the whitelist.

Operation modes

There are two ways to use the File-picker, depending on the value of the locationPicker search parameter.

File selector

This mode allows users to select files from their storage and then sends the selection to the parent application. This selection can be sent as a URL or a public link.

This is the default mode and there is no configuration setting for it.

URL sharing

By default, the File-picker will send the files' URL to the parent application, along with an authentication token to enable the download. This token is usually short lived, therefore this mode is more suited for downloading the selected files straight away after the user has made the selection (for example to copy them to the parent application's backend).

Alternatively, the File-picker can generate public links for the selected files and send them to the parent application. This can be enabled by passing the publicLink=1 parameter. These links will be valid in the longer term, and so they can be used to link files somewhere without copying them. The duration of the links can be adjusted with the publicLinkDuration, in days. These public links will have the internal flag set (so they are not visible in ownCloud web), and can be given a description via the description parameter.

Keep in mind

If the owner of the file deletes or moves it, the public link will stop being valid. This is especially important if you plan to have long-term access to the files.

Location selector

This mode allows users to select a path inside their storage for the parent application to upload files into it.

The File-picker will provide the parent application with authentication details along with the selected path.

Query parameters

The File-picker accepts the following parameters through the query string:

Name Description Values Default Required Example
origin URL of the iframe parent string Yes https://indico.cern.ch
locationPicker Show the location picker instead of the regular File-picker bool false No 1
style Style to apply to the File-picker light \| dark \| indico light No light
startPath Start path for the File-picker browser, always starting with / (overriden by userHome) string / No /aFolder/subFolder
userHome Whether the File-picker should start the browser in the user home folder (takes precedence over startPath) bool true No 0

The following parameters are only relevant when using the regular File-picker, not locationPicker.

Name Description Values Default Required Example
publicLink If true, the File-picker will generate public links for the shared files bool false No 1
publicLinkDuration If publicLink is true, number of days links will be valid before expiry number 0 No 30
publicLinkDescription Description for the public link string No CodiMD
mimeTypes A url-encoded, comma-separated list of MIME types to filter the contents of the user storage string No image%2Fjpeg%2Cimage%2Fsvg%2Bxml