Documentation — PCOWidget

Product Overview

PCOWidget is a self-contained, embeddable calendar that pulls live event data from your Planning Center Online calendar and renders it as an interactive, styled component on any web page — with a single <script> tag.

📅

Five Layout Views

Month grid, week strip, list rows, card grid, and simple service tiles.

🔍

Event Popovers

Click any event for a full-viewport detail card with image, description, and action links.

🏷️

Tag Filtering

Filter by Planning Center tag — show only Youth, Worship, Outreach events on any page.

📖

Sermon Title Extraction

Write sermon: Your Title in PCO event notes — it surfaces automatically on service tiles.

🎨

Auto Tag Colors

Events auto-color by ministry category — Worship, Youth, Children, Outreach, and more.

📆

iCal Downloads

"Add to Calendar" links let visitors save events to Google Calendar, Outlook, or Apple Calendar.

📱

Mobile-First Responsive

Adapts from phone to desktop. Works in Squarespace, WordPress, Wix, and custom HTML sites.

⚡

No Backend Required

PCOWidget's servers handle PCO authentication. Your site only needs a script tag.

How It Works

PCOWidget sits between your church website and Planning Center. Your site never touches PCO credentials — they live encrypted on PCOWidget's servers.

Your Church Website (Squarespace, WordPress, Wix, HTML)
    <script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY">
                              ↓
                    api.pcowidget.com
                              ↓
    Your API key → your PCO credentials (encrypted, server-side)
                              ↓
           api.planningcenteronline.com/calendar/v2
                              ↓
    Events rendered as HTML → injected into your page

Your <script> tag loads the widget JavaScript from PCOWidget's API servers
The widget auto-detects its endpoint from its own src URL
PCOWidget's PHP middleware authenticates with Planning Center using your encrypted credentials (never exposed to visitors)
Events are fetched, formatted, and returned as styled HTML
Month navigation and view switching fetch lightweight HTML fragments — no full page reload

Embedding the Widget

Basic Embed

One line. That's it. Paste into any HTML page, Squarespace Code Block, or WordPress Custom HTML block:

HTML

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"></script>

ℹ️

Replace YOUR_KEY with the API key from your PCOWidget account dashboard. Your key is provisioned when you sign up.

Squarespace

Add a Code Block (not a Markdown block) and paste your script tag. No <html>, <head>, or <body> tags needed — the widget handles everything.

💡

Cards layout width on Squarespace: Squarespace wraps code blocks in a .sqs-code-container element that can render as inline-block, preventing the card grid from filling the full column width. If your cards appear narrower than expected, add this to Design → Custom CSS:

.sqs-code-container {
  display: block;
  width: 100%;
}

WordPress

Add a Custom HTML block in the Gutenberg editor and paste the script tag.

Mounting Into an Existing Element

If you already have a container div where you want the widget, use data-target:

HTML

<div id="my-calendar"></div>
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-target="my-calendar"></script>

Multiple Instances on One Page

Each <script> tag creates an independent widget instance. Configure each with different data-* attributes:

HTML

<!-- Full church calendar -->
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="table"></script>

<!-- Youth events sidebar -->
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-tag="Youth"
        data-layout="list"></script>

<!-- This week's services (homepage) -->
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="simple"
        data-this-week="1"
        data-title="This Week's Services"></script>

Data Attributes

Control each widget instance using data-* attributes on the <script> tag:

ⓘ

Boolean attributes accept multiple formats. Any of "1", "true", "True", or "TRUE" are treated as on. Any of "0", "false", "False", or "FALSE" are treated as off. This applies to data-featured, data-this-week, data-allow-week-nav, data-include-past, data-hide-end-time, and data-hide-if-empty.

📄

Want to see every option in action? The live examples page shows all layouts, filters, and combinations running against real ELC data.

data-layout Default: table

Values: table · list · cards · week · simple

Initial view layout. table = month grid, simple = service tiles, others as named. See Layouts for details.

data-tag Default: (none — all events)

Values: any PCO tag name, or comma-separated list for OR filtering

Filter to events with a specific Planning Center tag. Case-insensitive. Use a comma-separated list for OR logic — data-tag="Youth,Women's Ministry" shows events tagged either Youth or Women's Ministry.

data-this-week Default: (none)

Values: true · 1

Show only events in a rolling 7-day window starting from today. Designed for "This Week's Services" sections using the simple layout.

data-allow-week-nav Default: (none)

Values: true · 1

Adds a prev/next week toolbar to the simple layout so visitors can browse upcoming weeks. The prev button is disabled on the current week. The center label shows "This Week" / "Next Week" / "+N Weeks" and clicking it returns to the current week.

data-nav-align Default: center

Values: left · center · right

Alignment of the week navigation toolbar (simple layout only).

data-title Default: (none)

Values: any string

Override the section heading shown above the widget. E.g. data-title="This Week's Services" or data-title="Youth Events".

data-columns Default: 2

Values: 1 – 8

Maximum tiles per row on the simple layout. Automatically collapses to 1 column on screens ≤480px regardless of this value.

data-featured Default: (none — all events)

Values: true · 1 · false · 0

Three-state filter: absent = all events (default); true/1 = featured events only; false/0 = non-featured events only. Featured events get star indicators and accent borders on card layouts.

data-limit Default: 50

Values: 1 – 50

Maximum number of events to fetch per request. Lower values improve load time for simple layouts.

data-shadow Default: blue

Values: blue · burgundy · standard

Container shadow color theme. See Shadow & Theming for visual examples.

data-include-past Default: false

Values: true · false · 1 · 0

By default, events that have already ended are hidden. Set to true for archive or recap pages where past events should remain visible.

data-hide-end-time Default: (show end time)

Values: true · 1

Hide the end time from time displays, showing only the start time. Applies to simple, cards, and list layouts. Useful for service tiles where end times add visual clutter.

data-hide-if-empty Default: (show empty state)

Values: true · 1

When set, the entire widget container is hidden — no box, no border, no empty message, no space — if zero events match the current parameters. Without this flag the widget renders a "No upcoming events found" box. Useful for tag-filtered widgets on pages where that ministry may have no upcoming events.

data-target Default: (auto-creates container)

Values: a DOM element ID

Mount the widget inside an existing <div> element by ID. If omitted, the widget creates and inserts its own container after the script tag.

Quick Reference Table

Attribute	Values	Default
`data-layout`	`table` · `list` · `cards` · `week` · `simple`	`table`
`data-tag`	tag name, or `tag1,tag2` (OR)	—
`data-this-week`	`true` · `1`	—
`data-allow-week-nav`	`true` · `1`	—
`data-nav-align`	`left` · `center` · `right`	`center`
`data-title`	string	—
`data-columns`	1–8	`2`
`data-featured`	`true` · `1` · `false` · `0`	—
`data-limit`	1–50	`50`
`data-shadow`	`blue` · `burgundy` · `standard`	`blue`
`data-include-past`	`true` · `false` · `1` · `0`	`false`
`data-hide-end-time`	`true` · `1`	—
`data-hide-if-empty`	`true` · `1`	—
`data-target`	element ID	—

Boolean Values — Accepted Formats

The five boolean attributes (data-featured, data-this-week, data-allow-week-nav, data-include-past, and data-hide-end-time) are flexible about how you write true or false. All of the following are valid:

Meaning	Accepted values
On / true	`"1"` `"true"` `"True"` `"TRUE"`
Off / false	`"0"` `"false"` `"False"` `"FALSE"` (or omit the attribute entirely)

Examples — these are all equivalent:

HTML

<!-- All three turn on data-this-week -->
<script src="..." data-this-week="1"></script>
<script src="..." data-this-week="true"></script>
<script src="..." data-this-week="TRUE"></script>

<!-- All three turn on data-include-past -->
<script src="..." data-include-past="true"></script>
<script src="..." data-include-past="True"></script>
<script src="..." data-include-past="1"></script>

Layouts

Choose from five layouts, each designed for a different use case:

Month GridFull month calendar with week rows. Best for event pages.

Week StripCompact 7-day view. Best for sidebars and homepage sections.

List RowsRow-based list with thumbnails. Best for ministry landing pages.

Card GridRich image cards with descriptions. Best for featured events.

Service TilesMinimal clickable tiles. Best for "This Week's Services" sections.

Month Grid — `data-layout="table"`

Full monthly calendar grid (Sunday–Saturday). Shows day numbers with event indicators.

Desktop: Event name and time visible inside grid cells
Mobile (<768px): Colored dot indicators instead of event text
Includes month/year header with prev/next month arrows and a view-switching toolbar
Click any event to open the full-detail popover

HTML

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="table"></script>

Week Strip — `data-layout="week"`

Compact 7-day view extracted from the month grid. Shows only the row containing today (or the first row with events for non-current months). Ideal for sidebars or "this week" widgets.

HTML

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="week"></script>

List — `data-layout="list"`

Compact row-based layout with thumbnail images (or date badges when no image). Shows event name, date, time, and location. Stacks on mobile. Good for ministry landing pages with moderate detail.

HTML

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="list"
        data-tag="Women's Ministry"></script>

Cards — `data-layout="cards"`

Rich card grid — auto-fit responsive layout. Each card is at least 260px wide; columns fill all available space naturally (typically 2 on tablet, 3+ on wide desktop, 1 on mobile). Each card shows:

16:9 image (or date badge placeholder)
Date badge, title, time, description (3-line clamp), location
Tag color badges
"View Details" link
Featured events get accent borders and star indicators

HTML

<!-- Featured events showcase -->
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="cards"
        data-featured="1"
        data-shadow="burgundy"></script>

Simple Tiles — `data-layout="simple"`

Minimal clickable service-time tiles. Each tile shows a clock icon, event name, sermon title (if set), date, and time range. Clicking a tile opens the full event popover. No toolbar — clean and focused.

Designed for use with data-this-week="1" to show the current week's events on your homepage or church info page.

Sermon Title Display

Your recurring "Traditional Worship" event stays the same in PCO, but the sermon title changes each week. To surface a sermon title on a simple tile, add a line to the PCO event's Details field:

PCO Event Details field

sermon: Giving Expectantly

The prefix (sermon:) is stripped — only the title text is shown
The match is case-insensitive (Sermon:, SERMON:, etc. all work)
The line can appear anywhere in the Details field
If no sermon: line is present, the subtitle is omitted — no blank space

💡

Pro tip: The sermon title line can appear anywhere in the event Details field — beginning, end, or mixed with other content. Just make sure it's on its own line.

Week Navigation

Add data-allow-week-nav="1" to let visitors browse upcoming weeks. The prev button is disabled on the current week. The center label shows "This Week" / "Next Week" / "+N Weeks" and clicking it returns to today.

Column Count

Use data-columns to control tiles per row. If you have 4 services on Holy Week, set data-columns="4". Always collapses to 1 column on mobile.

HTML — Full simple layout example

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="simple"
        data-this-week="1"
        data-title="This Week's Services"
        data-tag="Worship Services"
        data-allow-week-nav="1"
        data-nav-align="center"
        data-columns="2"></script>

Feature Flags

Feature flags are server-side controls managed by PCOWidget for your account. They determine which interactive features are enabled in your widget. All are enabled by default on Pro plans.

Flag	Feature	Effect
`WIDGET_POPOVER`	Event popover	Click events to open a full-detail card (image, description, links, iCal)
`WIDGET_TRANSITIONS`	Slide transitions	Smooth left/right animation when navigating months
`WIDGET_ICAL`	iCal downloads	"Add to Calendar" links generate `.ics` files for Outlook, Google, Apple Calendar
`WIDGET_TAG_COLORS`	Tag color coding	Events colored by ministry category (see Tag Colors)
`WIDGET_THIS_WEEK`	Week view option	Enables the "Week" button in the toolbar; 7-day strip view

ℹ️

To request a feature flag change for your account, contact support@pcowidget.com.

Shadow & Theming

Shadow Presets

Set the container shadow tone with data-shadow:

Value	Visual	Best For
`blue`	Blue-tinted drop shadow	Default — works with most church sites
`burgundy`	Warm red/maroon tinted shadow	Traditional church aesthetics, warm palettes
`standard`	Neutral gray shadow	Minimal sites, any color scheme

CSS Isolation

All widget CSS classes are prefixed with pcow-. Widget styles will not conflict with your site's existing CSS, even on Squarespace, WordPress, or Wix where host-site styles are aggressive.

💡

Note: The widget deliberately avoids h1–h6 elements to prevent host-site heading styles from overriding widget typography.

Tag Colors

When tag color coding is enabled, events are automatically colored by their Planning Center tag. No configuration needed — the widget reads the tag name and applies the matching style.

Worship Services Blue — for weekend services and worship events

Adult Discipleship Green — for Bible studies, small groups, growth events

Youth Purple — for student ministry, youth group events

Children Amber — for children's church, family events

Outreach Pink/rose — for community, mission, outreach events

Tags not in the default map receive the standard blue styling. Additional tag color mappings can be configured on your account — contact support to request custom tag colors.

💡

Multiple tags: Events can have multiple PCO tags and all will be shown as color badges on card and list layouts. The data-tag attribute scopes which events are shown, not which tags are displayed. An event tagged "Youth" and "Outreach" shows both badges when you filter by data-tag="Youth".

Responsive Breakpoints

The widget is mobile-first and adapts at these breakpoints:

< 480px

Compact grid cells, minimal spacing. Simple layout always 1 column.

< 640px

List: stacked layout (image above text).

< 768px

Month grid: colored dot indicators instead of event text in cells.

640px+

List: side-by-side (image left, text right).

Any width

Cards: auto-fit — fills available space with columns at least 260px wide. Typically 1 column on mobile, 2 on tablet, 3+ on wide desktop.

REST API Reference

The widget fetches data from PCOWidget's REST endpoint. You can call this directly for custom integrations or debugging.

Endpoint

GET https://api.pcowidget.com/v1/calendar-endpoint.php

Query Parameters

Param	Values	Default	Description
`key`	string	(required)	Your API key
`format`	`html` · `fragment` · `json`	`html`	Response format
`layout`	`cards` · `list` · `table` · `simple`	`cards`	Template layout (html/fragment only)
`month`	`YYYY-MM`	(none)	Explicit month — auto-sets date range
`tag`	PCO tag name	(none)	Filter by tag (case-insensitive)
`featured`	`1`	(none)	Show only featured events
`limit`	1–50	`10`	Maximum events returned
`after`	`YYYY-MM-DD`	(none)	Date range start
`before`	`YYYY-MM-DD`	(none)	Date range end
`filter`	`future` · `past`	`future`	Time filter (suppressed when month is set)
`columns`	1–8	`2`	Cards per row (simple layout only)

Response Formats

format=html — Full HTML with wrapper div, scoped CSS, and feature flags JSON. Used for initial widget load.
format=fragment — Layout HTML only (no wrapper, no CSS). Used by the widget for AJAX navigation.
format=json — Raw JSON event data. Use for custom integrations or debugging.

Example Requests

# Test your key — returns JSON event data
https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=json&limit=5

# March 2026 month grid as HTML
https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=html&layout=table&month=2026-03

# Youth events as cards
https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=html&layout=cards&tag=Youth

# Date range query
https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=json&after=2026-03-01&before=2026-06-30&limit=50

JSON Schema

When using format=json, the response follows this structure:

JSON Response

{
  "status": "ok",
  "count": 12,
  "events": [
    {
      "id": "123456",               // EventInstance ID
      "event_id": "789",          // Parent Event ID
      "name": "Sunday Worship",     // EventInstance name (falls back to Event name)
      "sermon_title": "Giving Expectantly", // Extracted from sermon: convention
      "description": "Join us for worship...",
      "starts_at": "2026-03-08T15:30:00Z",  // UTC
      "ends_at": "2026-03-08T16:30:00Z",
      "all_day": false,
      "location": "Sanctuary",
      "image_url": "https://...",
      "event_url": "https://...",        // Church Center URL
      "registration_url": "",
      "featured": true,
      "tags": ["Worship Services"],   // Array of tag names
      "recurrence": "weekly"
    }
  ],
  "meta": {
    "filter": "",
    "tag": null,
    "layout": "cards",
    "limit": 10,
    "month": "2026-03",
    "features": {
      "popover": true,
      "transitions": true,
      "ical": true,
      "tagColors": true,
      "thisWeek": true
    }
  }
}

Troubleshooting

Widget shows nothing

Open your browser's Developer Tools → Console tab and look for JavaScript errors or failed network requests
Verify the script src URL loads directly in a browser tab — it should return JavaScript, not an error page
Test the endpoint directly: https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=json&limit=1
Confirm your API key is correct and your account is active

⚠️

Squarespace: Make sure you're using a Code Block, not a Markdown block. Squarespace strips <script> tags from Markdown blocks.

CORS errors in browser console

If you see "Cross-Origin Request Blocked" or CORS errors:

Your site's domain may not be on the allowed domains list for your account
Contact support@pcowidget.com with your domain and API key to add it
Both https://example.com and https://www.example.com need to be listed separately
Clear your browser cache after the domain is added

Events not showing / empty calendar

Test the JSON endpoint directly to verify your PCO credentials are working
Confirm events exist and are published in Planning Center Calendar (not draft or hidden)
If using data-tag, verify the tag name matches exactly how it's spelled in Planning Center (matching is case-insensitive, but spelling must be exact)
Check that events are in the date range — by default the widget shows future events only

Past events still visible

Make sure data-include-past is not set to "true"
Hard refresh the page (Ctrl+Shift+R / Cmd+Shift+R) — the widget JavaScript may be cached
If the issue persists, add a cache-busting query string to the script src: calendar-widget.js?key=YOUR_KEY&v=2

Stale events after updating Planning Center

The widget caches fetched data in memory for the current browser session — a page refresh clears it
PCO API data can take a few minutes to propagate after saving changes in Planning Center

Sermon title not showing on simple tiles

Confirm the line is in the Details field of the event in Planning Center Calendar (not the title or notes on a separate app)
The line must begin with sermon: (with a colon) — no space before the colon
The line can appear anywhere in the Details field, but must be on its own line
Sermon titles only display on the simple layout

💬

Need help? Email support@pcowidget.com with your API key and a description of the issue. Pro plan users receive priority response.

Widget Reference Guide

Product Overview

How It Works

Embedding the Widget

Basic Embed

Squarespace

WordPress

Mounting Into an Existing Element

Multiple Instances on One Page

Data Attributes

Quick Reference Table

Boolean Values — Accepted Formats

Layouts

Month Grid — data-layout="table"

Week Strip — data-layout="week"

List — data-layout="list"

Cards — data-layout="cards"

Simple Tiles — data-layout="simple"

Sermon Title Display

Week Navigation

Column Count

Feature Flags

Shadow & Theming

Shadow Presets

CSS Isolation

Tag Colors

Responsive Breakpoints

REST API Reference

Endpoint

Query Parameters

Response Formats

Example Requests

JSON Schema

Troubleshooting

Widget shows nothing

CORS errors in browser console

Events not showing / empty calendar

Past events still visible

Stale events after updating Planning Center

Sermon title not showing on simple tiles

Month Grid — `data-layout="table"`

Week Strip — `data-layout="week"`

List — `data-layout="list"`

Cards — `data-layout="cards"`

Simple Tiles — `data-layout="simple"`