Facelift ContentBase Javascript SDK

Javascript SDK for Facelift Cloud ContentBase API.

ContentBase is a content management platform for web applications, mobile apps, and connected devices. It allows you to create, edit & manage content in the cloud and publish it anywhere via API. ContentBase offers tools for managing editorial teams and enabling cooperation between organizations.

Requirements

The SDK is currently in beta. The API might change at any time.

You need to install Node.js first, which is mandatory to install all the vendor libraries needed to run the Javascript SDK. If you're not familiar with NodeJS, please refer to their documentation first.

Setup

npm install faceliftsdk --save

In code:

const faceliftsdk = require('faceliftsdk');

Usage

Make sure that you have set up at least one Project with at least one Content Type and Field (also, don't forget to publish them).

The ContentBase Javascript SDK was made to help you work with the ContentBase content easily. The SDK is a cross-platform and can be used with any Javascript project (backend or frontend). The only difference between different platforms is the fetch library you have to provide to the SDK and it must be compatible with the platform on which you are using the SDK.

To use static typing, we recommend you to use typescript with the faceliftsdk library.

Successfully creating client needs three parameters:

• api_key - API_KEY retrieved from Facelift web page (optional, retreiving public content types can be done without api_key)
• project_id - Project ID retreived from Facelift web page
• fetch - library for accessing Facelift's API.

const nodeFetch = require('node-fetch');
const faceliftsdk = require('faceliftsdk');
const client = await createFaceliftClient({
    api_key: API_KEY,
    project_id: PROJECT_ID
},
nodeFetch
);

Working with objects

Once you created client, you have to create ContentProvider, to start working with the objects. For retrieving a specific object, list of all the objects in the project or delete a specific object, you don't need to provide contentTypeIdentifier (Even though if you do provide it you can still do the calls). For creating, updating or getting a list of objects from content type, you have to send contentTypeIdentifier as a provider parameter. If you want static typing support in typescript you need to provide a generic object to the provider, with all the containing fields of your API object.

Example of the following object:

TestContent {
  booleanfield: boolean;
  datefield: Date;
  integerfield: number;
  textfield: string;
  translatablefield: TranslatableProperty<string>;
  testreferencefield: ReferencedObjectProperty<BaseContentBaseObject>;
  testasset: ReferencedAssetProperty;
}

Create provider

Javascript

const contentTypeIdentifier = YOUR_CONTENT_TYPE_IDENTIFIER; // Optional
const testContentProvider = client.createContentProvider(
    contentTypeIdentifier
);

Typescript

class TestContent extends BaseContentBaseObject {
  public booleanfield: boolean;
  public datefield: Date;
  public integerfield: number;
  public textfield: string;
  public translatablefield: TranslatableProperty<string>;
  public referencefield: ReferencedObjectProperty<BaseContentBaseObject>;
  public asset: ReferencedAssetProperty;
}
const contentTypeIdentifier = YOUR_CONTENT_TYPE_IDENTIFIER; // Optional

const testContentProvider = client.createContentProvider<TestContent>(
    contentTypeIdentifier
);

Get objects

// Get list of objects
const objectList = await testContentProvider.list();
/* Returned data
  {
      pagination: Pagination,
      data: Array<TestContent>
  }
*/

// Get single object by id
const contentIdentifier = YOUR_CONTENT_IDENTIFIER;
const faceliftObject = await tectContentProvider.get(contentIdentifier);
/* Returned object
  {
    metaData: MetaData,
    booleanfield: boolean,
    datefield: Date,
    integerfield: number,
    textfield: string,
    translatablefield: TranslatableProperty<string>,
    referencefield: ReferencedObjectProperty<BaseContentBaseObject>,
    asset: ReferencedAssetProperty,
  }
*/

Translatable fields

Translatable fields have four methods for getting or setting values:

// Project default locale is 'en_US':
console.log(faceliftObject.getValue()); // Prints default locale value (en_US)
console.log(faceliftObject.getValue('de_DE')); // Prints de_DE locale value
faceliftObject.setValue('New en_US text'); // Sets the new text for default locale (en_US)
faceliftObject.setValue('New de_DE text', 'de_DE'); // Sets the new text de_DE locale

Create objects

const newObject = {
  booleanfield: true,
  datefield: new Date(),
  integerfield: 42,
  textfield: 'Simple text'
};

const createdObject = await testContentProvider.create(newObject);

Update objects

const contentIdentifier = '	s7JE3z9mpNXwSCsz';
const updateObject = {
  booleanfield: false,
  datefield: new Date(),
  integerfield: 24,
  textfield: 'Simple text2',
};

const updatedObject = await testContentProvider.update(contentIdentifier, updateObject);

Delete objects

const contentIdentifier = YOUR_CONTENT_IDENTIFIER;
await tectContentProvider.delete(contentIdentifier);

Working with references and assets

The SDK consists of several parts for making work with the ContentBase easy. One of this part is the reference and asset part. References are other objects associated with the current objects you are working on. You can use them by defining fields as reference or asset fields. When you try to invoke a get method in your Object which is a field of type Reference or Asset, the SDK loads these linked resources only when they are needed, means, it generates another API call and fetches the data for them on the fly.

References

// Get single object by id
const contentIdentifier = YOUR_CONTENT_IDENTIFIER;
const faceliftObject = await tectContentProvider.get(contentIdentifier);
const referencedField = await faceliftObject.referencefield.get();
/* Returned object
  {
    metaData: MetaData,
    ...fields
  }
*/

Assets

Asset can be accessed through the returned Object by calling get method on Asset field. Assets can also be accessed by id or list all the assets of a Project.

// Get single object by id
const contentIdentifier = YOUR_CONTENT_IDENTIFIER;
const faceliftObject = await tectContentProvider.get(contentIdentifier);
const asset = await faceliftObject.asset.get();
/* Returned object
  {
    metaData: MetaData,         // Meta data of the asset
    title: string;              // Title of the asset
    type: string;               // Type of the asset
    mimeType: string;           // The content (MIME-)type of the asset
    fileSize: number;           // The file size of the asset
    file: string;               // An internal `File` instance which holds all the neccessary file information of the underlying asset-file.
    originalFileName: string;   // The file name of the asset
    width?: number;             // (only for Image instances) The width of the image
    height?: number;            // (only for Image instances) The height of the image
    url: string;                // The url of your asset file which can be used in image-sources or as downloads links
    thumbnail?: string;         // (only for Image instances) The image thumbnail
  }
*/

For accessing all the project Assets or by an identifier, you need to create AssetProvider first.

const assetProvider = client.createAssetProvider();

// Get all the project assets
const faceliftAssets = await assetProvider.list();

// Get asset by id
const assetIdentifier = YOUR_ASSET_IDENTIFIER;
const faceliftAsset = await assetProvider.get(assetIdentifier);

API documentation

• API documentation

License

Copyright (c) 2018 Facelift bbt GmbH. Code released under the MIT license.