Support and Documentation

An ExternalItem implementation represents an object referenced in a third-party repository. Extending ExternalItem, the implementation provides a bridge between data retrieved from the repository and an internal Brightspot object to which the data will be converted. An external item is identified with a unique ID, and you must implement ExternalItem#getExternalItemId to return a unique ID of an external item.

The following example shows an ExternalItem implementation that represents an image in the external Getty repository. Its setters and getters support creation of GettyImage objects with third-party data and conversion to internal Brightspot objects. Also included are methods that enable Brightspot to display Getty images in the search panel and in content edit forms.

@Recordable.PreviewField("getPreviewFile")
@Recordable.SourceDatabaseProviderClass(GettyDatabaseProvider.class)
public class GettyImage extends ExternalItem {

   @Indexed
   private String title;

   @ToolUi.DefaultSearchResult
   private String gettyId;

   @Recordable.DisplayName("Image")
   @ToolUi.NoteHtml("<span data-dynamic-html='${content.getUrlPreviewHtml()}'></span>")
   private String url;

   private String caption;

   public String getTitle() { return title; }
   public void setTitle(String title) { this.title = title; }

   public String getGettyId() { return gettyId; }
   public void setGettyId(String gettyId) { this.gettyId = gettyId; }

   public String getUrl() { return url; }
   public void setUrl(String url) { this.url = url; }

   public String getCaption() { return caption; }
   public void setCaption(String caption) { this.caption = caption; }

   @Override
   public String getExternalItemId() { return getGettyId(); }

   @Ignored(false)
   @ToolUi.Hidden
   public StorageItem getPreviewFile() {
      return Optional.ofNullable(getUrl())
             .map(url -> {
                 StorageItem file = new UrlStorageItem();
                 file.setPath(url);
                 return file;
             })
             .orElse(null);
   }

   public String getUrlPreviewHtml() {
      String url = getUrl();

      if (url == null) {
         return "<span></span>";
      }

      StringWriter stringWriter = new StringWriter();
      HtmlWriter htmlWriter = new HtmlWriter(stringWriter);

      try {
         htmlWriter.writeTag("img",
                 "src", url,
                 "style", htmlWriter.cssString(
                         "width", "auto",
                         "height", "500px",
                         "border", "solid 1px #cdcdcd",
                         "padding", "3px"));

      } catch (Exception error) {
         // Ignore.
      }

      return stringWriter.toString();
   }

}

In the previous snippet—

An ExternalItem implementation and associated database provider retrieve data from a third-party repository and make it visible in Brightspot as an ExternalItem type. For an external item to be completely imported into Brightspot, it must be converted to an internal Brightspot type. An external item converter must implement the ExternalItemConverter#convert method. The following example shows an ExternalItemConverter implementation that converts the external GettyImage type to an internal Brightspot Image type.

public class GettyImageToImageConverter implements ExternalItemConverter<GettyImage> {

   private static final Logger LOGGER = LoggerFactory.getLogger(GettyImageToImageConverter.class);

   @Override
   public Collection<?> convert(GettyImage gettyImage) {
      Image image = new Image();
      image.setTitle(gettyImage.getTitle());
      image.setCaption(gettyImage.getCaption());

      String url = gettyImage.getUrl();
      if (url == null) {
         return Collections.singletonList(image);
      }
      url = url.substring(0, url.lastIndexOf("?"));

      try {
         StorageItem file = StorageItem.Static.create();
         file.setContentType("image/jpg");
         file.setPath(new RandomUuidStorageItemPathGenerator().createPath(url));

         ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
         ImageIO.write(ImageIO.read(new URL(url).openStream()), "jpg", outputStream);

         file.setData(new ByteArrayInputStream(outputStream.toByteArray()));
         file.save();
         image.setFile(file);

      } catch (IOException error) {
         LOGGER.error("Unable to save Getty Image file!", error);
      }

      return Collections.singletonList(image);
   }
}

In the previous snippet—