[Deprecated] CustomFunctions:Home - bettyblocks/cli Wiki

This feature is deprecated

Please use Action Functions to add coded solutions to your application. All functions need to be migrated as this feature will be shut down over time.

The documentation below serves solely to help to migrate functions to the new Actions Functions setup.

What are custom functions?

Custom functions (also referred as custom code) enable application builders to extend their actions toolset (the "native" events) with their own written Javascript code. They are seemlessly executed with native events.

Can I use NPM packages?

Yes but not all of them. As custom functions are labelled as untrusted code, they will be executed in an isolated environment. There are certain restrictions in what you can and cannot do within the code (e.g. using the file system is not allowed).

Getting started

In order to use custom functions within your Betty Blocks application, please follow these steps:

  1. Install the CLI
  2. Initialize the custom functions project
  3. Build your project
  4. Publish the custom code to your application

1. Install the CLI

To install the CLI globally you will need a recent version of Node.js.

$ npm install -g @betty-blocks/cli

2. Initialize the custom functions project

The init command initializes an NPM based Javascript project containing two example custom functions:

  • src/say-hello.js - which demonstrates how to acquire the name input variable value using the context() helper function and how to use Lodash' join function

  • src/all-users.js - which demonstrates how to query for application data using the gql() helper function

You need to pass the subdomain of your application. So if your application is available at https://awesome.bettyblocks.com then the subdomain is awesome.

$ bb functions init awesome
Initialized functions project in /Users/betty-functions/awesome.
You can use "bb functions" to build and/or publish it:

    cd awesome
    bb functions build
    bb functions publish

Please note that It is recommended to create a separate Javascript file for every custom function. Do not forget to export your custom functions in src/index.js.

Available helper functions

The following helper functions are available in custom functions:

  • context(name) - acquire the value of input variables: async

  • console - log messages in the application logs e.g. console.debug(message)

  • gql(query) - execute GQL queries compliant to the Betty Data API: async

  • mapAsync(collection, function) - asynchronously map either an array or object: async

  • request(url, options) - execute an HTTP or HTTPS request: async

3. Build your project

The build command is for debugging purposes really because (at default) publishing custom code will trigger building the project first. It builds the project using webpack under the hood and whenever a build has failed, you can use the build command to view the webpack output.

$ bb functions build
Building awesome.bettyblocks.com bundle (this can take a while) ...
npm WARN deprecated [email protected]: fsevents 1 will break on node v14+ and could be using insecure binaries. Upgrade to fsevents 2.
    Asset     Size  Chunks             Chunk Names
custom.js  1.4 KiB       0  [emitted]  main
Entrypoint main = custom.js
[1] ./src/index.js + 2 modules 544 bytes {0} [built]
    | ./src/index.js 112 bytes [built]
    | ./src/say-hello.js 245 bytes [built]
    | ./src/all-users.js 182 bytes [built]
    + 1 hidden module

4. Publish the custom code to your application

The publish command does the following:

  1. Builds the project using webpack unless passed the -s or --skip flag
  2. Grooms the functions.json file
  3. Bumps the revision number if passed the -b or --bump flag
  4. Updates the custom functions meta data conforming the functions.json file
  5. Uploads the webpack bundle
  6. Compiles "new runtime" actions

Please note that you are asked to fill in your Betty credentials when publishing the custom code for the first time.

$ bb functions publish -b
Publishing to awesome.bettyblocks.com ...
✔ Building custom functions bundle (this can take a while) ...
Grooming functions.json ...
✔ Fill in your e-mail address … [email protected]
✔ Fill in your password … ********
✔ Updating custom function "sayHello" ...
✔ Updating custom function "allUsers" ...
✔ Uploading "2.js" ...
✔ Compiling action "My awesome action" ...