Library

With our library control, users can upload their own pictures, take photo with their webcam or pick from one of our selected photos. As a developer, you can also make use of our API to provide your own set of photos that the user can pick from.

Specifying a custom library provider

The LibraryProvider class is the data manager for our library feature. Extend this class in order to load data from an external source or provide a fixed set of images. Your custom provider needs to implement two functions: getCategories and searchImages(query) which will be invoked by the editor. Please note that these methods are asynchronous and must return a Promise.

getCategories

The getCategories function should return a Promise with an array of LibraryCategory classes. The name attribute of the class will be used as a key to group the images.

new LibraryCategory({
  // category name which will be displayed in the ui and used to group images: string
  name: "",
  // this can be an external URL, data-url or any other valid image.src string
  coverImageUrl: "",
});

searchImages

The searchImages function should return a Promise with an array of LibraryImage classes. The query argument can be used to filter the list based on the image title.

new LibraryImage({
  // image title: string
  title: "",
  // thumbnail image: this can be an external URL, data-url or any other valid image.src string
  thumbUrl: "",
  // image: this can be an external URL, data-url or any other valid image.src
  rawUrl: "",
  // name of the category: string, optional
  category: "",
  // the author name can be displayed in the AdvancedUI: string, optional
  authorName: "",
  // the author avatar can be displayed in the AdvancedUI: string, optional
  authorAvatar: "",
});

Example

import { LibraryProvider, LibraryCategory, LibraryImage } from "photoeditorsdk";

class MyProvider extends LibraryProvider {
  /**
   * This is a method explicitly created for this provider. It makes sure our data
   * JSON has been loaded from the server.
   * @return {Promise}
   * @private
   */
  loadData() {
    if (this.data) {
      return Promise.resolve(this.data);
    }

    return this.loadJSON(
      "https://static.photoeditorsdk.com/libraries/unsplash/metadata.json"
    ).then((data) => {
      if (typeof data === "string") {
        data = JSON.parse(data);
      }

      this.data = data;
      return data;
    });
  }

  /**
   * Returns the categories
   * @return {Promise}
   * @resolve {LibraryCategory[]}
   */
  getCategories() {
    return this.loadData().then((data) => {
      // Create `Category` instances from our data
      return data.categories.map((categoryData) => {
        return new LibraryCategory({
          name: categoryData.name,
          coverImageUrl: categoryData.coverImage,
        });
      });
    });
  }

  /**
   * Returns the images which can be filtered by the search query
   * @param {String} query
   * @return {Promise}
   * @resolve {LibraryImage[]}
   */
  searchImages(query) {
    return this._loadData().then((data) => {
      return data.images
        .filter((image) => {
          // Split query by spaces, make sure all words are present in image title
          var words = query.split(/\s+/);
          for (var i = 0; i < words.length; i++) {
            var word = words[i];
            var regexp = new RegExp(word, "i");
            if (!regexp.test(image.title)) {
              return false;
            }
          }

          return true;
        })
        .map((imageData) => {
          return new Image(imageData);
        });
    });
  }
}

Passing the provider to the control

In order to make the UI use your provider, simply pass it as the provider option to the library control:

const editor = await PhotoEditorSDKUI.init({
  library: {
    provider: MyProvider,
  },
});

Disabling the webcam / upload

Your are able to allow your users to take photos using their webcam or upload their own photos using a file picker. In order to enable these features, simply set the enableWebcam or the enableUpload (which also includes the webcam on mobile devices) to true.

const editor = await PhotoEditorSDKUI.init({
  library: {
    enableWebcam: true, // Disables the webcam
    enableUpload: true, // Disables the upload
  },
});

Flattening of categories

If flattenCategories is set to true, all images will be shown in the top-level of the library selection tool, which effectively hides the categories.

const editor = await PhotoEditorSDKUI.init({
  library: {
    flattenCategories: true,
  },
});

Using a different category header style (`AdvancedUI`)

It is possible to switch between two styles of categories by changing categoryHeaderType.

categoryHeaderType: "text" will group the category items under a text heading
categroyHeaderType: "card" will group the category items in a collapsible section and display a card for the header

const editor = await PhotoEditorSDKUI.init({
  library: {
    categoryHeaderType: "text",
  },
});

Localization

You can override all the labels used in library tool using the custom.languages object in configuration, below are the default library localization lables.

await PhotoEditorSDKUI.init({
  // ...,
  custom: {
    languages: {
      en: {
        // ...,
        library: {
          title: "Library",
          controls: {
            buttonUpload: "Upload Image",
            buttonWebcamOpen: "Open Webcam",
            buttonWebcamClose: "Close Webcam",
            placeholderSearch: "Search Library",
            noResults: "No Results",
          },
        },
      },
    },
  },
});