MINISTRYPLATFORM CUSTOM WIDGET

Event Calendar — Installation Guide

A full parish calendar on your own website, in month, week, day or list view, built from the events you already approve for the web. Clicking an event opens its times, description and a link to the event page. No login required, and — unusually for a custom widget — no database work at all.

This guide assumes you have read Getting Started. It covers only where the Event Calendar differs from the standard path.

The Event Calendar in month view, showing a parish's Masses and events for July.

What the page does

The widget reads your events straight from the MinistryPlatform events feed and hands them to FullCalendar, a mature open-source calendar library.

  • Four views. Month, week, day and list, switched from buttons in the calendar's own toolbar. Visitors can page backwards and forwards, and a today button returns them.
  • Event detail. Selecting an event opens a modal with its start, end and description, plus an Event Details button linking to the event's own page for registration.
  • Recurring events behave. A daily 7am Mass appears once on each day it occurs, from the series MinistryPlatform already generates. Nothing needs flattening first.
  • Times are handled properly. The feed is requested in UTC and converted in the browser, so an event reads correctly for a visitor in another time zone.
Selecting an event opens its start and end times, description and a link through to the event page.

The page is entirely public. Nothing here requires a login, and no personal data is read or written.

The one thing that makes this widget different

There is no stored procedure. Skip Step 3 of Getting Started entirely.

The Event Calendar uses the toolkit's built-in events feed rather than custom SQL, which is why it is the fastest widget in the library to stand up and the right one to install first. You still need the platform-side setup from Step 1 and your domain prefix from Step 2, but nothing goes near SSMS.

The corollary is that what appears is governed entirely by how your events are configured in MinistryPlatform, not by a query you can edit. If an event is missing, the fix is on the Event record.

Step 1 Add the page and paste the widget

Create a page and add a single HTML block containing the following. Replace yourprefix with your domain prefix.

 <div id="FullCalendar"
     data-component="CustomWidget"
     data-template="https://cdn.jsdelivr.net/gh/MinistryPlatform-Community/MPCustomWidgets@main/Widgets/FullCalendar/Template/FullCalendar.html"
     data-requireUser="false"
     data-cache="false"
     data-debug="false"
     data-useCalendar="true"
     data-params="?GetFeaturedEventsOnly=false&GetRegistrationEventsOnly=false&OnlyApprovedEvents=true&ShowExtendedData=true&DataFormat=json&convertToUTC=true&cacheData=true"
     data-host="yourprefix"></div>
<script src="https://cdn.jsdelivr.net/npm/fullcalendar@6.1.15/index.global.min.js"></script>
<script type="text/javascript"
        src="https://cdn.jsdelivr.net/gh/MinistryPlatform-Community/MPCustomWidgets@main/dist/js/customWidgetV1.js"></script>

Two attributes are specific to this widget:

Attribute What it does
data-useCalendar Must be true . Tells the toolkit to hand the results to FullCalendar rather than rendering rows.
data-params The events feed query string. Each setting is described below.

Note that there is no data-sp — that is correct, and its absence is what selects the events feed.

There are two cache switches, and they are not the same one. data-cache is the toolkit's own response cache; cacheData inside data-params is the events feed's. The working deployment on this site uses data-cache="false" with cacheData=true , which lets the feed do the caching and keeps the toolkit out of it. That combination is the one to copy.

Load FullCalendar before the toolkit script. The toolkit expects the library to already be on the page. If the calendar area stays empty and the console reports that FullCalendar is not defined, the two script tags are the wrong way round.

The library version is pinned to 6.1.15 deliberately. FullCalendar has made breaking changes across major versions; do not swap it for @latest .

Step 2 Set the feed parameters

Everything an administrator normally changes is in data-params .

Setting What it does
GetFeaturedEventsOnly true restricts the calendar to events flagged as featured. Useful for a homepage strip; leave false for a full parish calendar.
GetRegistrationEventsOnly true shows only events open for online registration. false shows everything published.
OnlyApprovedEvents Leave true . Setting it false publishes events that have not been approved, which is rarely what anyone wants on a public site.
ShowExtendedData true returns the description and event page URL, which the detail modal needs. Setting it false leaves the modal nearly empty.
DataFormat json . Do not change.
convertToUTC true . Times are requested in UTC and rendered in the visitor's local zone.
cacheData true for a public calendar — every visitor sees the same events, so there is nothing to be gained by fetching them afresh each time. Set it false while you are testing so you are not reading a five-minute-old copy of your changes.

Adding a congregation filter

A multi-site parish or a diocese can run one page per campus from the same embed by adding a congregation to the parameters. Because each page carries its own data-params , a single deployment serves a combined calendar and a page per site without any further configuration.

Check the parameter name your instance's feed expects before relying on this — confirm it against the response in the browser console with data-debug="true" .

Step 3 Style it

The calendar arrives with FullCalendar's default styling, which is clean but generic. The repository's Widgets/FullCalendar/Assets/calendar.css is a small stylesheet that adapts it; copy its contents into your site's CSS, or into a <style> block in the same HTML embed.

FullCalendar exposes its colours as CSS custom properties, so brand colours are a short override rather than a rewrite. The event chips, the today highlight and the toolbar buttons are the three worth setting.

Scope your overrides. Put every rule behind #FullCalendar so the calendar's styling cannot leak into the rest of the site, and so your theme is less likely to leak into the calendar. If your theme is centring text or resetting button padding inside the calendar, this is the fix.

The event detail modal

The template includes a modal for event details. It uses the repository's own lightweight modal helper ( mp-modal.js and the mp- classes in mp-custom.css ), not Bootstrap — so it will not collide with whatever your site theme already loads.

If clicking an event does nothing, the modal helper has not loaded. Copy src/js/mp-modal.js and the modal rules from src/css/mp-custom.css from the repository onto your site, or serve them from jsDelivr the same way as the toolkit.

Step 4 Test

  1. Open the page. The calendar should render on the current month with your events in place.
  2. Switch to Week, Day and List. Each should hold the same events.
  3. Page forward two or three months. Recurring events should continue; a gap usually means the series has not been generated that far ahead in MinistryPlatform.
  4. Click an event. The modal should show start, end, description and a working Event Details link.
  5. Compare a handful of events against the Events page in the Platform. Anything missing is a data problem — see the next section.
  6. Narrow the browser to phone width. FullCalendar switches to a denser layout; confirm the toolbar is still usable.
  7. Set data-debug="false" and publish.

MinistryPlatform configuration

The calendar is only as good as the Event records behind it. For each event that should appear:

Field Requirement
Events → Visibility Level Must be 4 - Public. Private, Staff Only, Staff & Church and Hidden: URL Required are all invisible to an anonymous visitor. This is the switch that catches people out most often.
Events → Web Approved Must be Yes. This is the flag OnlyApprovedEvents=true acts on, and it is separate from the general Approved flag — an event can be approved internally and still not published to the web.
Events → Approved The internal approval. Set it too; an event that is web-approved but not approved is a contradiction waiting to be noticed.
Events → Cancelled Cancelled events are excluded. Cancel rather than delete, so the history survives and registrants stay attached.
Events → Featured On Calendar Only relevant if you set GetFeaturedEventsOnly=true . Ignored otherwise.
Events → Event Title What visitors read on the chip. Long titles truncate in month view — the full title shows in the modal and in list view. Keep the useful words first.
Events → Event Start Date / Event End Date Both are required by MinistryPlatform. An event whose end equals its start renders as a point rather than a block.
Events → Description Shown in the detail modal, and only when ShowExtendedData=true . Worth filling in; an empty modal looks broken rather than sparse.
Events → Congregation Required on the record. Set it consistently even if you run one combined calendar today — per-site pages are the most common second request.

The quickest audit is to open the page alongside the Events page in the Platform for the same month. Any event in one and not the other differs on Visibility Level or Web Approved nine times out of ten.

Troubleshooting

The calendar area is completely empty and the console says FullCalendar is not defined.

The FullCalendar library did not load, or loaded after the toolkit. Confirm both script tags are present and in the order given in Step 1, and that your site's content security policy allows scripts from cdn.jsdelivr.net .

The calendar frame renders but contains no events.

The frame is FullCalendar; the events are the feed. So the library is fine and the request is not. Set data-debug="true" and open the console: you will see the request URL and what came back. An empty array means MinistryPlatform returned nothing, which points at Visibility Level or Approved on the events themselves. An error means data-host is wrong.

Some events appear and others don't.

Not a widget problem. Compare a missing event against one that shows: the difference is nearly always Visibility Level below 4 - Public , Web Approved not set, or a start date outside the range being requested. Web Approved is the one people miss, because the event looks perfectly approved on the record.

Events are an hour out, or on the wrong day.

convertToUTC has been set to false , or an event has been entered with the wrong time zone. Check one known event against the Platform before assuming the widget is at fault — this is more often a data entry issue than a conversion issue.

Clicking an event does nothing.

The modal helper has not loaded. See Step 3.

The modal opens but is empty.

ShowExtendedData is false , so the description and URL never arrived. Set it true .

Blocks of documentation text appear on the page.

Your website builder stripped the HTML comment markers and rendered what was inside them. Remove the comments, or move your notes into a <script> or <style> comment. This affects Duda and several other builders.

The calendar looks squashed inside a narrow column.

FullCalendar sizes itself to its container. Put it in a full-width section rather than a sidebar column; month view needs roughly 700px to be readable.

Attribution

Calendar rendering uses FullCalendar under its MIT licence. No account, API key or billing relationship is required.

Built on the MinistryPlatform Custom Widget framework ( MPCustomWidgets).

ACST powered by Vanco · 800-736-7425 · allsales@acst.com