Ripple documentation

Start here#

Ripple finds saved content references to WordPress plugins. It helps you review a removal or replacement, trace affected content and prepare a report. This guide describes development preview 0.11.0. Public purchases are not open yet.

1. Install and activate Ripple on a staging site.
2. Open Ripple → Overview and run a scan.
3. Open a plugin’s impact report. Read its dependencies and inspect the affected content.
4. Review unresolved findings, save notes and test the planned change on staging.

The guided introduction highlights the main controls. Open Help and choose Start guided introduction to run it again. Each administrator has their own dismissal state. The preview also includes a temporary setting to replay it after every refresh.

Install Ripple#

Requirements

WordPress 6.6 or newer, PHP 8.1 or newer, and an administrator account. The current testing site runs WordPress 7.1.3. Wider hosting, version and multisite testing is still in progress.

1. Sign in to your verified Hamelton Software account and open My licenses. An eligible license provides the plugin ZIP; you do not need to activate a domain before downloading it.
2. In WordPress, open Plugins → Add Plugin → Upload Plugin.
3. Select the Ripple ZIP, choose Install Now, then activate it.
4. Open Ripple in the administrator menu.

Preview testers receive the build separately. A license is not required to run scans in the installed preview. Commercial downloads and updates require an eligible license.

Run your first scan#

Choose Scan again in Ripple. The icon rotates while requests are processing, and the progress bar shows processed records and the percentage complete. Progress reflects completed batches rather than an estimated timer.

Keep the page open during a manual scan. A completed scan replaces the report; incomplete work does not replace the last completed report. Only one scan runs at a time on a site. After content, plugins or the theme change, run a fresh scan before relying on a preview.

For slower hosting, reduce Records per scan request in Settings. This reduces request workload without excluding content.

Read the overview#

The overview shows the last completed scan, the number of content records scanned, active plugins and records needing review. Plugin cards show affected records and link to impact reports.

Dependencies found means the report contains stored references attributed to that plugin. A zero count means no usage was found within the scan’s coverage. It does not prove that the plugin has no effect on your site.

The next-step panel directs you to unresolved references or a plugin report. Use Dependencies to search the plugin list.

Inspect one plugin#

1. Open Ripple → Dependencies or select Inspect impact on a plugin card.
2. Review the affected records, statuses, dependency identifiers and evidence sources.
3. Use the title/ID search and status, content-type and dependency filters to narrow the view.
4. Use Edit content to inspect the record in WordPress.
5. When ready, test the change on staging. Keep plugin active returns to the Plugins screen; Continue to deactivate uses the normal WordPress action.

Reports show 25 records per page. Filters change the visible rows, not the full report’s totals or export scope. Deactivation requires WordPress’s activate_plugins capability as well as administrator access.

Ripple also offers an individual preview from the Plugins screen. Bulk, network, WP-CLI and programmatic deactivation are outside this interactive flow.

Understand dependency paths#

A dependency can be direct or inherited through saved reusable content. A path explains the stored relationship, for example:

Landing page → reusable pattern → nested pattern → plugin shortcode

Ripple follows reusable pattern references and saved core/navigation references. The explanation identifies the source records and the final block or shortcode. Cyclic references terminate; they do not cause an endless scan.

Each explanation shows one valid path per plugin, rather than every possible path. Saved evidence is not proof of runtime execution. Static blocks can retain their saved markup after a plugin is removed.

Preview several plugins together#

1. Open Ripple → Combined impact.
2. Select the plugins involved in your planned change.
3. Choose Preview combined impact.
4. Review the unique affected records and the evidence for each selected plugin.
5. Export the selected-plugin report if you need to share it.

A record that depends on several selected plugins is counted once in the combined total. The report retains the separate plugin relationships. Combined impact is a planning preview; it does not deactivate plugins in bulk.

Review unresolved findings and save notes#

The Review queue lists references whose owner could not be confirmed. An unknown bracketed string is a shortcode candidate, not proof of a registered shortcode or a missing plugin.

Open the content, identify the intended owner and check whether the reference is still needed. Use an Investigating or Reviewed note to record your decision. Notes support up to 1,000 characters. Ripple retains up to 500 recent notes, with administrator and timestamp.

Changed titles, statuses, types, references, reusable-content evidence or plugin/theme fingerprints can trigger Evidence changed — review again. Notes do not hide findings or certify safe removal. Run another scan after editing content.

Compare completed scans#

Scan history compares the current report with saved completed scans. Use it to see added or removed relationships and occurrence changes. Counts describe saved evidence, not guaranteed frontend calls.

The default is five prior scans. Settings permits 0–20, subject to a 2 MB storage limit. Setting zero disables history. Reducing retention removes older snapshots. Differences can also reflect changed scan conditions; read condition warnings before interpreting a change as a content edit.

Schedule background scans#

1. Open Ripple → Settings.
2. Choose Daily or Weekly for scheduled scans and save.
3. Check Scan activity after the next due run.

Background scans run in persisted batches through WordPress cron. WordPress needs site traffic or a hosting cron runner to process due events. A low-traffic site can run later than the scheduled time. Ask your host to configure a regular WordPress cron runner if timing matters.

Off stops future recurring runs. An already running background scan may finish. The Windows runner used in our local testing lab is not part of the customer plugin.

Read scan activity and failures#

Scan activity records completed scans, skipped runs, failures and changes. It keeps up to 20 entries within 1 MB. Change summaries retain counts and up to 25 record-level relationships per category.

A failed or stalled scan preserves the last completed report. A stalled job is detected after 30 minutes when cron or an administrator next runs. Check the failure message, hosting errors and cron configuration; then run a fresh manual scan. A skipped overlapping run means another scan was already in progress.

Integration warnings describe unreadable builder data or traversal limits. They are part of the report’s context and should be reviewed alongside the findings.

Export a report#

Impact reports and unresolved queues can be exported as CSV or JSON. Exports include the full saved findings, scan timestamp, freshness and coverage, independently of the on-screen filters and pagination.

Use the printable HTML report for a readable handoff. Open your browser’s Print dialog and choose Save as PDF. Ripple does not require a separate PDF service.

JSON schema version 2 includes evidence sources, dependency paths, branding and selected-plugin fields. CSV protects spreadsheet cells from formula execution. Downloads require administrator access and an authenticated request.

Create a branded client report#

1. In Settings, enter the agency and client names, brand color, contact details and footer.
2. Select a PNG, JPEG or WebP logo from the WordPress Media Library.
3. Save your preferences.
4. Open the report and choose the printable agency export.
5. Choose whether to include review notes, then print or save as PDF.

Notes are excluded unless explicitly selected, because they may contain internal or client information. Review the export before sharing it. Branding, notes and reports remain in your WordPress database.

Scan and report settings#

Settings also contains licensing, software update checks, agency branding and the introduction controls. The refresh-replay introduction setting is temporary for development testing.

Coverage and limitations#

Included

• Public post types and saved wp_block patterns, wp_template templates, wp_template_part template parts, wp_navigation navigation and Elementor library documents.
• Published, draft, pending, private and future records. Revisions, trash and auto-drafts are excluded.
• Nested plugin blocks, shortcode candidates and references through saved patterns/navigation.
• Targeted Elementor fields and assigned classic text/block widgets, described below.

How ownership is established

Ripple uses available block-registration metadata paths and PHP callback reflection. Shared plugin directories, frontend-only registration and client-only blocks can leave ownership ambiguous. Theme and must-use code may not map to a normal plugin.

Outside current coverage

Other builders, unsupported Elementor fields and dynamic tags, unsupported or unassigned widgets, theme-file templates, template-part slug resolution, unsaved navigation, options, custom tables and general runtime integrations. Escaped shortcodes and candidates inside HTML pre/code elements are excluded.

A report describes saved references within this scope. Use a backup and staging test for consequential changes.

Elementor and widget support#

Ripple reads saved Elementor shortcode and text-editor fields in nested containers. It also attributes builder-mode documents to the installed Elementor plugin. Elementor 4.3.4 widget objects were tested locally.

Dynamic tags, other Elementor fields and arbitrary addons are outside the current integration. Unreadable data or traversal limits produce warnings. Duplicate references in normal post content and builder data are separate stored evidence locations, not guaranteed runtime invocation counts.

Assigned WordPress classic text and block widgets are inspected without rendering them. Widget records identify their assigned area. That placement does not prove they appear on a specific frontend page. Inactive widgets and other widget types are excluded.

Activate your license#

Licenses are linked to the purchasing Hamelton Software account. The activation email contains your key and product-specific instructions. Do not post your key in a support request or public screenshot.

1. Open Ripple → Settings in WordPress.
2. Enter the emailed license key.
3. Select Production for your main website.
4. Activate the license and confirm the registered domain and expiry.
5. Sign in to My licenses to view the linked domain and license status.

An account email identifies the owner; it is not an activation credential. The key and installation identity link the installed copy to the account. Activation sends the key, domain and installation ID to Hamelton Software.

Use staging and local companion sites#

Each paid production activation permits two linked staging or local companion activations.

1. Activate the production domain first.
2. Install Ripple on your staging or local site.
3. Enter the same license key in Settings.
4. Select Staging or Local, and enter the parent production domain.
5. Activate and verify the companion listing in your company account.

The parent must belong to the same license and have an active production registration. Companion update eligibility depends on that parent activation. These companions do not provide extra production seats.

Expiry, renewal and cancellation#

After annual expiry, the installed version keeps scanning and retains its reports. Updates and support require renewal. Renewal keeps the same license key.

The annual plan is intended to renew through Stripe until cancelled. Public checkout and billing setup are not open yet. Once enabled, eligible accounts can manage payment details and cancellation through the billing portal. Cancelling future billing preserves the already paid term.

A refunded or revoked license cannot receive updates. Commercial purchase and refund terms will be published before sales open; the current preview is not an offer to take payment.

Move a license to another domain#

1. Sign in to My licenses and release the old domain’s activation, or deactivate the license from the old WordPress installation.
2. Install Ripple on the new site and enter the same key.
3. If the key is already saved on the new domain, choose Activate on this domain.
4. Confirm the new registered domain in Settings and the company account.

Clear saved key removes local credentials only; it does not release the remote activation slot. Use the account release control when the previous installation is unavailable. Changing WordPress salts can make the encrypted local key unreadable; clear and re-enter it to recover.

Recheck staging/local parent links after moving a production activation.

Install updates#

Ripple integrates with WordPress’s plugin update system. In Settings, choose Check for updates to refresh the available version. Use the normal WordPress update controls to install it. WordPress’s Enable auto-updates setting controls automatic installation.

Metadata and ZIP delivery require a valid activation for this installation and domain. Ripple verifies signed release metadata and the downloaded ZIP’s size and SHA-256 checksum before installation. Credentials are sent in authorization headers, not package links. Reports are not sent.

An expired, refunded or revoked license cannot download updates. During a licensing-service outage, Ripple keeps its last activation state and installed scanning functions. Retry later; an outage does not remove your reports.

Data, permissions and uninstall#

Ripple reads content without executing shortcodes or rendering it. Saved reports contain record IDs, titles, types, statuses, dependency identifiers and evidence; full post content is not stored in the report. Review notes, report history, branding, preferences and scan state are also stored locally.

Administrators with manage_options can scan and read reports. Deactivation also requires activate_plugins. Treat exports and review notes as client data when sharing them.

License activation and update checks contact Hamelton Software with license and installation details. Report contents are not uploaded.

Deactivating Ripple preserves reports. Deleting/uninstalling it removes Ripple options and cron hooks from the current site. This preview does not support network-wide multisite cleanup; clean per-site data before removing a network installation.

Troubleshoot common problems#

The scan stops or times out

Reduce the batch size, check PHP/hosting errors and retry Scan again. The last completed report is preserved. If a background run is stalled, allow the next cron/admin check to record the failure.

A scheduled scan did not run on time

Confirm scheduling is enabled and WordPress cron is running. Low traffic and disabled WP-Cron can delay jobs. Ask your host about a server cron runner, then check Scan activity.

A plugin has no matches

Confirm the report is fresh, then review coverage. The plugin may use options, custom tables, unsupported builder data or runtime hooks rather than saved blocks/shortcodes.

A report is stale immediately

Content, plugin/theme changes and Ripple version changes can invalidate it. Finish the changes and rescan. Report freshness does not override those invalidations.

A license will not activate

Check the key, domain, license validity and available production seats. For companions, check the production parent. Release a previous domain from the company account if needed.

An update fails integrity checks

Do not install an unverified package. Retry the update and contact support with the error text and versions if it persists.

Get help and report an issue#

Email help@hameltonsoftware.com for product help or bugs@hameltonsoftware.com for bugs. You can also use the contact form.

Include Ripple, WordPress and PHP versions; the affected plugin/builder version; the screen and steps involved; expected and actual results; and relevant error text. Remove passwords, license keys and client-sensitive information. If you attach a report, inspect it first.

For version changes, read the development changelog. Return to the Ripple product page for screenshots, features and availability.