@apollosproject/canvas-embeds v2.1.140

Apollos Embeds

Apollos React Embeds are pre-built, reusable components designed to integrate seamlessly into third-party websites such as Webflow. These widgets provide functionality for authentication, content feeds, and search features, creating a unified and engaging user experience across platforms.

Getting Started with Apollos Embeds

1. Adding Script Tags to Your Website

To enable the Apollos Embeds, include the following scripts and stylesheets in your website's code. For Webflow users, add them to the Custom Code section under Footer Code:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.css"
/>
<script
  defer
  src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
></script>

3. Understanding Embed Modes

There are three primary modes in which Apollos Embeds can be used:

• Apollos Site Mode
• Container Mode
• Legacy Modal Mode

Apollos Site Mode

In the Apollos Site Mode, all embeds link to the external Apollos site. This mode is recommended for users who want to maintain a consistent user experience across platforms, and it is the default mode for all embeds.

Container Mode

In the Container Mode, embeds are displayed within a container on the host website. This mode is recommended for users who want to keep users on their website while providing Apollos functionality. This mode also enables the user to cleanly integrate Apollos content into their website, while also applying custom styles.

To enable the Container Mode, add the data-apollos-path="/apollos" attribute to the script tag:

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
  data-apollos-route="/apollos"
></script>

On the host website, visiting any feed or content will navigate to the /apollos path on the host website. This path (which is customizable) should contain a div with the ID apollos-widget-container to display the embed content. This container should be styled to match the host website's design.

Legacy Modal Mode

In the Legacy Modal Mode, embeds are displayed in a modal window on the host website. This mode is recommended for users who want to keep users on their website while providing Apollos functionality. All embeds will be displayed in a modal window, with navigation state being tracked via URL search params.

To enable the Legacy Modal Mode, add the data-apollos-modal="true" attribute to the script tag:

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
  data-apollos-modal="true"
></script>

### 4. Adding the Embed Divs Navigate to the design section of your Webflow site
and add a `div` element for each embed you plan to use. Currently supported
embeds include: - **Auth**: Handles user authentication. - **FeatureFeed**:
Displays curated content feeds. - **Search**: Enables search functionality with
optional profile modal customization. Each `div` should include the
`apollos-widget` class to activate the embed functionality. Example: ```html
<div class="apollos-widget" data-type="Auth" data-church="example_church"></div>
<div
  class="apollos-widget"
  data-type="FeatureFeed"
  data-church="example_church"
></div>
<div
  class="apollos-widget"
  data-type="Search"
  data-hide-apollos-auth="true"
  data-church="example_church"
  data-search-profile-size="365px"
></div>

5. Customizing Embeds with Attributes

Use data-attributes (or Custom Attributes in Webflow) to customize the behavior and appearance of each embed.

Example for a FeatureFeed embed:

<div
  class="apollos-widget"
  data-type="FeatureFeed"
  data-church="example_church"
  data-feature-feed="FeatureFeed:unique-id"
  data-modal="true"
></div>

6. Understanding Church Slugs

Church slugs uniquely identify the organization whose content is displayed. If you’re unsure of your slug, contact a developer or administrator.

!NOTE Replace [INSERT_CHURCH_SLUG_HERE] with your church's unique identifier (or slug). Contact a developer if you need assistance obtaining a church slug.

For Developers

Background

This package was originally part of the apollos-embeds repository and involved significant duplication of frontend code, components, and GraphQL queries. To unify our web frontend development, we created canvas-ui-web as a component library. The apollos-embeds project has been moved into this repository to coexist with our other web platforms.

The original version of web-embeds was heavily dependent on modal presentation. This new package retains selective use of modals while encouraging users to navigate to Apollos microsites, which run on New Web.

How It Works

Embeds are bundled as index.js and index.css in the /widget folder and distributed via jsDelivr. By including these on the webpage, users can access these embeds. Placing an apollos-widget div on the page triggers the web embed functionality.

Local Development

To work on this package locally, ensure you have a valid Feature Feed ID. Use index.html for testing with examples. Keep in mind that embeds from different churches on the same page may cause conflicts, so ensure you only use one church per page. You should be running apollos-cluster as well as this entire repo by running yarn dev.

Testing Embeds Locally

Use the index.html file for testing. Open http://localhost:5174 in your browser to view changes.

Example embed for testing:

<div
  data-type="FeatureFeed"
  data-church="apollos_demo"
  data-feature-feed="FeatureFeed:caf294f0-cd0e-4486-95e7-fa11bd5fb1c5"
  data-modal="true"
  class="apollos-widget"
></div>

To test changes, open http://localhost:5174 in your browser.

Caching

To test caching in local development, modify the Apollo client configuration by commenting out the x-cache-me-not header in:

src/client/apollosApiLink.js

'x-cache-me-not': 1,

jsDelivr Cache Busting

If you need to force jsDelivr to fetch the latest version of a file, you can manually purge the cache by accessing the purge subdomain of the file's URL. This command clears the cached version of the file from jsDelivr's CDN.

yarn flush

Advanced Configuration

Supported Embeds and Attributes

Path Routing

For advanced routing options, use:

• data-use-path-router="true" for enabling path-based routing.
• data-apollos-id-param="true" for custom ID handling.