Custom Node API

A reference for building custom nodes: parameters, parameter types, groups, the Param Compare and Each nodes, and why a save can be refused.

Parameters let the people who use your custom node change how it behaves without touching its logic. This page is the reference for building them. For finding, installing and updating custom nodes, see Using Custom Nodes.

Defining parameters

In the custom node editor, the Parameters block sits at the top of your node. Click Add Parameter to add one. Each parameter has:

Name: the name you use in your logic, as $Name. It must be unique within the node.
Display Name: the label people see when they use your node. Leave it blank to show the name.
Group: which parameter group it appears in (see below), or None.
Type: what kind of value it holds. See the types below.
Description: help text shown to people using your node. Say what the parameter does and what a good value looks like.
Default Value: the value everyone gets until they change it.

The gear button next to a parameter opens a menu with Move Up, Move Down and Remove. List parameters also get Sort Alphabetically.

Using parameters

Write $ followed by the parameter's name anywhere in your node's logic, for example $WORD. When the node runs on a feed, each $WORD is replaced with that feed's value.

How a value is inserted depends on the parameter's type and on the node you use it in.

Parameter types

input

Plain text. The value is inserted exactly where you put $NAME.

regex

Text meant for a Regex node. The value is escaped so that characters like . or ? are matched literally, which means people using your node can type a word or phrase without knowing regex.

number

A number. Use it with nodes that take a number, such as a threshold or a score. If $NAME is the whole field, a number is inserted; if it's part of a longer piece of text, the number is inserted as text.

Switch on Is Percentage? to show the value to users as a percentage.

toggle

An on/off switch. On its own it doesn't change anything; pair it with a Param Compare node to switch part of your logic on or off (see below).

list

A list of values, built for nodes that take lists: Word List, Entity List and Users. Use $NAME in the list and it expands into every item.

Only use list parameters in nodes that take lists. You can also loop over a list with the Each node.

select

A drop-down of options you choose. Under Options, add each choice with Add Option. Switch on Custom Labels to show each option with a friendly Label while your logic receives its Value.

Parameter groups

When a node has many parameters, group them. The Parameter Groups block lets you Add Group, give it a Name and a Description, and then pick that group in each parameter's Group field. People using your node see the parameters arranged under those groups.

Nodes only available in custom nodes

The custom node editor has a few extra nodes built for parameters.

Param Compare

Checks what one of your parameters is set to. Pick the parameter on the left, a comparison in the middle and a value on the right.

For a toggle or a select, the value box offers exactly the values that parameter can hold (true or false, or your options), so you can't compare against something impossible.

Use cases:

Is a number parameter above or below a value?
Is a toggle on or off?
Is a select set to a particular option?

A common pattern for a toggle: put a Param Compare ($Animals is true) and the logic you want together in an All of these Logic node. That logic only applies when the toggle is on. Add a second branch with $Animals is false for what should happen when it's off, and wrap both branches in Any of these.

Each

Repeats the nodes inside it once for every item in a list parameter. Inside, use your parameter's name followed by _ITEM to mean the current item: for a list called $ANIMALS, that's $ANIMALS_ITEM.

In this example, for every animal in $ANIMALS the node adds a Word List matching both the singular and the plural.

Using a custom node inside a custom node

You can add another custom node to the one you're building, from the custom nodes palette in the editor.

The inner node is copied in at the version it's on when you add it. Later updates to it don't reach your node. When a newer version exists, your node's page tells you which copy is behind and by how many versions. To take the newer version, remove the inner node and add it again, and check what that changes before you save.

A node can't contain a copy of itself, directly or through another node.

When a save is refused

Once a node exists, Graze checks it each time you save. If something would break it for the people who use it, the save is refused with a message starting "Cannot save this node:" that says what to fix:

The defaults don't work. Everyone who installs your node starts with its default values, so those defaults have to produce working logic. A common cause is a list parameter with an empty default, or an Each over a parameter that isn't a list.
A Param Compare can never be true. For example, comparing a toggle with a word, or a select with a value that isn't one of its options. That branch could never run, so pick the value from the drop-down beside the comparison.
The node contains itself, directly or through a chain of other nodes. Remove the copy.
The node is too large. This almost always means a node has been embedded inside itself.

A brand-new node is only checked for size, so you can save work in progress before it's finished.