Project formulas

Project formulas provide a way to create reusable calculations and logic that can be accessed from any page or component in your project. Unlike component-level formulas that are only available within a specific component, project formulas can be used throughout your entire application.

When to use project formulas

Project formulas are ideal for:

Common calculations used across multiple components
Shared data transformations
Utility functions like date formatting or number parsing
Business logic that needs to be consistent throughout the application
Complex operations that might be reused

Using project formulas ensures consistency in your application and reduces duplication of code.

Create a project formula

The project sidebar is visible in the editor, showing a list of formulas in the formula section. Formulas are named, for example, getCssVariable, getDefaultTrue, getTradition. On the left, the getDefautTrue formula editor is visible, showing a snapshot of the formula notes that make up this formula. The formula takes an input of name value, and checks to see if it equals false. Further logic is calculated in an if formula node. If it equals false, if returns false, else it returns true. Tne image is also annotated with numbers that correspond to the list items below.

Live

To create a project formula:

1
Open the project sidebar by clicking the folder icon or using Cmd/Ctrl + K
2
Find the Formulas section, click the + button and name your formula
3
Optionally add arguments as input parameters
4
Define your formula logic using either
(A) The formula editor, or
(B) Custom JavaScript code by clicking the Convert to custom code button at the bottom left of the screen

Project formulas appear in the formula selection dropdown throughout your project, making them easily accessible from any component or page.

Custom code formulas

Custom code formulas extend the capabilities of the standard formula editor by allowing you to write JavaScript directly. This enables you to implement functionality that isn't available through the built-in formula components.

The custom code formula editor is visible. On the left the formula contains a description and a single input argument named value, with a type of unknown. On the right is a text editor that looks like an IDE, containing a short function named hasValue, which takes the value argument, and processes some logic.

Live

Custom code structure

In the custom code editor, your formula must have an entry function with the same name as your formula. This function receives two parameters:

args: The defined input parameters passed to your formula
ctx: The context object that provides access to Nordcraft-specific functionality

Custom code considerations

When using custom code in project formulas, keep these important points in mind:

Pure functions: Custom formulas should be pure functions without side effects; given the same inputs, they should always return the same outputs without modifying external state
Client-side only: Custom code formulas execute in the browser only and not during server-side rendering; this can cause layout shifts during page load and may impact your page performance scores, and as a result, SEO
Synchronous execution: Custom formulas must be synchronous; do not use Promise, fetch or other asynchronous JavaScript APIs in project formulas
Shadow DOM compatibility: When components are exported as web components, use ctx.root instead of document to access DOM elements; this ensures compatibility with Shadow DOM encapsulation

Warning

Avoid adding side effects in custom formulas. Side effects can cause unpredictable behavior and should be handled by actions instead.

Danger

Be cautious when pasting code snippets from external sources into custom formulas. Custom code can execute any JavaScript you add, which may introduce security vulnerabilities if you do not trust the source.