Twixly-extension-sdk NPM

Introduction⁣⁣⁣

Twixly Extensions lets you extend Twixly in a powerful way. You can create any type of field or view. It's your imagination that stops you. This document describes the API that an extension can use to communicate with the Twixly Management App.

Inclusion in your project

You will need to include the twixly-extension-sdk library in your HTML5 app:

<script src="https://unpkg.com/twixly-extension-sdk"></script>

The SDK is also distributed as an NPM package.

npm install --save twixly-extension-sdk

You can include it in your code base with

var twixlyExtension = require('twixly-extension-sdk')

Initialization

The SDK exposes the twixlyExtension.init() method. This is the main entry point for all extension related code. If you require the script from the web without any module system the item point is available as

function appStart(extension) {
  var value = extension.field.getValue();
  extension.field.setValue('Hello world!');
}

twixlyExtension.init()
  .then(appStart)
  .catch(function (err) {
    console.log(err);
  });

If you use a CommonJS packager for the browser (e.g. Browserify) you need to require the Extensions SDK.

var twixlyExtension = require('twixly-extension-sdk')
twixlyExtension.init(function (extension) {
  /* ... */
})

Basic template

Use this HTML template to quickly get up and running in creating your new and awesome Twixly extension:

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Awesome Twixly Extension</title>
  <!-- Twixly Extension SDK CSS -->
  <link rel="stylesheet" href="https://unpkg.com/twixly-extension-sdk/index.css">
  <!-- Twixly Extension SDK JavaScript -->
  <script src="https://unpkg.com/twixly-extension-sdk"></script>  
</head>
<body>
  <div class="app-container">
    <!-- Start your awesome extension here -->
  </div>
</body>
</html>

Extension API Reference

`extension.itemType`

This API gives you access to data about the item type and the item. It has the form as described under "item type properties" in our api documentation.

`extension.field`

This API gives you access to the value and metadata of the field the extension is attached to.

Name	Arguments	Returns	Description
`extension.field.getValue()`	none	Mixed value depending of field type	Gets the current value of the field
`extension.field.setValue(value)`	value: string	Promise: Field	Sets the value for the field
`extension.field.setInvalid(Boolean)`	boolean: true/false	undefined	Title for this extension
`extension.field.onChange(cb)`	function	Field object	URI to the extension
`extension.field.onValidate(cb)`	function	Field object	Extension type. `"field"` or `"view"`
`extension.field.schema`	object		The JSON Schema for this field

`field.getValue(): mixed`

Gets the current value of the field and locale. In the example this would yield "My Post".

`field.setValue(value): Promise<void>`

Sets the value for the field. The promise is resolved when the change has been acknowledged. The type of the value must match the expected field type. For example, if the extension is attached to a "String" field you must pass a string.

`field.setInvalid(Boolean): undefined`

Communicates to the twixly web application if the field is in a valid state or not. This impacts the styling applied to the field container.

`field.onChange(cb): function`

Calls the callback every time the value of the field is changed by an external event (e.g. when multiple editors are working on the same item) or when setValue() is called.

The method returns a function you can call to stop listening to changes.

`field.onValidate(cb): function`

Calls the callback immediately with the current validation errors and whenever the field is re-validated. The callback receives an array of error objects. An empty array indicates no errors.

The errors are updated when the app validates an item. This happens when loading an item or when the user tries to publish it.

The method returns a function that you can call to stop listening to changes.

`field.id: string`

The ID of a field is defined in an item's item type. Yields "title" in the example.

`extension.item`

This object allows you to read and update the value of any field of the current item and to get the item's metadata.

`item.fields[id]: Field`

In addition to extension.field, a extension can also control the values of all other fields in the current item. Fields are referenced by their ID.

The Field API methods provide a similar interface to extension.field.

field.id: string
field.getValue(): mixed
field.setValue(value): Promise<void>
field.onChange(cb): function

Example

If the item has a "title" field, you can transform it to upper case with:

var titleField = extension.item.fields.title
var oldTitle = titleField.getValue();
titleField.setValue(oldTitle.toUpperCase());

`extension.bucket`

The bucket object exposes methods that allow the extension to read and manipulate a wide range of objects in the bucket.

Allows operating on the current bucket's item types, items and media.

bucket.get([item-type, item, media], options): Promise<void>
bucket.get([item-type, item, media]/[id], options): Promise<void>
bucket.post([item-type, item, media], data): Promise<void>
bucket.put([item-type, item, media], data): Promise<void>
bucket.delete(id): Promise<void>

`extension.window`

The window object provides methods to update the size of the iframe the extension is contained within. This prevents scrollbars inside the extension.

To prevent a flickering scrollbar during height updates, it is recommended to set the extension's body to overflow: hidden;.

`window.updateHeight()`

Calculates the body's scrollHeight and sets the containers height to this value.

`window.updateHeight(height)`

Sets the iframe height to the given value in pixels. height must be an integer.

`extension.dialogs`

This object provides methods for opening UI dialogs:

`dialogs.selectSingleitem(options)`

Opens a dialog for selecting a single item. It returns a promise resolved with the selected entity or null if a user closes the dialog without selecting anything.

options is an optional object configuring the dialog.The available options are:

locale: The code of a locale you want to use to display proper titles and descriptions. Defaults to the bucket's default locale.
itemTypes: An array of item type IDs of items that you want to display in the selector. By default items of all item types are displayed.

// display a dialog for selecting a single item
dialogs.selectSingleitem().then((selecteditem) => {})

// select a single item of "blogpost" item type
// and display result in "de-DE" locale
dialogs.selectSingleitem({
  itemTypes: ['blogpost']
}).then((selecteditem) => {})

dialogs.selectMultipleitems(options)

Works similarly to selectSingleitem, but allows to select multiple items and the returned promise is resolved with an array of selected items.

Both locale and itemTypes options can be used. There are two additional options:

min and max - numeric values specifying an inclusive range in which the number of selected entities must be contained

// display a dialog for selecting multiple items
dialogs.selectMultipleitems().then((arrayOfSelecteditems) => {})

// select between 1 and 3 (inclusive) items
dialogs.selectMultipleitems({min: 1, max: 3})
.then((arrayOfSelecteditems) => {})