Widgets can be added to a website with very little coding knowledge. But, it's highly likely each church will need to work closely with their web staff/team/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). Details below!
2. Configuring each desired Widget (code snippet and attributes). See Quick Start!

Shared Widget Script

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.

To add the script to your website:

1. Review the sample script below.
2. Create the shared script for your Widgets using your MP base URL. For example, if your MP domain is https://ministryplatform.com/mp, your base URL would be https://ministryplatform.com/.
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. See Specific CMS Tips for more info on your CMS.
   

For example, here is the required script element:

<script id="MPWidgets" src="https://{your platform domain}/widgets/dist/MPWidgets.js"></script>

Permitted URLs

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://www.ministryplatform.com/groups and https://www.ministryplatform.com/volunteer, then the URL https://www.ministryplatform.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://ministryplatform.com" />
        <add key="websiteSSL" value="https://ministryplatform.com" />
        <add key="websiteWww" value="http://www.ministryplatform.com" />
        <add key="websiteWwwSSL" value="https://www.ministryplatform.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.

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: Please 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 desired, 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.