(dev/core#2994) oEmbed - Basic protocol support (*incubation*)

[totten]

Overview

oEmbed is a protocol for sharing HTML snippets across different sites.

This PR adds initial support for CiviCRM to provide embeddable content on external websites. However, the mechanism is somewhat experimental. Consequently, it is implemented as a hidden extension (oembed).

See also: https://lab.civicrm.org/dev/core/-/issues/2994

Technical Details

The standard protocol works like this:

• Browse to a page that is interesting. Copy the URL. For example:

  https://www.youtube.com/watch?v=XXXXXX-XXXX`
  

• Open your favorite web-editor/CMS.

• Paste-in the URL (or add an "Embed" widget... and paste-in the URL).

• The web-editor/CMS performs a lookup via oEmbed, which returns a new snippet of HTML, eg

  <iframe width="200" height="113" frameborder="0"
    src="https://www.youtube.com/embed/XXXXXX-XXXX?feature=oembed"
    ...>

  This snippet is basically the same content, but it's reformatted to fit into an external web-page.

oEmbed and <iframe> are technically different things. (Each mechanism can exist without the other.) But there appears to be a symbiosis -- if you want to embed content with interactivity/scripts/styles/forms, then the odds of getting through seem better with <iframe>s. Hence, the oembed extension builds on the iframe extension. (*In this impelmentation, pages will get oEmbed features if-and-only-if they have <iframe> support enabled per #29496.)

After enabling the oembed extension, this settings page becomes available.

Screenshot: Administer: oEmbed Settings

With the first option ("Auto Discovery") enabled, pages support the ordinary oEmbed pageflow -- and any visitor can use it. With the second option ("Explict Sharing"), you get more control over who/how of sharing. This panel becomes available to users with suitable permissions:

Screenshot: Cross-Site Sharing Panel

There are a few reasons for regarding this as an incubating/experimental extension:

• We need to test compatibility in more real-world scenarios with different content-consuming systems.
• The layout/styling of the panel should be tweaked.
• The panel should be further enhanced based on future theming work (re:configurability).

[civibot]

🤖 Thank you for contributing to CiviCRM! ❤️ We will need to test and review this PR. 👷

Introduction for new contributors...

• If this is your first PR, an admin will greenlight automated testing with the command ok to test or add to whitelist.
• A series of tests will automatically run. You can see the results at the bottom of this page (if there are any problems, it will include a link to see what went wrong).
• A demo site will be built where anyone can try out a version of CiviCRM that includes your changes.
• If this process needs to be repeated, an admin will issue the command test this please to rerun tests and build a new demo site.
• Before this PR can be merged, it needs to be reviewed. Please keep in mind that reviewers are volunteers, and their response time can vary from a few hours to a few weeks depending on their availability and their knowledge of this particular part of CiviCRM.
• A great way to speed up this process is to "trade reviews" with someone - find an open PR that you feel able to review, and leave a comment like "I'm reviewing this now, could you please review mine?" (include a link to yours). You don't have to wait for a response to get started (and you don't have to stop at one!) the more you review, the faster this process goes for everyone 😄
• To ensure that you are credited properly in the final release notes, please add yourself to contributor-key.yml
• For more information about contributing, see CONTRIBUTING.md.

Quick links for reviewers...

• ➡️ PR Demo site (can be rebuilt with the command test this please).
• 📖 Review standards
• 🗒️ Review template (brief or verbose)

➡️ Online demo of this PR 🔗

[totten]

@seamuslee001 This should be a bit more interesting to test:

• Rebased after the merge of the iframe PR.
• Added your two fixes
• Did a cleanup on the share-style URL formatting (so that it's more distinct from main oEmbed callback)
• Added an option ("oEmbed Standard Discovery". This enables oEmbed discovery based on the regular URL of the page.
• Added an option ("oEmbed Explicit Sharing"). This gives admins a panel where they can see some snippets for other ways to share.
  • It looks ugly. But IMHO it's more important to ensure the flows are working and give clearer testing options. Then later figure how to make it nice.
• Expose the options in "Administer > System Settings > oEmbed Settings"

[JoeMurray]

Another newbie question: what does AE mean or do in this context?

[totten]

A directive can be activated based on HTML (a)ttributes (<div crm-oembed-sharing> or HTML (e)lements (<crm-oembed-sharing />) or HTML (c)lasses (<div class="crm-oembed-sharing">).

The exports and restrict both speak to this. It's the same "A". Slightly different angles:

• The exports is more of a build-instruction/dependency-info. If somebody else wants to usecrm-oembed-sharing, then we should autoload the module.
• The restrict is a runtime thing -- it tells the browser how to target things at run time (eg how to use DOM selectors).

This mismatch between them (exports=A, restrict:AE) is a latent bug.

[JoeMurray]

Just confirming that frontend://civicrm/share is something that gets maps to a different URL depending on the User Framework/CMS of the producer site, and also allows different entry points for each, specifically WordPress which cannot have a url/route be mapped to file system location at top level within docroot if we are to comply with WP software policies.

[totten]

@JoeMurray, yeah frontend://civicrm/share is an ordinary frontend route -- going through the normal CRM_Core_Invoke, CRM_Core_Menu, civicrm_invoke(), etc. It's just a stub.

• It can convey extra params like ?maxwidth and ?maxheight.
• If you paste into an oEmbed client, then it's replaced by the <iframe>.
• If you open it manually, then it redirects to the real page.