This document describes the API that an extension can use to communicate with the Twixly Management App.
- Inclusion into your project
- Initialization
extension.itemType
extension.field
-
extension.item
-
extension.bucket
extension.locales
extension.window
extension.dialogs
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')
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-ui-extensions-sdk')
twixlyExtension.init(function (extension) {
/* ... */
})
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.
This API gives you access to the value and metadata of the field the extension is attached to.
If an item returned by the twixly API looks like the following:
{
meta: { ... },
data: {
attributes: {
title: "My Post"
}
...
}
}
Then the extension is attached to the title
field.
Gets the current value of the field and locale. In the example this would yield
"My Post"
.
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.
Removes the value for the field and locale. A subsequent call to getValue()
for the field would yield 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.
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.
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.
The ID of a field is defined in an item's item type. Yields "title"
in the
example.
This object allows you to read and update the value of any field of the current item and to get the item's metadata.
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
. The
methods also accept an optional locale to change the value for a specific
locale. It defaults to the bucket the bucket's default locale (see
extension.locales
). Providing an unknown locale throws an
exception.
field.id: string
field.locales: Array<string>
field.getValue(locale?): mixed
field.setValue(value, locale?): Promise<void>
field.removeValue(locale?): Promise<void>
field.onChange(locale?, cb): function
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())
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. Item types created/updated or deleted this way will immediately be published or unpublished respectively.
bucket.get([item-type, item, media], options)
bucket.get([item-type, item, media]/[id], options)
bucket.post([item-type, item, media], data)
bucket.put([item-type, item, media], data)
bucket.delete(id)
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;
.
Calculates the body's scrollHeight
and sets the containers height to this
value.
Sets the iframe height to the given value in pixels. height
must be an
integer.
Listens for DOM changes and calls updateHeight()
when the size changes.
Stops resizing the iframe automatically.
This object provides methods for opening UI dialogs:
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({
locale: 'de-DE',
itemTypes: ['blogpost']
}).then((selecteditem) => {})
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
andmax
- 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) => {})
Counterpart of selectSingleitem
for media. A itemTypes
option is not
available.
Counterpart of selectMultipleitems
for media. A itemTypes
option is
not available.