# 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.

<figure><img src="https://1402057010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgtHd8o9ldznZ1hKHiZvc%2Fuploads%2F9Ml1H4MRKfHfw9slIfo5%2Fimage.png?alt=media&#x26;token=3e243e4e-e6ae-438a-8daa-002e16a893da" alt=""><figcaption></figcaption></figure>

### **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](https://github.com/decipher-survey-programming/decipher-notetab-clips/blob/master/Decipher-Surveys-Latest.clb).
   * **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**.

<figure><img src="https://1402057010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgtHd8o9ldznZ1hKHiZvc%2Fuploads%2FUhhscUMMFliGhVDuWafh%2Fimage.png?alt=media&#x26;token=2b08af89-bb95-4466-a07d-3746c2cbfaad" alt=""><figcaption></figcaption></figure>

#### **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**

```clb
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:

  ```python
  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**

```clb
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**

```html
<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.