Library API

Contents

This section describes the JavaScript API available for setting up and embedding the Guillotine library into your Enonic application.

Functions

createSchema

The createSchema(options) function creates a GraphQL schema with custom options.

Table 1. Schema options
Name Description

applications: String or Array.<String>

List of application keys for which GraphQL objects will be generated from content types (default: current application). The property is optional.

allowPaths:String or Array.<String>

Allowed content paths in addition to this site in the default mode. In the site-less mode only provided allowPaths will be used. The property is optional.

subscriptionEventTypes:String or Array.<String>

Specifies event type patterns to be listened by GraphQL Subscription. The property is optional. By default will only listen to node.* events.

Example of creation schema
const guillotineLib = require('/lib/guillotine');

const SCHEMA = guillotineLib.createSchema({
    applications: ['com.enonic.app.hmdb', app.name],
    subscriptionEventTypes: ['myapp.eventName', 'node.*']
});

createHeadlessCmsType

The createHeadlessCmsType(context) function creates the Guillotine Headless CMS type.

Example of usage
const guillotineLib = require('/lib/guillotine');

function createRootQueryType(context) {
    return context.schemaGenerator.createObjectType({
        name: 'Query',
        fields: {
            guillotine: {
                type: guillotineLib.createHeadlessCmsType(context),
                resolve: function () {
                    return {};
                }
            }
        }
    });
}

createContext

The createContext(options) function creates a context necessary to create Guillotine types.

Context options contain the same list of options that are used for schema options and can be customized.

An instance of context object exposes the following functions:

Name Description

addDictionaryType(obj: GraphQLObject): void

Adds GraphQL object to a dictionary. Each content type which implements any interface must be added to a dictionary to define its implementations.

putContentTypeType(name: string, obj: GraphQLObject): void

Stores GraphQL object in a map for quick access.

uniqueName:String or Array.<String>

Generates a unique name for object type. If a type with the provided name already exists, will append _<count> to the name, where count is a number of types with provided name.

getOption(name: string): Object

Returns an option by name.

putOption(name: string, value: object): void

Adds a new option to context.

Example of usage
const guillotineLib = require('/lib/guillotine');

const context = guillotineLib.createContext();

execute

v v 5.0.0 5.0.0 The execute(params) function allows to execute a GraphQL query.

List of properties for the params object:

Name Description Default value

query:String

GraphQL query. Property is required.

variables:Object

Variables for GraphQL query. Property is optional.

siteId:String

Site ID. Property is optional.

ID of a current site.

branch:String

Branch. Property is optional.

Branch from request.

schema:GraphQLSchema

GraphQL schema. Property is optional.

schemaOptions:Object

SchemaOptions object to customize schema. Property is optional.

context:Object

GraphQL context. Accessible in resolve function via env.context. Property is optional.

List of properties for the schemaOptions object:

Name Description

applications: String or Array.<String>

Allowed application keys in addition to this site. The property is optional.

allowPaths:String or Array.<String>

Allowed content paths in addition to this site. The property is optional.

subscriptionEventTypes:String or Array.<String>

Specifies event type patterns to be listened by GraphQL Subscription. The property is optional.

If the schema parameter is not provided to the function, then a schema will be created for each branch (draft or master) of the site which will be automatically updated when any application is added/removed/re-deployed to the site. Developer is responsible for implementation of update of the schemas created outside of this function.

IMPORTANT! This function can not be used in site-less mode (version 6.0.0 and above), use graphqlLib.execute instead.

Basic usage
const guillotineLib = require('/lib/guillotine');

exports.post = function (req) {
    let input = JSON.parse(req.body);

    let params = {
        query: input.query,
        variables: input.variables
    };

    return {
        contentType: 'application/json',
        body: guillotineLib.execute(params)
    };
};
Usage with schema options
const guillotineLib = require('/lib/guillotine');
const contentLib = require('/lib/xp/content');
const contextLib = require('/lib/xp/context');
const portalLib = require('/lib/xp/portal');

exports.post = function (req) {
    let siteConfig = contextLib.run({
        branch: req.branch
    }, () => contentLib.getSiteConfig({
        key: portalLib.getSite()._id,
        applicationKey: 'com.enonic.app.guillotine'
    }));

    let input = JSON.parse(req.body);

    let params = {
        query: input.query,
        variables: input.variables,
        schemaOptions: {
            applications: siteConfig.applications,
            allowPaths: siteConfig.allowPaths,
            subscriptionEventTypes: siteConfig.subscriptionEventTypes
        }
    };

    return {
        contentType: 'application/json',
        body: guillotineLib.execute(params)
    };
};
Customized schema
const guillotineLib = require('/lib/guillotine');

const SCHEMA = guillotineLib.createSchema();

exports.post = function (req) {
    let input = JSON.parse(req.body);

    let params = {
        query: input.query,
        variables: input.variables,
        schema: SCHEMA
    };

    return {
        contentType: 'application/json',
        body: guillotineLib.execute(params)
    };
};

initWebSockets

v v 5.0.0 5.0.0 The initWebSockets(schema) function is used for default handling of Subscription via WebSocket. Only node.* events are listened to by default for current site, branch and repository. To customize which events must be listened use subscriptionEventTypes option during schema creation.

IMPORTANT! In site-less mode (version 6.0.0 and above), this function is not supported. Developer is responsible for implementation of this functionality, if needed.

Table 2. Schema options
Name Description

schema: GraphQLSchema

GraphQL schema. This parameter must be provided if schema was created without using the execute function. The property is optional.

To start handling a WebSocket event, XP provides the handler called webSocketEvent, which will be called for every WebSocket event from a client.

Example of usage
const guillotineLib = require('/lib/guillotine');

const SCHEMA = guillotineLib.createSchema();

exports.webSocketEvent = guillotineLib.initWebSockets(SCHEMA);

createWebSocketData

v v 5.0.0 5.0.0 Creates WebSocket data object from request with branch, repositoryId and site properties.

IMPORTANT! In site-less mode (version 6.0.0 and above), this function is not supported. Developer is responsible for implementation of this functionality, if needed.

const guillotineLib = require('/lib/guillotine');

webSocket: {
    data: guillotineLib.createWebSocketData(req),
    subProtocols: ['graphql-ws']
}

Contents