Attachments in your content model
Fundamentally, everything in Cloud CMS is JSON. JSON is simply scalar properties (text, numbers, etc). There isn't a way to represent binary data in pure JSON apart from getting into some very awkward encodings. So we don't go that route.
Rather, we use attachments. An attachment is a binary object that is part of the Node but isn't on the JSON. If you upload a binary object (such as a Word document or an image) to Cloud CMS, you'll see that it gives you a Node which is a JSON document and also has a single binary attachment called "default". The UI lets you preview the binary attachment. You can also add more attachments using the Attachments page on the left-hand side.
In this way, any Node can have zero or more attachments. The primary attachment is the "default" one but you can add others. Thumbnails are a really good use case for this where you might have many different attachments for your thumbnails of various sizes. For example, you might have "thumb256", "ipad320", etc. Each attachment can have a different mimetype and be of a different size.
So that's the foundation. Where your binary data and JSON all live on the same node.
Another way to do this is to use relator properties to relate two separate nodes together. Our customers use this feature to support the case where you might want to have a form with a control on it that lets you select from existing images or content items (such as picking images from an image library). Or connecting chapters to a book. For example, the idea might be that node #1 (library) relates to a node #2 (an image). Node #2 is just a normal node with a default attachment that is it's image. However, the virtue of being a separate node allows it to have it's own security context (access rights, who can see it, what they can do with it) and be re-used and shared across lots of libraries.
To achieve this, we offer relator properties. This is covered in good detail here:
Which way to go (using attachments or using relator properties to connect disparate nodes) is up to you.
In terms of the JS API to upload attachments, here are a few places to get a sense of things:
The JS API provides some minimal methods to upload and download. In general, to truly upload and download interesting content, you'll need to fire off your own HTTP POSTs to create your own attachments:
Simply post your content there and it'll be available with the attachment ID that you specify.
Finally, you may want to take a look at the Thumbnailable Feature:
The f:thumbnailable feature lets you define content types that have an automatic behavior so that thumbnails are auto-generated for you whenever the "default" attachment changes. That way, your end users just upload a new version of an image and all of the thumbnails are pre-generated for you at commit time.
Cloud CMS supports this kind of prescriptive generation of Thumbnails using features (we're very big on content modeling). It also supports dynamic or runtime / lazy generation using a URL pattern:
There are more switches and things you can provide, but the basic idea is that Cloud CMS checks to see if the thumbnail attachment exists. If not, it generates it for you on the fly. Cloud CMS also handles mimetype conversions so if you have, say, a Word document, it'll generate thumbnails for you by handling the intermediate page conversions to PDF and then to JPG (or whatever type you specify).