Brightspot CMS Developer Guide

Implementation requirements


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


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;

    /* Getters and setters. */
   
    @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();
    }

}
  • Calls the internal getPreviewFile method, which returns a Getty image for display in the search panel results.
  • 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.
  • Specifies the four GettyImage fields. The fields will be populated with data retrieved from the Getty repository.
  • Displays the ID of the retrieved Getty image in the search results.
  • Uses Image as the label for the url field in the content edit form for the GettyImage type.
  • Uses a Java Expression Language (EL) statement that calls the internal getUrlPreviewHtml method. The annotation results in construction of an HTML  tag that references the image in the Getty repository, enabling the image to be displayed in the GettyImage content edit form.
  • Required getExternalItemId implementation, which returns a unique ID for a Getty image.
  • Uses a Getty image URL to return the image that’s displayed in the search panel results.
  • Returns an HTML  tag for Brightspot to display the image in the GettyImage content edit form.


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); 
   }
}
  • Copies field data from a GettyImage object passed to the method into a new instance of Image.
  • Retrieves the URL that points to the Getty image.
  • Retrieves the Getty image from the external repository and saves it as a StorageItem object in the Brightspot repository.
  • Returns the image as an internal Brightspot type.

Previous Topic
Importing to Brightspot
Next Topic
Configuring Brightspot's server
Was this topic helpful?
Thanks for your feedback.
Our robust, flexible Design System provides hundreds of pre-built components you can use to build the presentation layer of your dreams.

Asset types
Module types
Page types
Brightspot is packaged with content types that get you up and running in a matter of days, including assets, modules and landing pages.

Content types
Modules
Landing pages
Everything you need to know when creating, managing, and administering content within Brightspot CMS.

Dashboards
Publishing
Workflows
Admin configurations
A guide for installing, supporting, extending, modifying and administering code on the Brightspot platform.

Field types
Content modeling
Rich-text elements
Images
A guide to configuring Brightspot's library of integrations, including pre-built options and developer-configured extensions.

Google Analytics
Shopify
Apple News