Clips

Using Clips in the Metaforms Editor

Metaforms integrates Clips to accelerate survey programming. Accessible via the Command Dialog (Cmd+M / Ctrl+M), this feature lets you import, manage, and execute reusable code snippets directly in the editor.

Metaforms is fully compatible with the NoteTab Clipbook (.clb) format, so you can bring existing personal and team libraries into the editor seamlessly.

1. Clip Libraries in Metaforms

When you open the Command Dialog, you’ll see three types of libraries available:

1. Global Metaforms Clips

   • Built-in formatting commands and utilities.

   • Protected: Cannot be modified or deleted.

2. Forsta Decipher NoteTab Clips

   • Pre-imported library of 140 industry-standard clips from the open-source Decipher collection.

   • Protected: Cannot be modified or deleted.

3. Your Clips

   • Any .clb files you import.

   • Fully editable: You can rename, edit, or delete clips individually or in bulk.

2. Importing .clb Clipbooks

Adding your own library is straightforward:

1. Open the Command Dialog (Cmd+M / Ctrl+M).

2. Expand the Import Clips section.

3. Drag and drop a .clb file, or click Select File.

File Name Conflicts

If a file with the same name already exists, you’ll be prompted to:

• Replace → Overwrite existing clips with the new file.

• Rename → Import under a new name (e.g., MyClips (1).clb).

• Cancel → Abort the import.

3. Understanding the .clb File Format

Metaforms parses .clb files into two types of clips:

• Text Clips → Insert static text.

• Script Clips → Execute Python code to transform editor content.

Supported Syntax

NoteTab Syntax	How Metaforms Handles It
H="Clip Name"	Defines a clip’s display name.
H=";Section Name"	Creates a category heading in the UI.
^!InsertText ...	Inserts static text.
^!RunScript scriptName	Executes a Python script defined in the file.
^!If ... ELSE ... GoTo	Not evaluated. Instead, each branch is imported as a separate clip (e.g., ClipName:Branch).

4. Conditional Logic in Clips

Conditional logic is parsed but never executed. Instead, each branch becomes its own clip.

Example

H="Make Radio"
^!If ^%p_ReqValue% = "FMA Requirements" FMA ELSE Generic

:Generic
^!RunScript makeRadio

:FMA
^!RunScript makeRadioFMA

Becomes two selectable clips:

• Make Radio:Generic

• Make Radio:FMA

5. Script Clips in Metaforms

Script Clips let you run Python code to transform text in the editor.

The Input/Output Contract

• Input (Mandatory) Must begin with:

  from sys import stdin
  input = stdin.read()

  → This captures the selected text from the editor.

• Output Use print to return transformed text, which replaces the selection.

Allowed vs Restricted Capabilities

✅ Allowed:

• String manipulation, loops, regex (re module).

• Full Python standard library (except restricted features).

❌ Restricted:

• File access (open(), os.path).

• Network requests (urllib, requests).

• Non-standard libraries.

6. Script Example

.clb Definition

H="Make li per line"
^!RunScript makeLi

H="makeLi"
try:
    from sys import stdin
    input = stdin.read().strip()
    lines = input.split("\n")
    for line in lines:
        print "<li>%s</li>" % line.strip()
except Exception, e:
    print e

User Action Selected text:

First item
Second item
Third item

Result After Running Clip

<li>First item</li>
<li>Second item</li>
<li>Third item</li>

---

7. Unsupported Syntax

Some NoteTab commands rely on state or desktop UI and cannot be replicated in a web environment.

Ignored or Modified

Command / Syntax	Metaforms Behavior
^!Set, ^!SetArray, ^!Append	Ignored – no persistent variables.
Variable usage (^%Var%)	Ignored – placeholders not substituted.
^!If, ^!IfFalse	Parsed only – branches imported as separate clips.
^!Prompt, ^!StatusShow, ^!Delay	Ignored – no UI dialogs.
^!URL	Ignored – won’t open links.
^!GoTo	Parsed only for conditional branches.

8. Troubleshooting

• Error: "Unable to Parse this file" → File may not be a valid .clb (missing H="..." headers).

• Missing Clips After Import → Headers like H=";" are ignored. Use descriptive names.

• Python Script Doesn’t Appear → Script blocks must be called with ^!RunScript. Standalone scripts are ignored.

• Script Runs but Fails → May use unsupported features (file I/O, networking). Simplify logic to text-only processing.