> For the complete documentation index, see [llms.txt](https://codifi-fdm.gitbook.io/codifi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codifi-fdm.gitbook.io/codifi-docs/cross-platform-features/ripple.md).

# Ripple

**Ripple is Codifi's built-in formula engine.** It lets you add intelligence to your forms without writing any code. With Ripple, fields can calculate their own values, show or hide based on other fields, pull data from parent and child Records, measure distances and areas from GPS coordinates, and build dynamic text summaries — all automatically.

Think of Ripple like the formula bar in a spreadsheet, but designed for structured field-data collection. Instead of cell references like `=A1+B1`, Ripple uses **field labels** and **Record relationships** to compute values across your entire Project hierarchy.

***

## What Ripple Can Do

| Capability                  | What It Means                                         | Example                                             |
| --------------------------- | ----------------------------------------------------- | --------------------------------------------------- |
| **Calculated Fields**       | Fields that compute their own values automatically    | Total Weight = sum of all artifact weights          |
| **Conditional Visibility**  | Show or hide fields and sections based on data        | Show "Historic Period" only when Type = Historic    |
| **Spatial Analysis**        | Measure distances, areas, and positions from GPS data | How far is this find from the survey transect?      |
| **Cross-Record Lookups**    | Pull values from parent, child, or sibling Records    | Display the parent site name on each feature Record |
| **Aggregation & Summaries** | Sum, count, and concatenate data across Records       | This site contains 47 features and 312 artifacts    |
| **Date Calculations**       | Compute durations, deadlines, and formatted dates     | Days in field = End Date − Start Date               |
| **Media Awareness**         | React to attached photos, documents, and files        | Show warning if fewer than 3 photos attached        |
| **Completion Tracking**     | Monitor form progress and required-field status       | Record is 85% complete (17 of 20 required fields)   |

{% hint style="info" %}
Ripple formulas are set up in the **Composition** (template) editor by your Project administrator. Once configured, they run automatically for everyone on the team — on mobile, on the web, and even offline.
{% endhint %}

***

## How Ripple Works

### The Two Types of Formulas

| Formula Type           | Purpose                                      | When It Runs                            | User Override?                            |
| ---------------------- | -------------------------------------------- | --------------------------------------- | ----------------------------------------- |
| **Value Formula**      | Computes a field's value automatically       | When the field is empty (no user input) | **Yes** — user input always wins          |
| **Visibility Formula** | Controls whether a field or section is shown | Every time data changes                 | **No** — always controlled by the formula |

**Key principle: user input always wins.** If a field has a value formula but the user types something in, the user's value is kept. Value formulas only fill in fields that are empty. This means Ripple provides smart defaults that users can override when needed.

### Cascading Formulas

Formulas can depend on other formulas. For example, a *Total Cost* field might depend on *Quantity* and *Unit Price*, while a *Budget Status* visibility rule depends on *Total Cost*. Ripple automatically detects these dependencies and re-evaluates in cycles until everything stabilizes. **You don't need to worry about ordering** — Ripple handles it.

### Where Ripple Runs

| Platform              | How Ripple Runs                                                      |
| --------------------- | -------------------------------------------------------------------- |
| **Codifi Mobile App** | Formulas evaluate locally on your device — even offline in the field |
| **Codifi Web App**    | Formulas evaluate in the browser as you enter data                   |
| **Backend (Server)**  | Formulas re-evaluate when data syncs to ensure consistency           |

{% hint style="info" %}
Because Ripple runs on all platforms, your calculated fields and visibility rules work identically whether you're in the field on your tablet or back at the office on the web.
{% endhint %}

***

## Sections in this Guide

Ripple is broken into focused sub-pages so you can jump straight to what you need:

| Page                                                                                        | Use it when you want to…                                                                                                              |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| [Value Formulas](/codifi-docs/cross-platform-features/ripple/value-formulas.md)             | Compute a field's value automatically — math, text, dates, lookups across Records                                                     |
| [Visibility Formulas](/codifi-docs/cross-platform-features/ripple/visibility-formulas.md)   | Show or hide fields and sections based on other field values                                                                          |
| [Spatial Formulas](/codifi-docs/cross-platform-features/ripple/spatial-formulas.md)         | Measure distances, areas, perimeters, bearings, and check containment from GPS data                                                   |
| [Aggregation Formulas](/codifi-docs/cross-platform-features/ripple/aggregation-formulas.md) | Sum, count, and average across repeater rows or child Records                                                                         |
| [Media & Completion](/codifi-docs/cross-platform-features/ripple/media-and-completion.md)   | React to photos and attachments, track form completion, and enforce documentation                                                     |
| [Real-World Examples](/codifi-docs/cross-platform-features/ripple/examples.md)              | See full configurations for common CRM patterns — prehistoric/historic switching, point-to-line QC, site summary paragraphs, and more |
| [Operations Reference](/codifi-docs/cross-platform-features/ripple/reference.md)            | Look up every operator Ripple supports, plus tips and best practices for formula authors                                              |

***

## Where Calculated Fields and Conditional Visibility Live in the Library

Ripple powers the [Calculated Fields](/codifi-docs/cross-platform-features/calculated-fields.md) and [Conditional Visibility](/codifi-docs/cross-platform-features/conditional-visibility.md) features in the Library. The pages above go deeper than those concept overviews — start with the concept page, follow links into this section when you need the formula details.