Getting Started — Installation Guide

What a custom widget is

A standard MinistryPlatform widget is built for you. You choose it in the Widget Configurator, set a few parameters, and paste the code — that process is covered on Adding Widgets.

A custom widget is a shell. You supply the data, usually as a stored procedure you install in your own database, and you supply the presentation as a Liquid template. The toolkit handles the parts in between: calling the API, passing the signed-in user through, binding query-string values, caching, and rendering the template into the page.

The trade is control for effort. A custom widget can present anything in MinistryPlatform in any layout you want. It also means you own a stored procedure and a template that no one at ACST will patch for you.

Custom widgets are included with MinistryPlatform at no additional cost.

What you need before starting

Access to add pages and HTML blocks on your website; and, for most widgets, SQL Server Management Studio access to the MinistryPlatform database. A widget that reads only published events needs no database work at all — the Event Calendar is one of these — but most of the interesting ones ship a stored procedure.

You will also need to be signed in to MinistryPlatform as an administrator to check the API Clients page.

Step 1 Confirm the platform side is ready

Three things must be true before any widget will return data. They are all one-time setup for the instance, not per widget.

Step 2 Find your domain prefix

Almost every setting you will touch depends on this one value, and it is the single most common thing to get wrong.

Launch the Add/Edit Family tool from within MinistryPlatform and look at the URL. Your domain prefix is what appears before .cloudapps.ministryplatform.cloud .

In https:// catholicdemo .cloudapps.ministryplatform.cloud/tools... the prefix is catholicdemo .

Confirm the API is reachable before going any further:

 https://<prefix>.cloudapps.ministryplatform.cloud/sky/swagger/index.html 

Step 3 Install the stored procedure

Skip this step for widgets that read published events only.

Each widget guide links the SQL script it needs. Open it in SSMS, confirm the database dropdown shows the MinistryPlatform database and not master , and execute it. Every script in this library does the same three things, and all three are required:

1. Creates the procedure, named api_custom_<something> . The api_custom_ prefix is not decoration — the API will not call a procedure without it.
2. Registers it in dp_API_Procedures .
3. Links it to a security role in dp_Role_API_Procedures .

The scripts end with verification queries. Read them rather than the printed messages: on some MinistryPlatform versions an insert can roll back while the PRINT that follows it still runs, so the script will cheerfully claim success it did not have.

The @UserName parameter

The Custom Widget API passes @UserName automatically whenever the visitor is signed in. Every procedure in this library accepts it, and any procedure you write yourself should too.

Give it a default of NULL if the widget does not need it. A parameter declared NOT NULL without a default will cause the procedure to fail for anonymous visitors — the API simply will not supply a value it does not have.

Verify the API can reach it

In a browser, with <prefix> and the procedure name substituted:

 https://<prefix>.cloudapps.ministryplatform.cloud/sky/api/CustomWidget?storedProcedure=api_custom_YourProcedure 

You should see JSON. If the response complains that a parameter was not supplied, append &@DomainID=1 and try again. If it says the procedure does not exist or user does not have access to it , that is almost always the missed role link from step 3 — see Troubleshooting.

If the script succeeded but the API still doesn't see it

This is the single most common way a correct installation appears to fail, and it is worth recognising before you start editing SQL that was already right.

You have two ways forward.

If you are hosted on MinistryPlatform Cloud , you do not have server access and cannot do this yourself. Raise a ticket with support asking them to recycle the MinistryPlatform API application pool, and say why — that you have installed a new custom widget stored procedure and the API is not yet seeing it. That phrasing gets it handled quickly, because it is a request they recognise.

If MinistryPlatform runs on a server you control , someone with administrative access to that server can do it in under a minute:

1. Remote onto the MinistryPlatform web server.
2. Open Internet Information Services (IIS) Manager.
3. Expand the server node and select Application Pools.
4. Find the pool serving the MinistryPlatform API. It is usually named for the API site — confirm which by selecting Sites, finding the API site, and reading its application pool in the Basic Settings.
5. Right-click the pool and choose Recycle.

Or, from an elevated PowerShell prompt on the same server:

 Restart-WebAppPool -Name "YourApiAppPoolName" 

If the recycle does not fix it, the cache was not the cause. Go back to the three registration checks in Troubleshooting; something in dp_API_Procedures or dp_Role_API_Procedures does not match.

Step 4 Understand the widget tag

The widget itself is one empty <div> . The attributes on it are the whole configuration:

 <div id="MyCustomWidget"
     data-component="CustomWidget"
     data-sp="api_custom_GroupWidget"
     data-template="/Widgets/WidgetTemplate/Template/template.html"
     data-requireUser="false"
     data-cache="true"
     data-host="mpi"></div> 

Where the template lives

data-template is a URL to an HTML file containing the Liquid markup. In the repository examples it is a site-relative path, which assumes you can host arbitrary .html files on your web server. Many website builders cannot.

The deployments on this site point at the file in the GitHub repository instead, which works and needs nothing hosted. Prefer the jsDelivr mirror over a raw GitHub URL:

 https://cdn.jsdelivr.net/gh/MinistryPlatform-Community/MPCustomWidgets@main/Widgets/<Widget>/Template/<file>.html 

jsDelivr is a CDN with sensible caching and no rate limit for ordinary traffic. raw.githubusercontent.com is neither, and is throttled under load.

The trade-off is that pointing at @main means your page follows the community repository. If a template changes upstream, your page changes with it. For a production site, copy the template to your own hosting or pin a specific commit rather than @main .

Step 5 Add the page and paste the code

Create a page on your website and add a single HTML block to it. Into that block goes the widget <div> , followed by the toolkit script:

 <script type="text/javascript"
        src="https://cdn.jsdelivr.net/gh/MinistryPlatform-Community/MPCustomWidgets@main/dist/js/customWidgetV1.js"></script> 

The script must come after the widget div. It initialises on DOMContentLoaded ; anything that configures the tag has to be in place before that fires, or the widget runs with no host and returns nothing.

Some widgets need more — a charting library, the FullCalendar library, the modal helper, a stylesheet from the widget's Assets folder. Each widget guide lists what else to load and where it goes.

If the widget requires a login

Add MinistryPlatform's shared widget script. On Refresh sites this goes in More → Settings → Head HTML → Body End HTML, so it loads on every page and you do not have to repeat it:

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

Note the .ministryplatform.net host, not cloudapps. This script supplies the <mpp-user-login></mpp-user-login> element, which gives visitors somewhere to sign in and gives the toolkit the identity it passes to your procedure as @UserName .

A note on HTML comments

Several website builders — Duda among them — strip the <!-- and --> markers from an HTML embed and render what was between them as ordinary page text. If you want to leave notes for the next administrator, put them in a JavaScript or CSS comment instead. If you see blocks of explanatory text appearing on your live page, this is why.

Step 6 Test

1. Open the page. The widget should render within a second or two.
2. Open the browser console (F12). With data-debug="true" you will see the request the widget made and the response it got — this tells you immediately whether the problem is the API or the template.
3. For a widget requiring a login, sign out and reload. You should get the sign-in prompt, not an error and not a blank space.
4. Check it on a phone-width browser.
5. Set data-debug to false and publish.

Troubleshooting

This message comes from the MinistryPlatform API, not SQL Server, and almost always means a missed registration step. Check in order:

• The procedure exists in the right database and in the dbo schema.
• A row exists in dp_API_Procedures with the exact name and no trailing spaces.
• A row links it to a role in dp_Role_API_Procedures .

The deploy script's verification queries check all three. If all three pass and the API still refuses, the procedure is almost certainly fine and the API has simply not noticed it yet — see If the script succeeded but the API still doesn't see it in Step 3.

Almost always data-host . Confirm the prefix, then open the Step 3 verification URL directly in a browser. If that returns JSON and the page does not, the problem is on the page — check the console for a script error and confirm the toolkit script comes after the div.

The template did not render. Look for a Liquid error in the console, and confirm data-template resolves — paste the URL into a browser and check you get HTML rather than a 404 or a GitHub error page.

Your site theme is winning the specificity contest against the widget's stylesheet. The fix is to scope the widget's CSS under its own container ID, which beats any selector that does not itself contain an ID. If a theme still breaks through, it is using !important or its own ID selector.

Either the shared widget script is missing, or the page's URL is not on the permitted list from Step 1, or data-requireUser is false . All three produce the same symptom: @UserName arrives as NULL and the procedure returns nothing.

Three caches sit between you and the page: the API's registered procedure list, the widget's own five-minute response cache, and your browser's. Work through them in that order — a hard refresh and data-cache="false" clear the second and third in seconds, and only if the direct API URL is also stale do you need the recycle described in Step 3.

Where the widgets come from

There is no single catalogue. Custom widgets reach you from several places, and it is worth knowing which you are looking at, because it determines where the files live and who you ask when something breaks.

Each widget has its own folder under /Widgets containing a demo.html with the tag to copy, a Template folder with the Liquid file, a StoredProc folder where one is needed, and an Assets folder for any CSS or JavaScript the widget requires. WidgetTemplate is the empty shell to clone when writing your own. The repository is a community project; the code is offered as-is, and contributions are welcome.

A sample of what's in there

The list below is a snapshot taken at the time of writing, offered to show the kinds of things people build rather than as a catalogue. It is a community repository, so widgets are added and changed without notice — always browse the repository itself for what is there today. Select any widget for a short description.

Several of the widgets demonstrated here do not exist in the community repository. They were built for this site, and their scripts, templates and embed code ship with their own installation guide rather than from GitHub. Where that is the case, the guide says so and lists the files by name. Take them from the guide, not from a repository search that will not find them.

Partners, consultants, other MinistryPlatform churches, and anything you or your developer writes. The framework is open — a custom widget is just a registered stored procedure and a Liquid template, so anyone can produce one.

Vetting a widget before you install it

A custom widget is not a plugin running in a sandbox. Installing one means running SQL you did not write against your MinistryPlatform database, and pointing a page at a template hosted somewhere you may not control. Both deserve a look before you proceed, whatever the source.

• Read the SQL before you run it. You are looking for what it selects and what it writes. Most of these procedures are read-only; one that issues an INSERT or UPDATE should say so in its guide, and you should understand why.
• Check what data it exposes. A procedure that returns more columns than the template displays is publishing them anyway — anyone can read the API response directly. This matters most for widgets touching contacts, giving or sacramental records.
• Check whether it requires a login, and whether it should. A widget reading personal data with data-requireUser="false" is a problem regardless of how good it looks.
• Know where the template is served from. If it points at a repository's @main branch, your page follows whatever that repository does next. Fine while evaluating, worth pinning or copying before you go live.
• Test on a draft page first. An unpublished page with real data tells you more than any amount of reading, and costs nothing if it goes wrong.