Support and Documentation

Implementation requirements

To import content from third-party repositories, you must supply the following implementations:

ExternalItem implementation

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") 1
@Recordable.SourceDatabaseProviderClass(GettyDatabaseProvider.class) 2
public class GettyImage extends ExternalItem {

    @Indexed
    private String title; 3

    @ToolUi.DefaultSearchResult 4
    private String gettyId;

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

    private String caption;

    /* Getters and setters. */
   
    @Override
    public String getExternalItemId() { return getGettyId(); } 7

    @Ignored(false)
    @ToolUi.Hidden
    public StorageItem getPreviewFile() { 8
        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", 9
                 "src", url,
                 "style", htmlWriter.cssString(
                         "width", "auto",
                         "height", "500px",
                         "border", "solid 1px #cdcdcd",
                         "padding", "3px"));

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

        return stringWriter.toString();
    }

}

1

Calls the internal getPreviewFile method, which returns a Getty image for display in the search panel results.

2

Specifies which database provider class to use to retrieve Getty images. The specified database provider creates an instance of the HttpEndpointDatabase implementation, which integrates with the Getty third-party service. For more information, see SourceDatabaseProvider implementation.

3

Specifies the four GettyImage fields. The fields will be populated with data retrieved from the Getty repository.

4

Displays the ID of the retrieved Getty image in the search results.

5

Uses Image as the label for the url field in the content edit form for the GettyImage type.

6

Uses a Java Expression Language (EL) statement that calls the internal getUrlPreviewHtml method. The annotation results in construction of an HTML <img> tag that references the image in the Getty repository, enabling the image to be displayed in the GettyImage content edit form.

7

Required getExternalItemId implementation, which returns a unique ID for a Getty image.

8

Uses a Getty image URL to return the image that's displayed in the search panel results.

9

Returns an HTML <img> tag for Brightspot to display the image in the GettyImage content edit form.

ExternalItemConverter implementation

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) { 1
      Image image = new Image();
      image.setTitle(gettyImage.getTitle());
      image.setCaption(gettyImage.getCaption());

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

      try { 3
         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); 4
   }
}

1

Copies field data from a GettyImage object passed to the method into a new instance of Image.

2

Retrieves the URL that points to the Getty image.

3

Retrieves the Getty image from the external repository and saves it as a StorageItem object in the Brightspot repository.

4

Returns the image as an internal Brightspot type.