Hypertable Logo Hypertable

Custom Functions

Overview

Custom Functions enable custom logic to be executed. The body of a Custom Function can be defined either as Javascript (the default) or Function Steps. Custom Functions enable powerful workflows and customisations to be added to any Project.

Contents

Introduction

Custom Functions define custom logic which can be executed from a number of places within a Project, for example: Button Fields; Record Triggers & Actions; View Triggers & Actions; Dashboard View Buttons and Values; Custom Webhooks; Scheduled Events.

Custom Functions may be used to update one or more Records, calculate a value or metric, or integrate with an external service for example.

Javascript

Custom Functions are usually written in Javascript (JS). This is for a number of reasons:

  • Hypertable does not reinvent the wheel trying to create its own syntax which will need to be learned from new by ever single user
  • Becoming familiar with Javascript is a widely applicable skill that that is extremely useful outside of Hypertable
  • Javascript runs in the Browser and the Server, so the same logic can be easily reused

Function Steps

Custom Functions may also be defined as a list of "Function Steps". These are edited using a visual editor with dropdowns to select the sources and targets of the defined operations.

Function Steps only provide a subset of the functionality available to Javascript Custom Functions, but they have the benefit of not requiring knowledge of any syntax.

Creating Custom Functions

To create a new Custom Function, open the Project Settings page, open the Custom Functions tab, then click the Create Custom Function button.

A new Custom Function is created, and is opened in the Edit Custom Function modal.

Editing Custom Functions

To edit a Custom Function, open the Project Settings page, open the Custom Functions tab, then click the Edit button for the Custom Function.

Scheduling

Docs coming soon!

Webhooks

Docs coming soon!

Writing Custom Functions

Function Body Editor

In the "Edit Custom Function" modal, click the Edit Function Body button to open the code editor.

The editor uses the Monaco library which is the same editor whch powers VS Code. As such, many of the shortcuts and syntax highlighting capabilities available in VS Code are also available in the Custom Function editor. For example:

  • F1 - show command pallette
  • Ctrl+Space - trigger suggestions
  • Ctrl+Shift+Space - trigger parameter hints
  • Ctrl+K Ctrl+I - show hover

More VS Code shortcuts are shown here.

The editor opens in edit mode. Switch between edit mode and test mode using the Edit and Test buttons.

In test mode an additional Test Function panel is displayed with buttons to run the Custom Function and a panel messages logged using the H.log() method. The Dry Run button runs the function while mocking method calls, and the Live Run executes the function will all its side-effects.

The Test Function panel can be resized by dragging the "Test Function" label when the mouse cursor becomes .

Function Body

The body of a Custom Function is defined like the body of a JS function, without the function signature or closing brace.

For example, a Custom Function which shows a toast displaying the title of the current context Record (if it is defined) may have the following body:

// Read the title of the record in the function's context,
// and if the record is not defined use the string "(no record)"
const title = context.record?.title ?? "(no record)";
// Display a toast alert to the user containing the record's title
H.alertToast(title);

Custom Function bodies not not require any module.exports statements, or even any function customFunction() { definitions. The bodies of Custom Functions are just that: function bodies.

If a value should be returned from a function, it should be returned as usual from the body of a function with a return statement.

Async

Custom Functions are all async. Custom Functions are free to use the await keyword (and are encouraged to do so). There is no callback function passed into the execution context, so if any async steps are being executing, they must either be awaited or a Promise muse be returned from the function body.

Many of the Hypertable Client Library methods return Promises.

Hypertable Client Library

The Hypertable Client Library provides methods to interact with the rest of Hypertable. These include reading from and writing to Records, opening Views, showing dialog boxes, and more.

It is always available in Custom Function bodies as the constant: H.

For example:

const isConfirmed = await H.alertConfirm("Confirm this message?");
H.alertToast(`Is confirmed: ${isConfirmed}`);

For a complete reference of the methods available, please see the Custom Function Reference page.

Context Object

When a Custom Function runs in a certain "context", information about that context is made available in the function body. For details on what values are available in the function context for a given feature, please see the documentation for that feature itself.

The context object is available as the constant: context (and also with the alias: ctx).

The context object has the following properties, all of which may be undefined:

  • record - a Record
  • oldRecord - the previous value of a Record (for example, in a Record's on update event)
  • collection - a Collection
  • view - a View
  • webhookBody - the parsed JSON body of the request that trigger the current webhook (only used for webhooks)

For example, in a Custom Function which marks the "current" Record as "complete" and saves the completion timestamp:

// Get the "current" record
const r = ctx.record;
// Ensure the record exists
if (!r) return H.alertToast("No record selected!");
// Ensure the record is in the desired collection
if (r.collectionId !== "4ryLOYrjFSyN6x0CK33ME") return H.alertToast("Record in wrong collection!");

// Mark the record as complete
r.setFieldByKey("status", "complete"); // "select" field
r.setFieldByKey("completedAt", new Date().toISOString()); // "timestamp" field
await r.save();
H.alertToast("✓ Marked as complete");

Autocompletion

Autocompletion options and type hints are provided for many of the methods and the objects they return. The type information is generated from the Collection, Field, and View settings.

This enables functions to be written without needing to refer back to the settings.

To view type information for a method or variable, hover the mouse over it in the editor, or use the keyboard shortcut Ctrl+K Ctrl+I.


Do you think something is missing from the docs? Let us know