---
title: Shortcode Builder
description: "> **This feature is available in GravityOps Search Premium.** ## Overview The Shortcode Builder is a visual, point-and-click tool built directly into the GravityOps Search admin page. It lets you construct `[gravops_search]` shortcodes interactively without writing any shortcode syntax by…"
url: "https://brightleafdigital.io/docs/shortcode-builder/"
updated: "2026-11-17"
category: GravityOps Search
---

# Shortcode Builder

> **This feature is available in GravityOps Search Premium.**

## Overview

The Shortcode Builder is a visual, point-and-click tool built directly into the GravityOps Search admin page. It lets you construct `[gravops_search]` shortcodes interactively without writing any shortcode syntax by hand. Every attribute, search filter, display option, and output template is wired to a live UI control, and the shortcode preview updates in real time as you configure it.

Navigate to **GravityOps → GravityOps Search → Shortcode Builder** to open it.

---

## Building a shortcode

### 1. Target forms

Choose which Gravity Forms to search:

- **All forms** — check "All forms" to query every form on the site (`target="0"`).
- **Specific forms** — leave the checkbox unchecked and tick one or more forms from the list. The first selected form is the *primary form* and drives the field-aware UI (field dropdowns, sort options, entry meta display, etc.). You can reorder the selection or mark a different form as primary using the "Make primary" button on each chip.

### 2. Attributes

The **Attributes** card covers the core shortcode settings:

| Setting | Shortcode attribute |
| --- | --- |
| Match mode (ALL / ANY) | `search_mode` |
| Search empty values | `search_empty` |
| Sort by / direction / numeric | `sort_key`, `sort_direction`, `sort_is_num` |
| Secondary sort | `secondary_sort_key`, `secondary_sort_direction` |
| Limit | `limit` |
| Unique results only | `unique` |
| Result separator | `separator` |
| Default value(s) | `default` |
| Wrap in admin entry link | `link` |

### 3. Search filters

Three buttons let you add different kinds of filter rows:

- **+ Add filter** — filter by a specific field ID or entry property chosen from a dropdown.
- **+ By label** — filter by field label. The builder emits `search_label` and resolves to the actual field ID(s) at runtime, so the shortcode works across multiple forms even when field IDs differ.
- **+ By type** — filter by field type (e.g., `email`, `text`, `select`). The builder emits `search_type`.

Each row has:

- **Mode selector** (`By ID` / `By Label` / `By Type`) — set when the row was added; can be changed at any time. Switching mode resets the field/label/type value.
- **Field / label / type input** — for By ID rows, a dropdown populated from the primary form's fields, entry properties, and detected entry meta (including Gravity Flow workflow keys). For By Label or By Type rows, a free-text input.
- **Operator** — available operators adjust to the field type for By ID rows (numeric fields get `gt`, `lt`, etc.; boolean fields get `=` and `!=` only). By Label and By Type rows show the full operator list.
- **Value** — plain text, a number, a date picker, or a comma-separated list for `in` / `not in` operators.

Rows can be reordered by dragging the numbered handle on the left. Click **Remove** to delete a row.

#### Field match (label and type rows)

When at least one By Label or By Type row is present, a **Field match** setting appears:

| Value | Behaviour |
| --- | --- |
| `first` (default) | Resolves to the **first** field in each target form with the matching label or type |
| `all` | Resolves to **every** field in each target form with the matching label or type |

This emits `field_match="all"` in the shortcode when set to "All matches"; the attribute is omitted when using the default `first`.

#### Operator and content ordering

When shortcodes mix search types, content pipe positions and operator positions follow this order: By ID rows first, then By Label rows, then By Type rows. The builder handles this automatically — the live shortcode preview always reflects the correct ordering.

#### Validation hints

The validator warns when:

- A By Label or By Type row has no label/type set.
- Label or type filters span multiple forms without `search_mode="any"` — different field IDs resolve per form, so ANY mode is usually correct in this case.

### 4. Display

Switch between the two output modes using the tabs under the **Display** card:

**Simple field list** — tick one or more fields, entry properties, entry meta keys, or special values (`meta`, `num_results`). Each entry outputs those values in order. Use "Discover available meta keys for this form" to run a quick introspection query that lists every key present in the most recent entry.

The field list groups items under:

- **Entry properties** — standard GF entry fields (ID, date created, payment status, etc.)
- **Fields — [Form title]** — all fields on the primary form, including sub-inputs for Name and Address fields.
- **Entry Meta — [Form title]** — extra meta keys detected in the form's most recent entry (e.g., Gravity Flow workflow step meta, custom plugin meta). This section only appears when at least one entry exists.
- **Special** — `meta` (dump all available keys) and `num_results` (count of matched entries).

**Template builder** — stack blocks to assemble a per-entry output template:

| Block type | What it does |
| --- | --- |
| Text | Literal text inserted verbatim |
| Field placeholder | Inserts a field, property, or meta value: `{13}`, `{gos:workflow_step_id}`, etc. |
| HTML wrapper | Wraps child blocks in an HTML element with optional attrs/classes |
| Nested shortcode | Emits a `{{shortcode}}` that the plugin resolves after placeholder substitution |
| Special | `{num_results}` or `{gos:num_results}` |

Blocks can be nested inside HTML wrappers and reordered by dragging. The field placeholder picker includes the same **Entry Meta** group as the simple field list, giving you access to Gravity Flow and other plugin meta in templates.

---

## Sidebar tools

### Live shortcode preview

Displays the current shortcode. Click **Display Shortcode** to refresh, or **Copy Shortcode** to copy it to the clipboard with one click.

### Validation

Runs automatically and flags common issues:

- **Error** (red) — the shortcode will not work correctly as configured (e.g., no form selected, pipe character in a value, bare `gos:id` used with a text key, By Label/Type row with no value set).
- **Warning** (yellow) — likely unintended configuration (e.g., `in` operator with no values, label/type filters spanning multiple forms without `search_mode="any"`).
- **Info** (blue) — informational notes (e.g., multi-form mode, `limit="all"` performance reminder, default/display count mismatch).

### Test run

Click **▶ Run shortcode** to render the current shortcode on the server and preview the output in the panel. This is a live query — it reflects the actual entries in your database.

### Save shortcode

Enter a name and click **Save** to persist the current shortcode and its builder state to the **Saved Shortcodes** tab. Saved shortcodes are stored site-wide and visible to all users with the appropriate capability.

### Presets

Presets are personal (per-user) saves of the full builder state. They are useful for storing partially-built configurations or frequently reused setups that you want to come back to without saving a final shortcode. Presets are separate from Saved Shortcodes.

**Starter templates** give you a pre-configured state as a starting point for common patterns.

---

## Saved Shortcodes tab

Navigate to **GravityOps → GravityOps Search → Saved Shortcodes** to manage all shortcodes saved from the builder.

Each card shows:

- **Name** and the date it was saved.
- **Shortcode** — click anywhere on the code block to copy it to the clipboard. The block flashes green on a successful copy.
- **Edit in Builder** — loads the saved state back into the Shortcode Builder tab so you can modify it and re-save.
- **Delete** — removes the entry after a confirmation prompt.

---

## Data storage and cleanup

| Data | Where stored | Removed on uninstall |
| --- | --- | --- |
| Saved shortcodes | `wp_options` (`gosp_saved_shortcodes`) | Yes |
| Per-user presets | `wp_usermeta` (`gosp_sb_presets`) | Yes — all users |

## Stuck? Ask in GravityOps Help

Search past answers or post your question, tagged "search".

[Ask in GravityOps Help](https://brightleafdigital.io/community/gravityops-help/?gofrm_tag=search)[Open a support request](https://brightleafdigital.io/support/)

GravityOps Weekly

[This iframe contains the logic required to handle Ajax powered Gravity Forms.](about:blank)
