Cosmic JS Extensions Cosmic JS Extensions enable you to create custom experiences within your Bucket. We also have pre-built Extensions available for easy install.

What Are Cosmic JS Extensions?

Cosmic JS Extensions make it possible to extend the functionality of Cosmic JS for both the developer and editor. Developers are given a canvas to create interactive views, connect to third-party APIs and customize the editor experience. Think of it as a controllable app within your Bucket.

What Can You Create?

A Cosmic JS Extension is simply a static website with an index.html file as the entry point, so you have lots of freedom. You can:

  • Interact with your Cosmic JS Bucket through the API, add / edit data and files from your Cosmic JS Bucket.
  • Display information from third-party APIs.
  • Create interactive experiences that use the Cosmic JS API and third-party APIs.

How to Add an Extension

You can add an available extension by installing it to your Bucket. Or you can create your own Extension by uploading a zip file to the Extensions area in your Bucket.

Installing an Extension

1. Go to Your Bucket > Extensions > Browse Extensions. Extensions will be made available here for quick installation into your Bucket.

Uploading an Extension

1. Go to Your Bucket > Extensions > Upload Extension.

2. Add your Extension zip file making sure to include all required files. See "How to Upload an Extension" section below.

How to Upload an Extension

Upload a new Extension to your Bucket by uploading a zipped folder that includes a couple required files. When you upload your Extension zip file, the following files need to be included in your zipped folder:

extension.json
index.html

Query Parameters

After adding your Extension, query parameters are attached to the URL for easy connection to your Bucket. The format looks like this:
/?bucket_slug=your-bucket-slug&read_key=your-read-key&write_key=your-write-key
When you build your application, you can get these values with JavaScript for example:

window.location.search

Extension Settings

Include an extension.json file to set information about your Extension. Add an optional Font Awesome icon to create a custom icon in the sidenav. Add an image URL as the thumbnail image next to your Extension. Example:

{
  "title": "Product Manager",
  "font_awesome_class": "fa-tags",
  "image_url": "http://this-is-your-thumbnail-url.xyz"
}

Optional Import Data

Along with the Extension info, you can import data to the destination Bucket. By adding an objects array, you are able to import Objects. By adding an object_types array, you are able to import Object Types.

{
  "title": "Product Manager",
  "font_awesome_class": "fa-tags",
  "image_url": "http://this-is-your-thumbnail-url.xyz"
  "objects": [
    {
      "title": "Product 1",
      "slug": "product-1",
      "type_slug": "products",
      "metafields": [
        {
          "title": "Image",
          "key": "image",
          "value": "1234asdf1234.jpg"
        },
        {
          "title": "Price",
          "key": "price",
          "value": "$12.99"
        }
      ]
    },
    {
      "title": "Product 2",
      "slug": "product-2",
      "type_slug": "products",
      "metafields": [
        {
          "title": "Image",
          "key": "image",
          "value": "4321asdf1234.jpg"
        },
        {
          "title": "Price",
          "key": "price",
          "value": "$14.99"
        }
      ]
    }
  ],
  "object_types": [
    {
      "title": "Products",
      "slug": "products",
      "singular": "Product",
      "metafields":[
        {
          "title": "Image",
          "key": "image",
          "type": "file",
          "value": ""
        },
        {
          "title": "Price",
          "key": "price",
          "type": "text",
          "value":""
        }
      ]
    }
  ]
}

Preparing Your Extension for Upload

Zip up your folder:

Then upload the Extension to your Cosmic JS Bucket located in Your Bucket > Extensions > Upload Extension (screenshot below). You can also upload your Extension via the Cosmic JS API.

  

Resources

View these Extension examples on GitHub:

Product Manager
Contact Form
SEO Manager

We hope you enjoy the new freedom you have to build and extend the functionality of Cosmic JS. If you have any questions, you can reach out to us on Twitter and join the community on Slack.