Cockpit Javascript SDK

A Javascript SDK for Cockpit Headless CMS

Usage

npm install cockpit-sdk
# or
yarn add cockpit-sdk

If you're using Gatsby you can include the cockpit-sdk with the following:

Simple Example

const CockpitSDK = require("cockpit-sdk").default;
// or
import CockpitSDK from "cockpit-sdk";

const cockpit = new CockpitSDK({
  host: "http://localhost:8080", // e.g. local docker Cockpit.
  accessToken: "12a3456b789c12d34567ef8a9bc01d"
});

cockpit.collectionGet("posts", { limit: 3 }).then(data => console.log(data));
// { "fields": {...}, "entries": [{...},{...},{...}], "total": 3 }

// Or with the callback api:
cockpit.collection("posts", { limit: 3 }).get(console.log);
cockpit.region("regionName").data(console.log);

Connecting to your Cockpit instance

Connecting your project to Cockpit is done by instantiating CockpitSDK. This object takes multiple parameters.

| Parameter | Description | | -------------------- | ----------------------------------------------- | | host | Your cockpit instance address | | accessToken | Cockpit access token | | webSocket | Websocket address (if used) | | fetchInitOptions | Init options to apply on every Fetch request | | defaultOptions | Options to be applied on every Cockpit fetch |

  {
    filter: { published: true }, // mongoDB Operators.
    populate: 1 // Resolve linked collection items.
    limit,
    skip,
    apiEndpoints, // See Api endpoints section bellow
    sort: { _created: -1 },
  }

Collections

| Method | Args | Return | | -------------------- | ----------------------------- | ------- | | collectionSchema | (collectionName) | Promise | | collectionList | () | Promise | | collectionGet | (collectionName, options) | Promise | | collectionSave | (collectionName, data) | Promise | | collectionRemove | (collectionName, filter) | Promise | | collection | (collectionName, options) | - | | collection.get | (success, error) | - | | collection.watch | (success, error) | - | | collection.on | (eventName, success, error) | - |

  {
    filter: { published: true }, // mongoDB Operators.
    populate: 1 // Resolve linked collection items.
    limit,
    skip,
    sort: { _created: -1 },
  }

Assets

| Method | Args | Return | | --------------- | ----------------------------------------------------- | -------------------------- | | image | (assetId OR assetPath, imageOptions OR widthsArray) | Path String OR Paths Array | | imageSrcSet | (assetId OR assetPath, widthsArray) | Paths Array | | imageGet | (assetId OR assetPath, imageOptions) | Promise | | assets | (options) | Promise |

{
  width,
  height,
  quality: 85,
  pixelRatio: 2, // default: 1
  mode: 'thumbnail' | 'bestFit' | 'resize' | 'fitToWidth' | 'fitToHeight',
  filters: { darken: 50, pixelate: 40, desaturate: true, flip: 'x', colorize: 'FF0' },
  /* Filters:
  blur | brighten | colorize | contrast | darken | desaturate |
  emboss | flip | invert | opacity | pixelate |
  sepia | sharpen | sketch
  */
}

[
  100, // Width
  {
    srcSet: "100w" | "2x" | "(max-width: 30em)",
    ...imageOptions
  }
];

When image method receives an array as second argument it will behave as imageSrcSet.

cockpit.image(path); // original/path.jpg
cockpit.image(path, { width: 100 });
cockpit.image(path, [100, 480, 960]);
cockpit.image(path, [
  100,
  { width: 480, height: 480 },
  { width: 960, srcSet: "(max-width: 30em)" }
]);
// ['?src=path.jpg&w=100 100w', '?src=path.jpg&w=480&h=480 480w', '?src=path.jpg&w=960 (max-width: 30em)']

User

| Method | Args | Return | | ------------- | ------------------ | ------- | | authUser | (user, password) | Promise | | listUsers | (options) | Promise |

Regions

| Method | Args | Return | | --------------- | ----------------------- | ------- | | region | (regionName, options) | - | | region.get | (success, error) | - | | region.data | (success, error) | - | | regionGet | (regionName, options) | Promise | | regionData | (regionName, options) | Promise |

Forms

| Method | Args | Return | | -------------- | --------------------- | ------ | | formSubmit | (formName, options) | - |

cockpit.formSubmit(
  'contacts',
  {
    field1: 'value1',
    field2: 'value2',
  },
  options,
);

Real-time

Simple Example

The collection method fetches the data on call and on every collection update.

The real-time methods expects callback functions instead of a promise.

cockpit.collection("portfolio").watch(data => console.log(data));

// { "fields": {...}, "entries": [{...},{...},{...}], "total": … }

Real-time Methods

You will need a Websocket middleware server to use the real-time features.

This SKD is working with Cockpit-Real-time-Server

| Method | Args | | -------------------- | ----------------------------- | | collection | (collectionName, options) | | collection.get | (success, error) | | collection.watch | (success, error) | | collection.on | (eventName, success, error) |

const collection = cockpit.collection("portfolio");
collection.watch(console.log); // { "entries": […], "fields": {...}, "total": … }
collection.on("save", console.log); // { entry: {...}, collection: '', event: '' }
collection.on("preview", console.log); // { entry: {...}, collection: '', event: '' }

Note that the .watch and .get methods returns the whole entries and the .on method just one entry

Api endpoint

Default endpoints

| Name | Default URL | | -------------------------- | ---------------------------------- | | cockpitAssets | '/api/cockpit/assets' | | cockpitAuthUser | '/api/cockpit/authUser' | | cockpitImage | '/api/cockpit/image' | | cockpitListUsers | '/api/cockpit/listUsers' | | collectionsCollection | '/api/collections/collection/' | | collectionsGet | '/api/collections/get/' | | collectionsListCollections | '/api/collections/listCollections' | | collectionsRemove | '/api/collections/remove/' | | collectionsSave | '/api/collections/save/' | | regionsData | '/api/regions/data/' | | regionsGet | '/api/regions/get/' | | regionsListRegions | '/api/regions/listRegions' | | singletonsGet | '/api/singletons/get/' | | singletonsListSingletons | '/api/singletons/listSingletons' |

The default apiEndpoints can be updated in the constructor.

new CockpitSDK({
  // ...
  apiEndpoints: {
    cockpitImage: '/api/public/image',
  },
});

Event names

cockpit.collection("portfolio").on(eventName);

| Events | | ------- | | save | | preview |