PicaFinna

A zero-dependency image picker component for image materials in Finna.fi using the Finna API.

Browser compatibility IE9+ and modern browsers.

Demo: haltu.github.io/picafinna

Usage

Include picafinna.css and picafinna.js in your page.

<link rel="stylesheet" href="picafinna.css" />
<script src="picafinna.js" async></script>

Call the picker and get back the details of the image the user selected.

PicaFinna.pickImage(function handleResult (imageObj) {
  console.log(imageObj);
  // { title: '...', url: '...', pageUrl: '...', licenseDescription: '...' }
});

You can also get a new instance of PicaFinna for custom options.

var picker = new PicaFinna({
  zIndex: 10000,
  locale: 'en'
});

// Prevent parent element from scrolling
document.body.style.overflow = 'hidden';

picker.pickImage(function handleResult (imageObj) {
  console.log(imageObj);
  document.body.style.overflow = '';
});

Options

• zIndex  —  Number
  • Default value: 1000.
  • zIndex of the main element in modal mode.
• imageMaxDimensions  —  Object
  • Default value: {width: 1200, height: 1200}.
  • Maximum dimensions for the returned image.
• locale  —  String
  • Default value: 'fi'.
  • Choices: 'fi', 'en'.
  • Language of the picker UI. Image details, for example license descriptions, will still be in Finnish.
• parentElement  —  Element
  • Default value: document.body.
  • Override the parent element for the picker. Can be useful if you are implementing a custom inline picker.
• documentOverride  —  Document
  • Default value: document.
  • Override the document object for the picker.
• resultsPerPage  —  Number
  • Default value: 15.
  • Allowed values: 0 - 100.
  • Search results to show per page.
• searchDebounceTime  —  Number
  • Default value: 400.
  • The duration before the search is triggered after typing into the search field.
• useJsonp  —  Boolean
  • Default value: true.
  • If true JSONP is used instead of XMLHttpRequest. Currently the API does not support CORS.

Methods

picker.pickImage( callback, initialQuery )

Allow the user to pick an image and call the callback with the results.

Parameters

• callback  —  function
• initialQuery  —  string
  • Optional.

Callback parameters

• imageObj  —  object
  • Properties:
    • title  —  Title of the image
    • url  —  URL to the image file
    • pageUrl  —  URL to detail page
    • licenseDescription  —  License information

Examples

picker.pickImage(handleResult, 'kissa');
function handleResult (imageObj) {
  console.log(imageObj);
  // { title: '...', url: '...', pageUrl: '...', licenseDescription: '...' }
}

PicaFinna.pickImage( callback, options )

Create a new instance with options and call pickImage on it. initialQuery can be passed as an option.

Parameters

• callback  —  function
• options  —  object
  • Optional.

Callback parameters

• imageObj  —  object
  • Properties:
    • title  —  Title of the image
    • url  —  URL to the image file
    • pageUrl  —  URL to detail page
    • licenseDescription  —  License information

Examples

PicaFinna.pickImage(handleResult, {initialQuery: 'kissa'});
function handleResult (imageObj) {
  console.log(imageObj);
  // { title: '...', url: '...', pageUrl: '...', licenseDescription: '...' }
}

picker.cancelPick()

Cancel the pick action and call the callback with no result.

Examples

picker.cancelPick();

picker.showPicker()

Make the picker visible.

Examples

picker.showPicker();

picker.hidePicker()

Make the picker hidden.

Examples

picker.hidePicker();

picker.resetPicker()

Reset existing picker instance to a clean state.

Examples

picker.resetPicker();

picker.setPage( page )

Move to the given page number, or to the next or previous page.

Parameters

• page  —  number / 'next' / 'prev'

Examples

picker.setPage('next');

License

Copyright © 2016 Haltu Oy. Licensed under the MIT license.