Gallery Picker

Kapost have added the ability to convert and embedded gallery link into a file picker for integrators. This should be useful in situations where kapost content/assets need to be used outside of Kapost.

Gallery URL changes

In order to make use of this new functionality the embedded gallery URL needs to have the picker query param added ie. ?embedded=true&picker=true.

Integrating the Gallery Picker

JS Helper Class

Integrators will need to add the following script on any page that needs the Gallery Picker.

<script src="https://<subdomain>.kapost.com/gallery/gallery_picker.js" type="text/javascript"></script>

Using Helper Class

The most likely scenario is that you will open the Gallery Picker using a button/link. In this element's click handler you will need to do something like the following.

$(document).ready(() => {
  $("#open-gallery").on("click", (e) => {
    e.preventDefault();

    // Callback that is triggered when selection is sent from Gallery Picker. This will be called multiple times
    // if the multiselect option is used.
    const callback = (payload) => {
      // The payload shape is as follows:
      // {
      //   id: String,
      //   title: String,
      //   kapostUrl: String,
      //   downloadUrl: String,
      //   mediaUrl: String,
      //   publishedUrls: Array[Object({
      //     external_site_name: String,
      //     published_url: String,
      //     draft: Boolean,
      //     scheduled_date: Timestamp,
      //     published_date: Timestamp,
      //     platform: String,
      //     external_id: String,
      //     metadata_only: Boolean,
      //   })],
      //   initiatives: Array[Object({
      //     id: String,
      //     name: String,
      //     newsroom_id: String,
      //     start_date: Timestamp,
      //     end_date: Timestamp,
      //     created_at: Timestamp,
      //     updated_at: Timestamp,
      //   })],
      //   customFields: Object({ "Field Name": mixed })
      // }

      // Do somthing with payload ...
    };

    // Gallery URL to populate the Gallery Picker.
    const galleryUrl = "https://<subdomain>.kapost.com/gallery/collections/<collectionId>";
    // This informs the picker if it needs to allow multiple selections.
    const allowMultiselect = true;

    if (window._galleryPicker && !window._galleryPicker.closed) {
      // If there is already a gallery picker window open we want to just show that again.
      window._galleryPicker.focus();
    } else {
      // Instantiate the Gallery Picker. The last argument defaults to false which creates a single select picker.
      const picker = new GalleryPicker(galleryUrl, callback, allowMultiselect);

      // This allows us to refocus and existing picker that may have lost focus and prevents multiple
      // handlers being created/triggered.
      window._galleryPicker = picker.open();
    }   
  });
});

Demo

You can try the gallery picker out using the demo here.