/cockpit-sdk

A JavaScript SDK for Cockpit Headless CMS

Primary LanguageJavaScriptMIT LicenseMIT

Cockpit Javascript SDK

A Javascript SDK for Cockpit Headless CMS

npm version size

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
defaultOptions:

  {
    filter: { published: true }, // mongoDB Operators.
    populate: 1 // Resolve linked collection items.
    limit,
    skip,
    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) -
options:

  {
    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
imageOptions:

{
  width,
  height,
  quality: 85,
  mode: 'thumbnail' | 'bestFit' | 'resize' | 'fitToWidth' | 'fitToHeight',
  // Filters:
  blur, brighten, colorize, contrast, darken, desaturate,
  emboss, flip, invert, opacity, pixelate,
  sepia, sharpen, sketch
}

widthsArray:

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

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

Example:

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) -
region.get (success, error) -
region.data (success, error) -
regionGet (regionName) Promise
regionData (regionName) Promise

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

Event names

cockpit.collection("portfolio").on(eventName);
Events
save
preview