@bbc/psammead-social-embed

3.3.13 • Public • Published

psammead-social-embed - Known Vulnerabilities Dependency Status peerDependencies Status Storybook GitHub license npm version PRs Welcome

Description

The SocialEmbed component renders a rich social media embed for a number of supported providers or a fallback containing a link to the source content.

Supported providers

Name Value
Instagram instagram
Twitter twitter
YouTube youtube

Installation

npm install @bbc/psammead-social-embed --save

Props

Canonical

Argument Type Required Default Example
provider String Yes n/a See supported providers.
service String Yes n/a 'news'
oEmbed Object Yes n/a See @bbc/psammead-oembed.
fallback Object Yes n/a See fallback.
skipLink Object Yes n/a See skipLink.
caption Object No null See caption.
onRender Function No null () => console.log('rendered')

AMP

Argument Type Required Default Example
provider String Yes n/a See supported providers.
service String Yes n/a 'news'
id String Yes n/a '1237210910835392512'
fallback Object Yes n/a See fallback.
skipLink Object Yes n/a See skipLink.
caption Object No null See caption.

fallback

Argument Type Required Default Example
text String Yes n/a "Sorry but we're having trouble displaying this content"
linkText String Yes n/a 'View content on %provider_name%'
linkTextSuffixVisuallyHidden String No null ', external'
linkHref String Yes n/a 'https://twitter.com/MileyCyrus/status/1237210910835392512'
warningText String No null Warning: BBC is not responsible for third party content

skipLink

Argument Type Required Default Example
text String Yes n/a 'Skip %provider_name% content'
endTextId String Yes n/a 'skip-%provider%-content'
endTextVisuallyHidden String Yes n/a 'End of %provider_name% content'

caption

Argument Type Required Default Example
textPrefixVisuallyHidden String No null 'Video caption,'
text String Yes n/a 'Warning: Third party content may contain adverts'

See accessibility notes for more information.

Note: For your convenience, instances of %provider% and %provider_name% in fallback, skipLink and caption strings will be replaced with the current provider and, where the provider is known, the name of the provider. E.G. youtube and YouTube respectively.

Usage

Canonical

Pass a supported provider and valid oEmbed response. If neither of these cases can be met, a fallback will be rendered containing a link to the source content.

Example

import { CanonicalSocialEmbed } from '@bbc/psammead-social-embed';

<CanonicalSocialEmbed
  provider="instagram"
  service="news"
  oEmbed={{ html: '...' }}
  skipLink={{
    text: 'Skip %provider_name% content',
    endTextId: 'skip-%provider%-content',
    endTextVisuallyHidden: 'End of %provider_name% content',
  }}
  fallback={{
    text: "Sorry but we're having trouble displaying this content",
    linkText: 'View content on %provider_name%',
    linkTextSuffixVisuallyHidden: ', external',
    linkHref: 'https://www.instagram.com/p/B8FPf4ZphHi/',
    warningText: 'Warning: BBC is not responsible for third party content',
  }}
/>;

The component supports integration with the react-lazyload package ensuring the social media posts are rendered when they come into view.

Example

<LazyLoad height={200}>
  <CanonicalSocialEmbed provider="instagram" .../>
</LazyLoad>

onRender

This component takes an onRender prop which is invoked when the embed is fully rendered (currently only for twitter embeds), this can be used to change styling on render to help reduce layout shift.

Example

import React, { useState } from 'react';
import styled from '@emotion/styled';

const DEFAULT_MIN_HEIGHT = '18.75rem';

const Wrapper = styled.div`
  min-height: ${({ minHeight }) => minHeight};
`;

const SocialEmbedWithWrapper = ({
  provider,
  oEmbed,
  skipLink,
  fallback,
  service,
  }) => {

  const [wrapperMinHeight, setWrapperMinHeight] = useState(DEFAULT_MIN_HEIGHT);

  return (
    <Wrapper minHeight={wrapperMinHeight}>
      <CanonicalSocialEmbed
        provider={provider}
        oEmbed={oEmbed}
        skipLink={skipLink}
        fallback={fallback}
        service={service}
        onRender={() => {
          setMinHeight('0');
        }}
      />
    </Wrapper>
  );
};

export default SocialEmbedWithWrapper;

AMP

Pass a supported provider. If this case cannot be met, a fallback will be rendered containing a link to the source content.

Pass a valid id. This refers to the unique segment of the URL, which identifies the source content. E.G. 1237210910835392512 in https://twitter.com/MileyCyrus/status/1237210910835392512.

import { AmpSocialEmbed } from '@bbc/psammead-social-embed';

<AmpSocialEmbed
  provider="instagram"
  service="news"
  id="B8FPf4ZphHi"
  skipLink={{
    text: 'Skip %provider_name% content',
    endTextId: 'skip-%provider%-content',
    endTextVisuallyHidden: 'End of %provider_name% content',
  }}
  fallback={{
    text: "Sorry but we're having trouble displaying this content",
    linkText: 'View content on %provider_name%',
    linkTextSuffixVisuallyHidden: ', external',
    linkHref: 'https://www.instagram.com/p/B8FPf4ZphHi/',
    warningText: 'Warning: BBC is not responsible for third party content',
  }}
/>;

When to use this component

This component is designed to embed rich social media content from a number of supported providers in primary content, such as an article.

When not to use this component

This component will not provide a rich social media embed for providers outside of the supported providers – these will use fallback content instead.

Accessibility notes

This component provides a Skip Link, which allows users to identify and skip over social media content in your pages. skipLink.endTextId should be set to a value that uniquely identifies skipLink.endTextVisuallyHidden. This is especially important when there are more than one social media embeds from the same provider on a page.

fallback.linkTextSuffixVisuallyHidden is used to add a suffix to fallback.text. This will not be visible on the UI, but will be captured by assistive technology.

caption.textPrefixVisuallyHidden is used to add a prefix to caption.text. This will not be visible on the UI, but will be captured by assistive technology.

Miscellaneous

Some components within SocialEmbed render the same result given the same props and are memoized using React.memo to prevent unnecessary renders.

Contributing

Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at the root of the Psammead repository.

Code of Conduct

We welcome feedback and help on this work. By participating in this project, you agree to abide by the code of conduct. Please take a moment to read it.

License

Psammead is Apache 2.0 licensed.

Versions

Current Tags

VersionDownloads (Last 7 Days)Tag
3.3.133latest
2.0.0-alpha.01alpha

Version History

VersionDownloads (Last 7 Days)Published
3.3.133
3.3.121
3.3.111
3.3.101
3.3.91
3.3.81
3.3.71
3.3.61
3.3.51
3.3.41
3.3.31
3.3.21
3.3.11
3.3.01
3.2.11
3.2.01
3.1.161
3.1.151
3.1.141
3.1.131
3.1.121
3.1.111
3.1.101
3.1.91
3.1.81
3.1.71
3.1.61
3.1.51
3.1.41
3.1.31
3.1.21
3.1.11
3.1.01
3.0.31
3.0.21
3.0.11
3.0.01
2.0.31
2.0.21
2.0.11
2.0.0-alpha.01
1.1.121
1.1.111
1.1.101
1.1.91
1.1.81
1.1.71
1.1.61
1.1.51
1.1.41
1.1.31
1.1.21
1.1.11
1.1.02
1.0.21
1.0.11
1.0.01
0.1.0-alpha.41
0.1.0-alpha.31
0.1.0-alpha.21
0.1.0-alpha.11

Package Sidebar

Install

npm i @bbc/psammead-social-embed

Weekly Downloads

64

Version

3.3.13

License

Apache-2.0

Unpacked Size

189 kB

Total Files

37

Last publish

Collaborators

  • silver-jenkins
  • bbc-web-core
  • iplayer-web-jenkins
  • sport-web-jenkins
  • bbcconnections
  • bbc-gnl-ci
  • bbc-morph
  • itv-ci-machine
  • audienceplatformdev
  • bbc-archivesearch-development-team
  • sounds-web-jenkins
  • rmsdev
  • bbc-voice-pipeline
  • weather-jenkins
  • newslabs-jenkins
  • api-management-jenkins
  • mdtbuild
  • bbc-online
  • cps-support
  • bbc-cd-jenkins
  • locator-deploy
  • bbc-isite
  • participation-jenkins
  • bbc-news-jenkins
  • bbcrd
  • ibl
  • iplayerradio-aws
  • media-playout-jenkins
  • partner-platform-jenkins
  • bbc-admin
  • gel-jenkins
  • pcs-amp-jenkins
  • education-jenkins
  • insyn-jenkins
  • kite-jenkins
  • bbcrd-artifactory
  • iplayer-pc-downloads-pipeline-bot