MINISTRYPLATFORM CUSTOM WIDGET

Organization Directory — Installation Guide

A public directory of the organizations in your diocese — parishes, schools, cemeteries, hospitals, the chancery, or any mix of them. Visitors browse alphabetically, by city or by deanery, search by name, and filter to the organizations within a chosen distance of their ZIP code, with every one plotted on a map. No login required, no mapping API key, no billing account.

This guide assumes you have read Getting Started. It covers the Organization Finder and the Organization Detail page it links to.

The directory configured for parishes: browse A–Z or by city, search by name, or find the parishes nearest a ZIP code, with every one plotted on the map.

What the page does

The widget reads your Congregations where Available Online is Yes, follows each to its Location record and that Location's Address, and uses the address coordinates for the map and the distance search. From the Location it also reads the Category and the Group, which is what makes the page generic.

  • Browse A–Z — grouped under sticky letter headings with a jump bar across the top.
  • Browse by city — grouped by city, with a count beside each name.
  • Browse by deanery — a third option, appearing only when you configure a Location Group Type. The button and the headings take the group type's own name, so Deanery gives a "By Deanery" button.
  • Search — narrows as the visitor types, matching name, location name, street, city, state, ZIP, county, category and group. Accents are folded, so avila finds Ávila.
  • Find organizations near me — a ZIP code, city or address, or one tap on Use my location. Results re-sort nearest-first, numbered to match the map pins, with the radius drawn as a ring.
  • Map — clicking a pin opens the name, address, phone and a Get directions link.
  • Pinned categories — organizations in a category you nominate sit in their own section above the list, and are exempt from the distance filter, so the chancery is never returned as the nearest parish.

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

The titles write themselves

Leave pageTitle blank and the heading is built from the categories the query actually returns:

Categories returned Heading Back link
Parish Find a Parish All Parishes
Parish, School Find a Parish or School All Parishes and Schools
Parish, School, Hospital Find a Parish, School, or Hospital All Parishes, Schools, and Hospitals
Office Find an Office All Offices
Cemetery Find a Cemetery All Cemeteries

Irregular plurals and the a/an distinction are handled. The count line, the search label, the map hint and the empty state all follow the same wording, so a school directory says "12 schools" rather than "12 parishes". Set pageTitle , backLabel , nounSingular or nounPlural to override any of it.

One caveat worth knowing. The categories are taken from the rows returned, not from your configuration, so a page left wide open reports what it finds. If your chancery's Location carries the Office category and nothing is pinned, the heading reads "Find an Office or Parish". Setting pinnedCategoryIDs fixes both the heading and the layout.

What you need before starting

SQL Server Management Studio access, edit access to the diocesan website, and the five files below.

The two embeds download as .txt files. The content management system will not serve an .html attachment, so they are published as organization-finder-embed.html.txt and organization-detail-embed.html.txt . The contents are unchanged — open them in a text editor, or save them without the .txt if you prefer. Nothing needs editing before you paste them, beyond the configuration block at the top of each.

If you do not have a dedicated hosting plan or the required SQL Server skills, reach out to the professional services team for assistance. Normal hourly rates will apply.

Step 1 Run the database scripts

Open each in SSMS, confirm the database dropdown shows the MinistryPlatform database and not master , and execute it. Run them in this order, because each builds on the last:

  1. deploy_OrganizationFinder.sql
  2. deploy_OrganizationFinder_logos.sql — replaces the procedure the first one created, adding the image column
  3. deploy_OrganizationDetail.sql — reuses the image view the second one created

Each script creates its procedure, registers it in dp_API_Procedures , and links it to the Administrators role in dp_Role_API_Procedures .

The role link is the step most often missed, and nothing works without it. The API checks role links, not SQL permissions.

Read verification query 4e before you configure anything

The finder script ends with a query listing the Location Categories and Location Group Types on your instance, with a count of Available Online organizations against each. Use those IDs, not the ones in this guide.

This is not pedantry. On the demo instance the Location Group Types read Deanery = 1 , Vicariate = 2 , Deanery (b) = 3 , Vicariate (b) = 4 , Region = 5 — so the obvious guess of 3 for Deanery selects a decoy with no groups attached, and the browse option silently shows nothing. Query 4e is the only reliable source.

Step 2 Verify the API can reach the procedures

In a browser, replacing yourdiocese with your host prefix:

 https://yourdiocese.cloudapps.ministryplatform.cloud/sky/api/CustomWidget?storedProcedure=api_custom_OrganizationFinder

You should see JSON listing your organizations. If it complains that a parameter was not supplied, append &@DomainID=1 .

Testing with parameters by hand needs spParams . Appending &@LocationCategoryIDs=1 does nothing — the API ignores it and returns everything, which looks exactly like a broken filter. The correct form encodes the whole set as one value:

 ...?storedProcedure=api_custom_OrganizationFinder&spParams=@LocationCategoryIDs=1%26@LocationGroupTypeID=1

Note the %26 between parameters. The widget does this for you; it only matters when you are testing a URL yourself.

Step 3 Add the directory page and configure it

Create a page — /organization-directory or /find-a-parish — and add one HTML embed containing the whole of organization-finder-embed.html . Everything an administrator touches is in the ORG_CONFIG block at the top.

Setting What it does
dataHost Required. Your MP host prefix, the part of your Platform URL before .ministryplatform.net .
locationCategoryIDs Which kinds of organization to list. "" for every category, "1" for one, "1,6,7" for a set. From query 4e.
pinnedCategoryIDs Categories pinned above the list and exempt from the distance filter — normally your Office category. "" pins nothing.
browseGroupTypeID Adds the third browse option, grouping by Location Group. Set it to a Location Group Type ID. "" hides the option.
congregationIDs "" for everything Available Online, or a list to restrict to a cluster. One deployment can serve a diocesan page and a page per deanery.
pageTitle , pageIntro , backLabel , nounSingular , nounPlural Overrides for the derived wording. Leave blank to let the page name itself.
officesTitle The heading over the pinned section.
detailPage Everything up to the identifier, default "/organization-detail?id=" . The Congregation ID is appended. "" hides the link and the Details button.
brandColor , brandColorDark , accentColor Buttons, pins, focus rings, distance badge.
mapStyle , mapCenter , mapZoom "light" , "street" or "terrain" ; centre and zoom are used only until the pins are plotted.
ignoreLeadingTitles true files St. Mary under M. Leave it on: a literal A–Z puts most parishes under S.
radiusOptions , defaultRadius , units , geocodeCountry The distance dropdown. Use units: "km" outside the United States.
showLogos , logoFit , fileBaseUrl The organization image. "cover" fills and crops; "contain" letterboxes.
showPhone , showDescription , showGivingLink Optional card content.
pageSize , compactThreshold , clusterThreshold Large-diocese behaviour. A small diocese never reaches these.
demoMode , debug Testing aids. Both false in production.

An organization with no Location drops out the moment you set a category. It has no category to match on. On a wide-open page those records still appear, labelled Address not published ; add a category filter and they disappear. That is correct, but it surprises people.

Step 4 Add the detail page

Create /organization-detail and add the whole of organization-detail-embed.html . Its configuration object is ORGD_CONFIG .

The organization is chosen by the query string. The finder links to /organization-detail?id=13 and the widget tag passes it straight through:

 data-params="@CongregationID=[id]"

The square brackets are the toolkit's query-string binding. One embed serves every organization in the diocese.

Setting What it does
directoryPage Where the back links point. Default "/organization-directory" .
backLabel , backButton Override the back-link wording. Blank derives it from this record's own category, so a school page says "All Schools".
pinnedCategoryIDs Keep the same as the directory's, so a chancery page can be told apart from a parish page.
idParam The query-string parameter carrying the ID. Change it only if you changed the directory's detailPage .
heroHeight , heroHeightMobile , heroOverlay The photograph band and the strength of the wash behind the name.
The Organization Detail page behind each result: photograph, address, phone, pastor, parish office, weekly Mass schedule and directions.

Sparse records degrade rather than break: no photograph gives a brand-coloured panel with a monogram, no coordinates omits the map and directions, no Mass events keeps the section and says none are published, and an unknown ID gives a "we could not find that record" panel with a link back.

Step 5 Test

  1. Open the finder. You should see the toolbar, the list grouped under letter headings, and one pin per organization.
  2. Check the heading. It should name the categories you configured.
  3. Switch to By City, then By Deanery if you set a group type. Sections should become city and deanery names with counts.
  4. Enter a ZIP code, choose a radius, press Search. The list re-sorts nearest-first with numbered badges and a ring appears on the map.
  5. Confirm the pinned section sits above the list and stays visible during a distance search.
  6. Click a name. The detail page should open with the back link naming the right category.
  7. Narrow the browser to phone width. List and Map become tabs.

MinistryPlatform configuration

Field Requirement
Congregations → Available Online Yes. The only switch controlling whether an organization appears.
Congregations → Congregation Name What visitors see and what search matches. Pick St. or Saint and stay with it.
Congregations → Location Must point at the organization's Location record.
Locations → Location Category New requirement. Drives the filter, the derived heading and the pinned section. An organization with no category cannot satisfy a category filter.
Locations → Location Group Needed only for the browse-by-group option, and only for groups of the configured type.
Locations → Address Street, city, state, postal code. Also what the Directions button hands to Google Maps.
Addresses → Latitude / Longitude Required for the map and distance search. Clear Do Not Validate and let MinistryPlatform geocode, or enter them by hand.
Locations → Phone Optional, shown as a tap-to-call link.
Congregations → End Date, Coming Soon Hidden by the procedure. Retire a closed parish by setting the End Date rather than deleting it.

Schools and cemeteries are usually not Available Online. They exist as Congregation records but with the flag off, so they will not appear until you switch it on — which is the first thing to check when a category filter returns nothing.

A stock instance may not have the categories you need. MinistryPlatform ships Parish, Facility, Department, Office and Organization. School, Cemetery and Hospital may have to be added before a mixed directory means anything.

Troubleshooting

The browse-by-group button never appears.

Either browseGroupTypeID is blank, or it points at a group type with no groups assigned to any Location. Run query 4e and use the ID it reports — see the warning in Step 1 about decoy group types.

A category filter returns nothing.

Three candidates, in order: the organizations are not Available Online; their Locations have no Location Category; or the ID is wrong. Query 4e settles all three at once.

The heading names a category I did not expect.

The wording comes from the rows returned, not the configuration. Something in that category is in the results — most often the chancery. Set pinnedCategoryIDs .

The chancery is mixed in with the parishes.

pinnedCategoryIDs is blank, so nothing is pinned. Set it to your Office category.

Hand-testing a parameter has no effect.

You are appending it as its own query argument. Use spParams with %26 between parameters, as in Step 2.

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

Almost always the role link. Check the procedure exists in dbo , a row exists in dp_API_Procedures with the exact name, and a row links it to a role. If all three pass, see If the script succeeded but the API still doesn't see it in Getting Started.

Everything is centred, or the fonts are wrong.

The host theme is winning on specificity. Every rule is scoped under #pf-root , which beats any selector without an ID. If a theme still breaks through it is using !important or its own ID selector; add #pf-root to the front of the offending rule.

Blocks of documentation text appear on the page.

Your builder stripped the HTML comment markers. Neither embed contains HTML comments for this reason; keep any notes of your own in a JavaScript or CSS comment.

Attribution

Map rendering uses Leaflet with tiles from CARTO and OpenStreetMap; address lookup uses OpenStreetMap Nominatim. The attribution in the corner of the map must not be removed. None of these services requires an account, an API key or a billing relationship.

Built on the MinistryPlatform Custom Widget framework ( MPCustomWidgets).

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