From 1a83aff724cbd6104081343af966a8124884bc4a Mon Sep 17 00:00:00 2001 From: Benjamin Chausse Date: Tue, 16 Dec 2025 13:39:26 -0500 Subject: [PATCH 1/3] docs --- .vitepress/sidebars/reference.ts | 4 ++ src/reference/workflow_interpolation.md | 78 +++++++++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 src/reference/workflow_interpolation.md diff --git a/.vitepress/sidebars/reference.ts b/.vitepress/sidebars/reference.ts index 020f466c..faa99afc 100644 --- a/.vitepress/sidebars/reference.ts +++ b/.vitepress/sidebars/reference.ts @@ -45,6 +45,10 @@ export const referenceSidebar: DefaultTheme.SidebarItem[] = [ text: "Node Data Types", link: "/reference/workflow_data_types", }, + { + text: "Interpolation", + link: "/reference/workflow_interpolation", + }, { text: "SDK", link: "https://developer.caido.io/reference/sdks/workflow/", diff --git a/src/reference/workflow_interpolation.md b/src/reference/workflow_interpolation.md new file mode 100644 index 00000000..636ba2e1 --- /dev/null +++ b/src/reference/workflow_interpolation.md @@ -0,0 +1,78 @@ +--- +description: "Find detailed reference information on Caido Interpolation within workflow nodes allowing rich and dynamic reporting." +--- + +# Interpolation + +Interpolation enables dynamic content generation within workflow nodes by +embedding [JavaScript](#javascript-engine) expressions in text. Those +expressions can take the following shapes: + +1. [Inline](#inline-evaluation) +2. [Code Blocks](#tagged-code-blocks) + +## Inline Evaluation + +Inline interpolation uses `<% %>` delimiters to execute JavaScript expressions +and output results in-place within text. + +### Escaping + +Use `\<% %>` to display literal interpolation syntax without execution (shows as `<% %>`). + +### Comments + +| Syntax | Description | +|--------|-------------| +| `<% value // comment %>` | Line comments - `%>` closes the interpolation block. | +| `<% /* comment with %> */ value %>` | Block comments for including `%>` in comments. | + +## Tagged Code Blocks + +| Tag | Description | +|-----|-------------| +| `exec` | Markdown code blocks with this tag are evaluated by the JavaScript engine. | + +### Output Functions + +| Function | Description | +|----------|-------------| +| `print(...values)` | Outputs values without newline. | +| `println(...values)` | Outputs values with newline. | + +::: warning NOTE +Only explicitly printed content appears in final output. The `exec` code block +itself is not visible. +::: + +::: tip +As [all fields share the same context](#shared-context), pre-compute complex +values in `exec` blocks without print statements, then reference variables in +simple `<% variable %>` interpolations for improved readability. +::: + +## Javascript Engine + +Interpolation uses Caido's JavaScript runtime environment. See [JavaScript in +Workflows](/concepts/workflows_js) for understanding JavaScript concepts in +workflows and refer to the [Runtime +documentation](https://developer.caido.io/concepts/runtime.html) for detailed +technical specifications. + +### Accessing previous nodes + +All previous node outputs within a workflow are accessible using their +[alias](/concepts/workflows_nodes.html#aliases), allowing interpolation to use +values from earlier nodes in the workflow chain. + +### Shared context + +All Interpolable fields within a workflow node share the same execution context +which entails the following: + +- **Execution Order**: Interpolations execute sequentially in the order they + appear within the node, allowing building upon previous computations. +- **Shared Context**: All interpolations in a single node share the same + JavaScript environment, meaning variables, functions, and state are accessible + across all expressions within that node. + From dcc2e6269531685cea6399caea0d6a4222621e15 Mon Sep 17 00:00:00 2001 From: Benjamin Chausse Date: Tue, 16 Dec 2025 15:14:59 -0500 Subject: [PATCH 2/3] hello-world like example for inline interpolation --- src/reference/workflow_interpolation.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/reference/workflow_interpolation.md b/src/reference/workflow_interpolation.md index 636ba2e1..99eb6afb 100644 --- a/src/reference/workflow_interpolation.md +++ b/src/reference/workflow_interpolation.md @@ -14,7 +14,15 @@ expressions can take the following shapes: ## Inline Evaluation Inline interpolation uses `<% %>` delimiters to execute JavaScript expressions -and output results in-place within text. +and output results in-place within text. For example: + +```md +# Found <% issue_count %> issues +lorem ipsum dolor ... +``` +::: warning NOTE +The example above assumes a `issue_count` variable was previously declared. +::: ### Escaping From 8179ea8a062d56c1db46a767182a4ac4372ce1df Mon Sep 17 00:00:00 2001 From: Benjamin Chausse Date: Tue, 16 Dec 2025 15:34:41 -0500 Subject: [PATCH 3/3] tweaks --- src/reference/workflow_interpolation.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/reference/workflow_interpolation.md b/src/reference/workflow_interpolation.md index 99eb6afb..0d66accf 100644 --- a/src/reference/workflow_interpolation.md +++ b/src/reference/workflow_interpolation.md @@ -18,7 +18,6 @@ and output results in-place within text. For example: ```md # Found <% issue_count %> issues -lorem ipsum dolor ... ``` ::: warning NOTE The example above assumes a `issue_count` variable was previously declared. @@ -33,13 +32,18 @@ Use `\<% %>` to display literal interpolation syntax without execution (shows as | Syntax | Description | |--------|-------------| | `<% value // comment %>` | Line comments - `%>` closes the interpolation block. | -| `<% /* comment with %> */ value %>` | Block comments for including `%>` in comments. | +| `<% /* comment with %> */ value %>` | Block comments allow including `%>` in comments. | ## Tagged Code Blocks -| Tag | Description | -|-----|-------------| -| `exec` | Markdown code blocks with this tag are evaluated by the JavaScript engine. | +Markdown-style code blocks with the `exec` tag are evaluated by the JavaScript engine. For example: + +````md +```exec +const issue_count = 5; +println("# Found " + issue_count + " issues"); +``` +```` ### Output Functions @@ -83,4 +87,3 @@ which entails the following: - **Shared Context**: All interpolations in a single node share the same JavaScript environment, meaning variables, functions, and state are accessible across all expressions within that node. -