Attachments

Cloud CMS provides support for the storage and retrieval of binary assets. These assets are stored as attachments on an object.

Unlike some CMS systems which start with the binary asset, Cloud CMS considers all of your objects and content to be JSON documents. The JSON document then has N number of binary BLOBs attached to it. Each attachment has a unique name and retains information such as mimetype, filename and content length.

The following kinds of objects support attachments:

  • Content Nodes and Associations
  • Users and Groups
  • Identities
  • Archives
  • Tenants

In addition, all data stores support raw binary file storage. The mechanism under the hood used to achieve this is in common with attachments but it is conceptually different. To learn more about raw binary storage, please check out our documentation on Binaries.

Multiple Attachments

A lot of people who come from old school CMS systems either think of "content" as a binary blob or they think of binary data as somehow different (i.e. static) and of a different class of thing.

In Cloud CMS, we think of everything as a JSON object that may optionally have N number of attachments. Objects that do not have binary attachments are just, well, objects. Objects that have binary attachments are a little souped up. Those attachments float around with the object wherever it goes and participate in the versioning of the object and validation/consistency checking with the graph.

You can add as many attachments as you would like. One might be a PDF. Another an image file. Or a video file. It really doesn't matter so long as Cloud CMS captures it and then stores it away. Once stored away, the attachments for an objects can be retrieved via the API (generally by using the /attachments subpath in the URI).

Here is an example of getting the attachments for a node from the API:

GET /repositories/{repositoryId}/branches/{branchId}/nodes/{nodeId}/attachments

{
    rows: [{
        _doc: "thumbnail
        contentType: "image/png",
        length: 5495,
        filename: "_preview_default_icon64_64.png",
        attachmentId: "_preview_default_icon64_64",
        ext: "png"
    }, {
        _doc: "default",
        contentType: "image/png",
        length: 47462,
        filename: "logo.png",
        attachmentId: "default",
        ext: "png"
    }],
    size: 2,
    total_rows: 2,
    offset: 0
}

The results are paginated and contain the entries in a list. In this case, we have two attachments - one which is called default and one which is called thumbnail.

Each entry in the list has an attachmentId which is the key by which the attachment could be retrieved or streamed back from the server. We can stream back the default attachment like this:

GET /repositories/{repositoryId}/branches/{branchId}/nodes/{nodeId}/attachments/default

We can also set the content disposition header by using the a request parameter:

GET /repositories/{repositoryId}/branches/{branchId}/nodes/{nodeId}/attachments/default?a=true

Each attachment entry in the list provides the following information:

  • _doc - the attachment ID
  • contentType - the mime type of the attachment
  • length - the length of the attachment in bytes
  • filename - the filename of the attachment (if uploaded)
  • ext - the extension of the attachment to be used if written to disk or deployed (i.e. attachmentId.ext)

You may also see objectId which is an internal key used to locate the resource on a back end storage provider.

The default attachment

Within the main Cloud CMS user interface, Cloud CMS optimizes things a bit for end users who just want to work with straight up desktop content. If you upload or drag-and-drop binary files into Cloud CMS, Cloud CMS will automatically create JSON object for you with a single default attachment.

Some of the screens within the Cloud CMS user interface are optimized to make editing of the default attachment a bit easier. We recommend using the default attachment for any primary binary payloads that make up your content.

The User Interface

That said, the Cloud CMS user interface also provides ways to navigate and work with attachments that have any name. You can create, upload, download and remove attachments in many different places.

As an example, here is the Document Attachment screen from within the Document inspector:

[object Object]