Santa Cruz Local Election Results: New Election Preparation Process

Purpose

Santa Cruz Local displays election results on election night and for the following months. Results are scraped from the Santa Cruz County Elections site and displayed through WordPress snippets/shortcodes.

This document explains how to prepare the results page for a new election, preserve the prior election as a static archive, test the scraper, and monitor the page on election night.

Core process

1. Freeze and archive the prior election page

Critical: do this before the County updates its live results page for the next election. The County may update the page one to two days before election day, with no reliable warning. Once that happens, the prior election’s shortcode output may no longer be recoverable from the County source.

  • Copy the previous election results page and preserve it as a static/archive page.
  • Replace election-results shortcodes with the actual rendered HTML/results output.
  • Confirm the archived page no longer depends on live County data.
  • Update the archive page title, URL, intro text, and internal links.
  • Confirm the archived page still looks clean and understandable.

Practical methods:

  • Preferred: view the rendered public page source, copy the enclosing <div> for the election results, and paste that static HTML into the archive page in place of the shortcode.
  • Alternative: copy/paste the visible rendered results from the browser into an Avada/WordPress text block, then verify formatting.

Also update the Avada library element that lists archived election pages:

https://santacruzlocal.org/wp-admin/post.php?post=18113&action=edit

Add the newly archived election page and confirm the public archive link works.

2. Identify the new election configuration

Record the information needed to configure the site:

  • Election name.
  • Election date.
  • Polls-close date and time.
  • County results source URL.
  • Expected local races, measures, city races, supervisor races, and countywide races.
  • Races Santa Cruz Local wants to feature.
  • Races that should be hidden from the full-results display.
  • Any known or suspected County formatting changes.

Santa Cruz Local generally shows selected local races, not every County race.

3. Create a working copy of the live elections page

The public election results page uses a reused/permanent URL. Prepare the next election on a working copy before changing the live page.

  • Copy the current live election results page or create a draft/mockup.
  • Keep the working page out of public navigation.
  • Confirm it uses the current shortcode system.
  • Confirm it can be edited safely without affecting the live public page.

The likely go-live method is copying the working page content into the permanent live page, but this should be confirmed during the next setup.

4. Configure races and hidden races

  • Add shortcodes for featured races.
  • Add measure, city, or supervisor shortcodes as needed.
  • Update remove-races.txt for races that should not appear in the full-results display.
  • Confirm regex-based race matching works against actual County race names.
  • Update explanatory text, headings, labels, and source links.

remove-races.txt path:

/var/www/vhosts/santacruzlocal.org/httpdocs/scrape/remove-races.txt

5. Configure date/time show-hide behavior

Use [Election​LiveResults] and Avada rendering logic to control what appears before and after results are live.

  • Add or update [Election​LiveResults] with the correct polls-close date/time.
  • Confirm the shortcode appears before any Avada rendering logic that depends on it.
  • Configure the pre-results section to show before results are live.
  • Configure the live-results section to show once results are live.
  • Test both states deliberately.

Example polls-close format:

[Election​LiveResults pollsClose="6/2/2026 8:00:00PM"]

6. Test against the County site

About two weeks before election day, begin testing against the County results page.

  • Confirm the County source page is available.
  • Confirm the scraper can read the current County data format.
  • Test the full-results shortcode.
  • Test each race, city, supervisor, and measure shortcode used on the page.
  • Use cache="no" when direct scraping is needed for testing.
  • Compare output manually against the County page.

The County results page usually exists continuously. One to two days before election day, the County typically updates it to show the new races with zero votes. That update is effectively live source data and should trigger final testing.

Check:

  • Source URL has not changed.
  • Race names match shortcode patterns.
  • County timestamp parses correctly.
  • Race order, names, totals, percentages, and timestamps display correctly.
  • Desktop and mobile display are acceptable.
  • The page works after caches are cleared and with normal caching enabled.

7. Make the working page live

  • Move the prepared content into the reused/permanent live election results page.
  • Confirm public navigation points to the correct page.
  • Confirm old election pages work as static archives.
  • Clear relevant caches.
  • Test the public page as an anonymous visitor in a private/incognito browser.

8. Monitor election night

Before polls close:

  • Confirm the page loads publicly.
  • Confirm the pre-results message is visible.
  • Confirm the live-results section is hidden.
  • Confirm Cloudflare is not serving an old page.
  • Avoid risky edits near 8:00 PM unless the page is broken.

At or shortly after polls close:

  • Watch both the County results site and the Santa Cruz Local page.
  • Confirm Avada show-hide logic behaves correctly.
  • Confirm the live-results section appears when appropriate.
  • Confirm the County update timestamp appears correctly.
  • Compare at least one major race manually against the County site.
  • Watch for stale caches, broken race matches, missing races, or layout problems.

If the page appears stale, clear caches in this order:

  1. Shortcode/scraper cache.
  2. WordPress/plugin cache.
  3. Avada cache.
  4. Cloudflare cache.
  5. Browser cache.

These instructions should be usable by someone other than Will. Kara is the likely backup person if Will is unavailable.

9. Maintain the page after election night

  • Leave the live results page active while results continue to update.
  • Results may take weeks to become final.
  • Add certified/final-results language when appropriate.
  • Keep monitoring until the County stops updating.
  • Record any scraper, shortcode, cache, or County-source issues.
  • Before the next election cycle, freeze/archive the page before the County source changes again.

Shortcode reference

The election results system is implemented with PHP snippets exposed as WordPress shortcodes. The site runs in WordPress using the Avada theme.

Primary shortcodes:

  • [Election​Results] — displays County election results.
  • [Election​Race] — displays one or more races using a regex match.
  • [Election​Supervisor] — displays a supervisorial district race.
  • [Election​City] — displays city council races.
  • [Election​Measure] — displays a measure.
  • [Election​CurrentTime] — displays the current time, not the County results update time.
  • [Election​LiveResults] — sets $_GET['SCL_Election_Live_Results'] to control Avada show-hide logic.

Important notes:

  • Shortcode parameters are case insensitive, except for [yes,no] values.
  • WordPress normalizes shortcode attribute names to lowercase before they reach PHP.
  • Examples are live and depend on current County data.
  • Documentation pages containing $_GET may trigger Jetpack Firewall Automatic Rules. Temporarily disable Jetpack → Firewall → Automatic Rules only if needed, then re-enable it after saving.

Scraper reference

The scraper is pragmatic but brittle. It depends on the County keeping the same URL, HTML structure, CSS class names, and text patterns. There is no County API, formal schema, or documented results feed.

Before every election, verify the scraper against the actual County page. Do not assume it still works because it worked in a prior election.

Scrape directory:

/var/www/vhosts/santacruzlocal.org/httpdocs/scrape/

County results URL, hard-coded in the snippet:

https://sccounty01.co.santa-cruz.ca.us/ElectionSites/ElectionResults/Results

Files used by the full-results shortcode:

  • strInArray.php
  • simple_html_dom.php
  • remove-races.txt
  • replacements_universal2.php
  • cache-county.txt

Cache behavior:

  • Rendered full-results output is cached in cache-county.txt.
  • If the cache file is less than two minutes old, the shortcode returns cached HTML instead of scraping the County site again.
  • Use cache="no" when testing the current County source directly.

County page dependencies:

  • div.electionTimeStamp — County update time.
  • div.mb-4 — race blocks.
  • div.card-header — race title and reporting text.
  • .prec-num — reporting/precinct text.
  • div.header-row div.col-head — table headers.
  • div.content-row div.elec-col — candidate/choice rows.

If any of these change, the snippet may need code changes before election night.

Troubleshooting

Results are not showing

Check:

  • County source page changed.
  • County results are not live yet.
  • Polls-close value is wrong.
  • Scraper cache is stale.
  • Cloudflare, WordPress, Avada, or browser cache is stale.
  • Race is being removed by remove-races.txt.
  • Regex pattern does not match the current race title.

A specific race is missing

Check:

  • The County page contains the race.
  • The race name matches the shortcode regex.
  • Snippet title normalization did not change the match string.
  • remove-races.txt is not excluding the race.
  • Caches have been cleared.

Live/not-live containers are wrong

Check:

  • [Election​LiveResults] appears before Avada rendering logic that depends on it.
  • pollsClose is correct.
  • Date/time format is valid.
  • GET variable name is correct.
  • Avada is testing the expected YES or NO value.
  • Page cache is not preserving the wrong state.

Documentation page cannot be saved

Likely cause: Jetpack Firewall Automatic Rules are treating $_GET as a PHP injection attempt.

Fix:

  1. Temporarily disable Jetpack Firewall Automatic Rules.
  2. Save the page.
  3. Re-enable Jetpack Firewall Automatic Rules.

Private/incognito mode behaves differently

Likely cause: browser cache or cached redirects/pages in the normal browser.

Fix:

  • Clear browser cache.
  • Test in private/incognito.
  • Clear Cloudflare and WordPress caches.
  • Use hard reload where appropriate.

Open items to fill in

  • Snippet names in WordPress.
  • Whether Cloudflare page rules/cache rules apply to election results pages.
  • Whether Avada or another plugin caches dynamic shortcode output.
  • Exact reused Santa Cruz Local live election results page URL.
  • Exact working/draft page URL.
  • Exact go-live method: copy working-page content into permanent page, publish draft, redirect, or another method.
  • Exact wording for unofficial/certified result status.
  • Election-night monitoring and cache-clearing backup procedure for Kara.
  • Whether Kara has the necessary WordPress, Avada, Cloudflare, and server/cache access to execute the process if Will is unavailable.