Family Faith Formation Widget — Installation Guide

A login-protected page showing a parent every member of their household who is involved in Faith Formation. Each person gets their own collapsible section with two tabs: Current Groups, showing that group's leaders (including Catechists) with clickable contact information and a rundown of upcoming and past meetings with attendance; and Past Groups, listed most-recent-first, each showing the same leader and attendance detail collapsed by default.

This guide assumes basic familiarity with deploying a MinistryPlatform Custom Widget — creating a stored procedure in SSMS and adding an HTML embed to a login-gated page on your website.

Faith Formation is only the worked example. Nothing here is tied to that Ministry specifically — the widget works with any Ministry your Groups are organized under. Wherever you see Faith Formation, substitute your own Ministry name and ID. See Using a different Ministry near the end.

Built on the MinistryPlatform Custom Widget framework, with the same sign-in mechanism used by your other login-gated widgets, such as the Milestone Tracker: identity is read from the JSON Web Token the shared login script (MPWidgets.js) stores in the browser once a visitor signs in, not a cookie. There's nothing to wire up here — it's already built in and requires no edits.

What it looks like

A few things worth pointing out in that screenshot:

• Every group — current or past — can show one or more leaders. A "leader" is anyone with a Group Participant record on that group whose Group Role is typed Leader; this already covers roles like Catechist, Group Leader, Children's Teacher, or Pastoral Assistant for Faith Formation with no extra setup. The widget matches leaders to the specific enrollment window being shown — a Catechist from a child's 2021 school year shows up on that Past Group card, not just whoever is teaching the class today.
• A leader's phone number and email address are clickable — tel: and mailto: links — with the same phone and mail icons used on the Personnel Directory widget, so the two read as one family of widgets.
• "Upcoming Meetings" and "Times Present · Times Absent" are click-to-expand headers. Current Groups open expanded by default; Past Groups open collapsed, since there's usually more history to scroll past there.
• Clicking a person's name and photo at the top of their section collapses that whole person — useful when a parent wants to tuck away their own row and focus on the kids.

What you need before starting

SQL Server Management Studio access to the MinistryPlatform database, edit access to the church website, and the Ministry_ID that represents Faith Formation in your system. If you're not sure of it, look it up with:

 SELECT Ministry_ID, Ministry_Name FROM dbo.Ministries ORDER BY Ministry_Name; 

The following files ship with this guide. Run the database script first, then add the web page:

deploy_FaithFormationFamily.sql

Creates the read procedure dbo.api_custom_FaithFormationFamily_JSON and registers it with the API, in one script.

faith-formation-widget.html

The web page embed. All of your settings — which Ministry is Faith Formation, whether to show leaders' email and mobile phone, your MP host prefix — live in the FAITH_FORMATION_CONFIG block at the top of this file. There is no database configuration table. Downloads with a .txt extension from the link above — rename it to .html only if you need to open it locally; paste its contents into the embed either way.

Both are safe to re-run: the procedure uses CREATE OR ALTER and the registration steps use IF NOT EXISTS guards, so running the script again will not create duplicates or raise errors.

Step 1 — Deploy the read procedure

Open deploy_FaithFormationFamily.sql in SSMS, confirm you are connected to the MinistryPlatform database and not master — check the database dropdown — and execute it.

The script does three things, all required:

• Creates the read stored procedure dbo.api_custom_FaithFormationFamily_JSON , which returns the signed-in user's household members involved in Faith Formation, their current groups (with leader contact cards and related meetings), and their past groups (also with leader contact cards, most recent first, plus an attendance summary). Which Ministry counts as Faith Formation, and whether to show leaders' email and mobile phone, are passed in as parameters on every call — nothing is stored in the database.
• Registers the procedure in dp_API_Procedures so the MinistryPlatform API is allowed to call it.
• Links the procedure to a security role in dp_Role_API_Procedures .

Registration is easy to miss and the page will not load without it. The API checks role links, not SQL permissions.

Before running, open the script and set @RoleName , near the bottom, to the security role your website visitors sign in with — commonly the same role used by your other login-gated widgets, such as the Milestone Tracker.

The script ends with verification queries and PRINT messages that confirm each of the three steps above — a non-NULL ProcObjectId , a line confirming the procedure is registered in dp_API_Procedures , and a line confirming the role link.

Step 2 — Add the web page

Create a login-gated page on the website and add an HTML embed containing the full contents of faith-formation-widget.html . Everything you'll normally touch lives in one place: the FAITH_FORMATION_CONFIG block at the very top of the file.

 const FAITH_FORMATION_CONFIG = {
  dataHost: "catholicdemo",           // the part of your Platform URL before .ministryplatform.net
  ministryId: 13,                     // the Ministry to treat as Faith Formation (Ministries.Ministry_ID)
  showLeaderEmail: true,              // show group leaders' email address
  showLeaderMobilePhone: true,        // show group leaders' mobile phone
  filesBaseUrl: "https://catholicdemo.ministryplatform.net/ministryplatformapi/files/",
  avatarColor: "#8a1f2b",
  requireLogin: true,
  pageHeading: "Faith Formation",
  noInvolvementText: "No one in your household is currently registered in a Faith Formation group.",
  loginPromptText: "Please log in to see your family's Faith Formation activity."
}; 

The sign-in check itself needs no editing. It already matches your other login-gated widgets: it reads the same mpp-widgets_IdToken , mpp-widgets_AuthToken , and mpp-widgets_ExpiresAfter values your site's shared login script (MPWidgets.js) writes to the browser once a visitor signs in through the site's Login widget. Because of that, this page needs to carry that same Login widget — place it on a page that also includes it, the same way your Milestone Tracker and Personnel Directory pages do.

Step 3 — Test

As a quick server-side check that the read procedure is reachable, open this URL in a browser (already set for catholicdemo — swap in your own host prefix and Ministry_ID if different). You should see JSON listing the test household's involved members:

 https://catholicdemo.cloudapps.ministryplatform.cloud/sky/api/CustomWidget?storedProcedure=api_custom_FaithFormationFamily_JSON&spParams=@MinistryID=13%26@ShowLeaderEmail=1%26@ShowLeaderMobilePhone=1 

That URL alone won't be signed in as anyone, so it exercises the query logic without exercising the sign-in flow. Then open the new page while signed out on the website itself — you should see the "please log in" message. Sign in through the site's Login widget and the household's Faith Formation activity should appear on its own, matching the screenshot above.

Using a different Ministry

Nothing about the widget is tied to Faith Formation. To use it for another Ministry — Youth, Adult Small Groups, Music and Liturgy, and so on:

• Confirm the Ministry has Groups with current participants.
• Set ministryId in the embed to that Ministry's Ministry_ID .
• Reword pageHeading to suit.

You can run as many of these widgets as you like — one page per Ministry — all from the same procedure.

Troubleshooting

The page shows only the "please log in" message and never reveals anything.

The page looks for the signed-in MinistryPlatform user that your site's Login widget stores in the browser. Make sure the page, or its layout, includes that widget, and that you actually completed sign-in. Give it a few seconds — the widget rechecks periodically in case the login script writes its tokens a moment after the page loads.

A household member I expect to see is missing.

Confirm they have a Group Participant record, and that the group's Ministry matches the ministryId set in the embed. Confirm they aren't marked deceased, and that they're in the same household as the signed-in user.

A group shows no leaders.

Confirm at least one Group Participant record on that group has a Group Role typed Leader , and that its Start Date / End Date overlaps the specific enrollment window being shown — the widget matches a leader to that person's own stint in the group, whether that stint is Current or Past, not to today's date.

A leader's email or phone isn't showing.

Two switches both have to allow it: showLeaderEmail / showLeaderMobilePhone in the embed, and that leader's own MinistryPlatform "Show Email" / "Show Phone" flag on their Group Participant record.

An event I expect isn't showing up.

Confirm the event is linked to the group via Event Groups or Event Rooms, that the person has their own Event Participant record for it — the widget only shows events a person is individually registered for or attended, not every meeting the group ever had — and that the event isn't cancelled and its date falls within that enrollment's Start/End Date window.

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

Check the role link in dp_Role_API_Procedures . Re-run the registration section of the deploy script with the correct @RoleName and confirm the verification query returns a row for that role.

Everyone shows initials instead of a photo.

Look at the deploy script's output for a message starting "Could not automatically identify the Table/Record/Default-flag/GUID columns on dp_Files" — the script inspects that table's real columns before using it, and lists them if it can't recognize the shape. Share that column list and the lookup can be finished with the correct names. If dp_Files doesn't exist by that name at all on your instance, that also prints instead of erroring.

One person shows a photo and another doesn't.

Normal — it means that Contact has no file attached, or has one that isn't flagged DEFAULT in the Files panel. They'll show initials instead, same as the Personnel Directory widget's fallback.

The expand/collapse arrows change but the content underneath doesn't hide.

This would mean something on your site's theme stylesheet is overriding the widget's own collapse rule with a more specific !important declaration. The widget's CSS is scoped under #faith-formation-widget specifically to avoid this; if you've copied any of its styles out into your own theme, keep the ID scoping intact.

MinistryPlatform configuration