# General Notes ### GravityOps Search Admin Page You can find a high-level overview of the GravityOps Search plugin by navigating to: - **GravityOps → Search** The **Overview** tab provides a summary of the plugin's capabilities, while the **Help** tab offers quick links to documentation, support, and community resources. The **Docs** tab provides this documentation, right in your dashboard. The **Shortcode Builder** tab (free during launch — may move to a paid tier in a future release) provides a visual, point-and-click interface for building `[gravops_search]` shortcodes. See [docs/06-shortcode-builder.md](06-shortcode-builder.md) for full usage details. The **Saved Shortcodes** tab shows all shortcodes you have saved from the builder, with one-click copy, edit-in-builder, and delete actions. --- ### Shortcode Attributes Reference | Attribute | Default | Purpose | |----------------------------|---------|-------------------------------------------------------------------------------------------------------------------| | `target` | `0` | Form ID(s) to search, comma-separated. `0` = all forms. | | `search` | — | Field IDs to filter on, comma-separated. | | `search_label` | — | Field labels to resolve to IDs and filter on, comma-separated. | | `search_type` | — | Field types to resolve to IDs and filter on, comma-separated. | | `field_match` | `first` | How label/type resolution picks fields: `first` (one per form) or `all` (every match across all forms). | | `operators` | — | Operators per search position, comma-separated. See [03-using-search-operators.md](03-using-search-operators.md). | | `search_mode` | `all` | `all` (AND) or `any` (OR) across all filter conditions. | | `search_empty` | `false` | When `true`, searches for entries where the searched field is empty. | | `display` | — | Fields/properties to output, or a template with `{id}` placeholders. | | `sort_key` | `id` | Field ID, entry property, or meta key to sort by. | | `sort_direction` | `DESC` | `ASC`, `DESC`, or `RAND`. | | `sort_is_num` | `true` | Treat sort values as numbers. Auto-set for numeric fields. | | `secondary_sort_key` | — | Secondary sort field. Ignored when primary is `RAND`. | | `secondary_sort_direction` | `DESC` | `ASC` or `DESC`. | | `limit` | `1` | Number of results to return, or `all`. | | `unique` | `false` | Return only unique formatted results. | | `separator` | — | String placed between multiple results. `__none__` for no separator. | | `default` | — | Fallback output when no entries match. Use `|` to separate per-field defaults. | | `link` | `false` | Wrap each result in a link to the entry view in the WordPress admin. | --- ### Shortcode Tips and Guidelines - To search multiple fields pass comma-separated IDs to `search` and separate the corresponding values in the shortcode content with the `|` symbol. Use `search_mode` to configure whether any or all conditions must match. To search for multiple values for the same field, repeat the field ID in `search` with the corresponding values in the content. - **Cross-form label/type search:** Use `search_label` or `search_type` to find fields by label or type across forms where the field ID differs. For example, `search_label="Email Address"` locates the first field in each target form whose label is "Email Address" and applies your filter value to it. Set `field_match="all"` to match every field with that label/type rather than just the first one per form. When resolving to multiple field IDs across forms, set `search_mode="any"` so entries match whichever form's field resolves. - **Content pipe ordering when mixing search types:** Content pipe positions follow this order — `search` field values first, then `search_label` values, then `search_type` values. The `operators` attribute maps the same way. Example — field ID, then label, then type: ``` [gravops_search target="1,2" search="3" search_label="Email" search_type="phone" operators="=,contains,=" search_mode="any"] Active|john@example.com|555 [/gravops_search] ``` Position 0 (`Active`) filters field `3`; position 1 (`john@example.com`) filters the first field labeled "Email" in each form; position 2 (`555`) filters the first field of type `phone` in each form. - Custom Formatting: Use the `display` attribute with placeholders to produce complex output — lists, tables, `mailto` links, GravityView links, and more. See [02-the-display-attribute.md](02-the-display-attribute.md). - The `search` and `display` attributes both support entry properties, field IDs, and entry meta keys (including keys added by third-party plugins such as Gravity Flow). See [Gravity Forms Entry Object](https://docs.gravityforms.com/entry-object/). - To perform a global search (any field with a given value), leave the corresponding search ID blank. - To display values from a field without filtering, omit `search`, `search_label`, and `search_type` and the shortcode content entirely. - **Sorting:** Use `sort_key` (field ID, entry property, or meta key), `sort_direction` (`ASC`, `DESC`, `RAND`), and `sort_is_num` (`true`/`false`). For secondary sorting, use `secondary_sort_key` and `secondary_sort_direction`. Secondary sorting is ignored when primary direction is `RAND`. - Use `unique="true"` to return only unique results. Results are compared as formatted strings — two values that differ by even one character are treated as distinct. - To search for empty values, leave the shortcode content blank and set `search_empty="true"`. - Use the `default` attribute to specify a fallback when no entries match or a display field is blank. Separate multiple per-field fallbacks with `||`. - Use `link="true"` to wrap each result in a link to the entry in the WordPress admin. - Avoid using the pipe (`|`) character inside search values — escaping is not supported and will produce incorrect results. - The `[gravops_search]` shortcode does not restrict access by default. Anyone who can view the page can see the results, including Gravity Forms entry data. Protect sensitive information by placing the shortcode inside access-controlled pages (e.g., membership plugins, password protection, or role-based visibility). - Each shortcode runs a live database query. `limit="all"` loops through results in pages of 25 until exhausted. To improve performance: cap results with `limit`, minimize nested shortcodes, and consider caching the page output. - If there are more search IDs than content values, extra fields search for blank entries. Extra content values beyond the number of IDs are ignored.