Custom code - API

Custom code in formulas and actions is almost entirely vanilla javascript. However, there is a thin API to access toddle internals that you might find useful.

Custom actions and formulas can contain any number of functions, but they must contain their entry function. The entry function is named the same as your code file. If your file is called showModal then your entry function is called:

function showModal(args, ctx) { ... }

Formulas

Formulas are functions. Given some inputs, they produce an output. This could be Add, which takes a and b and returns their sum. Almost all common functions already exist as built-in formulas in toddle. We have found that you can achieve nearly anything by composing the built-in formulas.

Formulas are synchronous, so you should not use Promises, Fetch or similar asynchronous APIs in your custom formulas. Instead, for such cases you can use an asynchronous custom action with a callback to another workflow with the value. You can then use the callback to set a variable that can be used in your formulas.

Please note: formulas written in code, only run/evaluate client side. This means you could see layout shifts when using custom formulas since they won't be evaluated correctly server side.

Root

All toddle components may be exported as web components. This opens an important caveat, due to the nature of web components' Shadow DOM: DOM elements are inaccessible through the `document` scope. Trying to `document.getElementById` will work fine in the editor and pages, but if used in a component exported as a web component, the element will not be found. The solution is to use toddle's `ctx.root` element instead of `document`. Root is either equal to the `document` or the `Shadow Root` if loaded as a web component.

You can find the `root` in the context object (second parameter of your entry function) along with the rest of toddle's API.

Actions

toddle expects exactly one function to have the same name as your custom action. This is the entry point. It is called with two arguments:

• The first is an object with the arguments that the action is called by. If your action has an argument called "foo" that is called with "bar", then your arguments object will look like `{ foo: "bar" }`
• The second argument is your current context. This context contains a function "triggerActionEvent" to trigger your events.

Trigger action event

Unlike formulas, actions do not have a return value. Instead, actions may perform callbacks to other workflows with the triggerActionEvent.

function showModal(args, ctx) { ctx.triggerActionEvent("my-action-name", data) }

Events can be called asynchronously, so you could use a setTimeout or call an API, and then call your triggerActionEvent to call another workflow after a wait. This is exactly what the built-in sleep action does in toddle. toddle actions and formulas are built in the same way as your custom code. No magic 🪄

Warning: Formulas and actions can run any code you put into them, so be careful of malicious attempts when you paste code-snippets onto your app. Additionally, formulas should not contain side-effects, leave this to actions. If a formula is not a pure function then it might cause you some nasty bugs and reduce scalability and maintainability of your project.

Cleaning up after yourself

Formulas are pure functions and are not meant to perform any side effects. Actions, however, often cause side-effects, such as setting a timeout with `setTimeout`, or adding event listeners `addEventListener`. To avoid event and memory leaks, you should aim to clean these effects up with `clearTimeout` etc.

If an action returns a function, that function will run when the parent component is unmounted. Unmouth happens when the component is no longer rendered, either due to the page closing or a show/hide or repeat changes somewhere in the tree that affects the component to no longer be rendered.