home

MinistryPlatform

RealmRealm AccountingMinistryPlatformGivingPDSACSConnectShepherdGrowth MethodHeadMasterRefresh WebsitesTrust CenterGo MethodMissionInsite
RealmRealm AccountingMinistryPlatformGivingPDSACSConnectShepherdGrowth MethodHeadMasterRefresh WebsitesTrust CenterGo MethodMissionInsite

What would you like to know more about?

Show Contents

Show Page Sections

thumbnailMinistryPlatform

Widgets

Enabling Widgets

Important: These configuration details are shared by and required for any and all Widgets.
Note: Widgets can be added to a website with very little coding knowledge. It is highly likely each church will need to work closely with their web staff, team, or vendor to successfully integrate Widgets into the existing ecosystem of their website.

You can enable Widgets on your website by:

  1. Completing the shared Widget configuration (script and permitted URLs).
  2. Configuring each Widget you want with its code snippet and attributes. See Quick Start.

Add Shared Widget Script

Diagram showing a figure labeled "app" pointing to two separate pages labeled "script" that each contain a box labeled "widget"

All Widgets are powered by a shared script. This script contains all the logic for Widgets powered by your Widgets application. The script must be added to any page which will contain Widgets. The simplest approach is to add it to your site header so it is available to all pages. For example, here is the required script element configured for example-church.com:

<script id="MPWidgets" src="https://example-church.com/widgets/dist/MPWidgets.js"></script>
  1. Review the sample script.
  2. Copy the shared script for your Widgets and replace the URL with your base Platform URL. For example, if your MinistryPlatform URL is https://example-church.ministryplatform.net/mp, your Platform base URL would be https://example-church.ministryplatform.net.
  3. From your CMS (website management software), add this script to your website header. If this is not possible in your CMS, add the script to any page which will contain Widgets.

Permitted URLs

Important: Permitted URLs are case-sensitive, so make sure you add both uncapitalized and capitalized versions of your URL as permitted URLs in your list. (For example, both https://example-church.com and https://Example-Church.com.)

Any website where a Widget is placed must be included in your permitted URLs list. For example, if you place the Group Finder and Opportunity Finder widgets on your main website at https://example-church.com/groups and https://example-church.com/volunteer, then the URL https://example-church.com (with no trailing slash) needs to be on the permitted URLs list. You may have multiple permitted URLs.

  • The key for each permitted URL must be unique.
    • For example: 
      <permittedUrls>
    <add key="website" value="http://example-church.com" />
    <add key="websiteSSL" value="https://example-church.com" />
    <add key="websiteWww" value="http://www.example-church.com" />
    <add key="websiteWwwSSL" value="https://www.example-church.com" />
</permittedUrls>
  • Best Practices:
    • "http" is distinct from "https". Add both versions as permitted URLs.
    • "www.domain.com" is distinct from "domain.com". Add both versions as permitted URLs.
    • Make sure you do not include a slash at the end of any permitted URLs.
  • After changing your permitted URLs, you'll need to recycle the widgets application pool for any updates to take effect. If you don't have access to your server, coordinate your changes with someone who does or contact Support.
Note: A SPoC can contact Support to add, change, or remove permitted URLs. We're here to help!

Important Considerations

  • The Administrator's Security Role needs to have permission to many API Procedures. If API Procedures are missing, reach out to Support for help. If a Procedure is missing, you'll receive an error in the Widget that Procedure "X" does not exist, or User "Y" does not have access to it.
  • It is best practice to have an SSL certificate installed on any website that utilizes Widgets. It might be possible to use Widgets without the certificate, but it is not advisable.
  • Shared Cloud churches: Contact Support to configure additional sites. We have already configured the church website we have on record for you.
  • Self-Hosted and Dedicated Cloud churches:
    • Contact Support to configure additional sites.
    • If needed, you can manage this list in the SaaS config file found under: \widgets\wwwroot\_DomainData\saasdomains\customer.config
      • Keys must be unique for each permitted URL. If keys are duplicated, only the last URL for each key will be permitted.
      • If you are configuring a domain starting with www, it's a good idea to also include the version without the "www" prefix.

Foundational Widgets

Widgets are flexible and a church may opt to use as many or as few Widgets as they would like. Whenever a Widget is added to a website page, it is highly recommended that both the Login Widget and Language & Locale Widget be added as well. These foundational Widgets improve the capabilities of all other Widgets.

portal
MinistryPlatform

Last updated: November 26, 2024