MINISTRYPLATFORM CUSTOM WIDGET

Family Sacraments — Installation Guide

A signed-in page showing the sacraments received by everyone in a household — baptism, first communion, confirmation, marriage — with the date, the place, who performed it, and the spouse where one applies. Read-only, drawn straight from the Sacraments records your staff already maintain, so the office stops fielding calls asking for dates and certificates.

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

The page as a signed-in head of household sees it: one section per family member, each sacrament with its date, place and celebrant. Names are obscured here for privacy.

Because the live demo requires a login, this is what you would otherwise not be able to see.

What the page does

A parishioner signs in with their MinistryPlatform account. The widget resolves that login to their Contact record, finds their household, and lists every member of it with their sacraments beneath their name. Members are ordered by household position, so the head of household appears first and children follow, each sorted by name.

For each sacrament the page shows the type, the date, the place it was celebrated, who performed it, and — for marriage — the spouse.

Nothing is written back. This widget only reads.

Read this before you deploy it

Only the head of household sees anything.

The stored procedure checks the signed-in contact's Household Position. If it is Head of Household (position 1), it returns the whole household. If it is anything else, there is no ELSE branch — the procedure returns an empty result and the visitor sees a blank page.

In practice this is less restrictive than it sounds. MinistryPlatform's convention is that both married adults are marked Head of Household, so a husband and wife each get the full household view. The people shut out are the other positions: Minor Child, Adult Child, Other Adult, Guest Child.

That is a defensible privacy decision — a household's sacramental history is not something a guest or a minor should be able to pull up. But it is invisible to the person it affects. An adult child signing in gets no data and no explanation, which reads as a broken page rather than a policy.

You have three honest options:

  1. Leave it and say so on the page. Add a line above the widget: "Sacramental records are visible to the adults listed as head of household. If you need your own record, contact the parish office." Cheapest, and no SQL.
  2. Admit adult children. Adding position 4 to the test covers the most common complaint without exposing minors' records to each other.
  3. Give everyone their own record. Add an ELSE branch returning only the signed-in contact's sacraments. More work, but nobody sees an empty page.

Decide this before you publish. Retrofitting it after parishioners have reported the page as broken is a worse conversation.

Audit Household Position before you rely on the gate. If a married couple has only one of the two marked Head of Household, the other is locked out for no reason anyone intended. This field is frequently left at whatever the import set, because until now nothing depended on it.

Check what is actually in your Sacraments table first. Many parishes hold decades of sacramental history on paper and only a partial set in MinistryPlatform. A page that confidently shows two of a family's nine sacraments is worse than no page at all — it looks like data loss. Run the audit query below before you decide to publish.

Step 1 Install the stored procedure

Follow Step 3 of Getting Started. The script is:

 Widgets/FamilySacramentsJSON/StoredProc/api_custom_SacramentViewerWidget_JSON.sql

It creates dbo.api_custom_SacramentViewerWidget_JSON , registers it in dp_API_Procedures , and links it to the Administrators role. Change @RoleName if your widget API client uses a different role.

What it reads

Table Used for
dp_Users Resolves the signed-in @UserName to a Contact ID.
Contacts The household, the participant record, the household position, and the names shown on the page.
Household_Positions The position label, and the head-of-household test.
Sacraments The records themselves, matched on the contact's Participant Record.
Sacrament_Types Baptism, Confirmation, Marriage and so on.
Sacrament_Places Where it was celebrated.
dp_Files The contact photograph, where one is attached.

It returns JSON, not rows

Unlike most widgets in the library, this procedure ends in FOR JSON PATH and returns a single JsonResult column containing the whole nested structure — contacts, each with their sacraments. The _JSON suffix on the procedure name is the signal.

The practical consequence: if you edit the procedure, the shape of that JSON is a contract with the template. Adding a column to the SELECT will not appear on the page until you also reference it in the Liquid, and renaming one will silently blank the field that used it.

Be careful what you add to the SELECT

Sacraments is a secured record type in MinistryPlatform, and it holds considerably more than the five fields this widget publishes. Among the columns sitting alongside them are Annulment , Interfaith , Protocol_Number , Notes (2,000 characters of free text), Place_of_Burial and Date_of_Burial , and the sacramental register references Volume , Page and Entry .

None of these belong on a public-facing page. An annulment flag in particular is exactly the sort of thing a parishioner would be distressed to find published to their household, and the register references are internal record-keeping. The shipped procedure selects a deliberately narrow set. If you widen it, widen it on purpose.

Audit your data before publishing

The last thing to do in SSMS is find out what parishioners will actually see. A count of sacraments per household, and a list of contacts with none, will tell you quickly whether the page is ready. Households with a plausible full set are the ones to spot-check against the paper register.

Step 2 Add the shared widget script

This widget requires a login, so the page needs MinistryPlatform's shared widget script. On Refresh sites put it in More → Settings → Head HTML → Body End HTML so it loads site-wide:

 <script id="MPWidgets" src="https://yourprefix.ministryplatform.net/widgets/dist/MPWidgets.js"></script>

Note .ministryplatform.net , not the cloudapps host the API uses.

Confirm too that the page's URL is on the permitted list you asked support to whitelist in Step 1 of Getting Started, for both your design environment and the published site. A widget requiring a login fails quietly from a URL that is not on that list, and the symptom looks identical to a broken procedure.

Step 3 Add the page and paste the widget

 <div class="mp-text-end">
  <mpp-user-login></mpp-user-login>
</div>
<div id="SacramentWidget"
     data-component="CustomWidget"
     data-sp="api_custom_SacramentViewerWidget_JSON"
     data-template="https://cdn.jsdelivr.net/gh/MinistryPlatform-Community/MPCustomWidgets@main/Widgets/FamilySacramentsJSON/Template/FamilySacraments.html"
     data-requireUser="true"
     data-cache="false"
     data-debug="false"
     data-host="yourprefix"></div>
<script type="text/javascript"
        src="https://cdn.jsdelivr.net/gh/MinistryPlatform-Community/MPCustomWidgets@main/dist/js/customWidgetV1.js"></script>

Two settings matter more here than elsewhere:

data-requireUser="true" . Without it the toolkit never passes @UserName , the procedure cannot resolve a contact, and every visitor sees an empty page.

data-cache="false" . This is not optional for this widget, and it is where the repository demo and good practice diverge. The toolkit caches responses for about five minutes. On a page where every visitor sees different data, caching is at best stale and at worst wrong. Public widgets cache; personal widgets do not.

Include the login element. <mpp-user-login> is what gives a signed-out visitor somewhere to sign in. Without it they land on a page that requires an account with no way to get one, and the page appears simply not to work.

Step 4 Style it

The template is built on Bootstrap 5 conventions with the repository's mp- class prefix, and renders a bordered table per household member. Copy the widget's CSS from the repository onto your site, or into a <style> block in the same embed.

The template also carries custom CSS for ribbons on the sacrament cards, a description height limit, and a placeholder icon for contacts with no photograph attached. Keep the placeholder rule — without it, members without a photo leave a hole in the layout rather than a neutral icon.

Scope everything under #SacramentWidget . The table inherits from your theme otherwise, and parish site themes have a habit of centring table cells and resetting borders.

Step 5 Test

Test this widget with more than one account. Its whole behaviour depends on who is signed in, so a single successful test proves very little.

  1. Signed out. The page should offer a sign-in, not an error and not a blank space.
  2. As a head of household with records. Every member of the household should be listed, ordered with the head first, each sacrament showing type, date, place and celebrant.
  3. As a head of household with no sacraments recorded. Confirm the page degrades to something readable rather than an empty frame.
  4. As a spouse or adult child in the same household. This is the case that will generate support calls. Confirm you get whatever you decided in Read this before you deploy it — and that the page explains itself.
  5. Check a marriage record. The spouse name is the field most likely to be blank in real data.
  6. Sign out and back in as a different household. Confirm you see the second household's data and not a cached copy of the first. If you see the first, data-cache is still true .
  7. Set data-debug="false" and publish.

MinistryPlatform configuration

Field Requirement
Contacts → Household Every member must point at the same Household record. A contact attached to no household cannot be reached by this widget at all.
Contacts → Household Position Drives both the ordering and the head-of-household gate. A household with no member marked Head of Household shows nobody anything.
Contacts → Participant Record Sacraments are matched on this, not on Contact ID. A contact with no participant record shows with no sacraments even when records exist.
Contacts → Nickname Used for display and for sorting within a household position.
Sacraments → Sacrament Type Required. Baptism, Confirmation, First Communion, Reconciliation Prep, Marriage, Holy Orders, Anointing of the Sick, Death on a default instance.
Sacraments → Date Received Shown formatted. A missing date renders an empty line rather than hiding the sacrament.
Sacraments → Place Optional but expected by visitors — for many families this is the detail they came for. Held as Place_ID against Sacrament Places, with Place_Name as free text where no lookup matches.
Sacraments → Performed By Optional. Same pattern: Performed_By_ID to a Contact, or Performed_By_Name as text.
Sacraments → Spouse Marriage records only. Spouse_ID to a Participant, or Spouse_Name .
dp_Files on the Contact Optional photograph. Falls back to a placeholder icon.

Household Position is doing more work than it looks. It controls who can see the page, what order members appear in, and whether the household resolves at all. It is worth auditing before launch — it is a field that is often left at its default because until now nothing depended on it.

Troubleshooting

The page is blank for everyone, signed in or not.

Check data-requireUser is true and the shared widget script is loading. Open the console: if the request went out with no @UserName , the toolkit never established an identity, which is the shared script or the permitted-URL list.

A specific person sees a blank page while others are fine.

Almost certainly the head-of-household gate. Check that contact's Household Position — anything other than Head of Household returns nothing. If it is one of two married adults, the usual cause is that only one of them was marked Head of Household. This is the expected behaviour of the procedure as shipped — see Read this before you deploy it.

A member appears but with no sacraments, though records exist.

Their Contact has no Participant Record, or the sacraments are attached to a different participant. Sacraments join on Participant, not Contact.

Nobody in a household appears.

No member is marked Head of Household, so the gate never opens. Set the position on the appropriate contact.

One person sees another household's data.

data-cache is true . Set it to false and hard-refresh. Treat this as urgent: on a page showing personal records it is a disclosure, not a display bug.

Dates render oddly, or as raw values.

The template formats dates in Liquid. If you have edited the procedure and changed the column name or its type, the filter no longer matches. Compare against the unmodified script.

The layout collapses, or the table is centred.

Theme bleed. Scope the widget's CSS under #SacramentWidget — see Step 4.

"Procedure … does not exist or user does not have access to it."

Usually the role link in dp_Role_API_Procedures . If the deploy script's verification queries all pass and the API still refuses, the registration is fine and the API has not picked it up yet — see If the script succeeded but the API still doesn't see it in Getting Started for how to recycle the application pool.

Attribution

Built on the MinistryPlatform Custom Widget framework ( MPCustomWidgets). Layout conventions follow Bootstrap 5.

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