Register new types of content elements.

// frontend.js

import {frontend} from 'pageflow-scrolled/frontend';
import {InlineImage} from './InlineImage';

frontend.contentElementTypes.register('inlineImage', {
  component: InlineImage
});

Register new types of widgets.

// frontend.js

import {frontend} from 'pageflow-scrolled/frontend';
import {CustomNavigationBar} from './CustomNavigationBar';

frontend.contentElementTypes.register('customNavigationBar', {
  component: CustomNavigationBar
});

Custom error boundary component to wrap content elements. Allows integration with error monitoring tools. The component receives typeName (string), configuration (object), fallback (function returning default UI), and children (content element).

Type: React.Component

Integrate new content types into the editor.

// editor.js
editor.contentElementTypes.register('inlineImage', {
  supportedWidthRange: ['xss', 'full'],

  configurationEditor() {
    this.tab('general', function() {
      this.input('caption', TextInputView);
    });
  }
});

Render one of the EU icons for labelling AI generated content.

Render audio file in MediaPlayer.

Wrap content element that render a visible box in this component to apply theme specific styles like rounded corners.

Render a figure with a caption text attached.

Render a div with the given aspect ratio which does not exceed the heigth of the viewport by setting an appropriate max-width on the container.

Wrap content in FitViewport.Content element:

Render an image file.

Render some text using the default typography scale.

Render an SVG icon that can be customized in themes.

Render opt in prompt instead of children if third party consent cookie has been configured in theme options and user has not given consent for passed provider.

Display info tooltip with a link to opt out of third party embeds. Opt out url needs to be configured in theme options.

Render video file in MediaPlayer.

Returns data generated by a Ruby lambda registered server side via config.additional_frontend_seed_data.register.

const data = useAdditionalSeedData('someSeed');

Prevent parallel playback of multiple media elements.

Use inside a content element component to determine whether the component is being rendered inside the editor iframe, and whether the content element is currently selected. This can be used to implement simple inline editing capabilities like displaying extra information when the content element is selected.

const {isEditable, isSelected} = useContentElementEditorState();

Returns an object containing information about the scroll position related lifecylce of the content element. Requires the lifecycle option to be set to true in the frontend.contentElements.register call for the content element's type.

• shouldLoad is true if the content element should start lazy load. Becomes true before shouldPrepare.

• shouldPrepare is true if the content element is about to enter the viewport.

• isActive is true if the content element is completely in the viewport.

const {isActive, shouldPrepare} = useContentElementLifecycle();

Invokes a callback with the progress of the content element along a range of its view timeline. Mirrors the concepts of CSS scroll driven animations: The content element acts as the subject of a view timeline of the page's scroll container. Requires the viewTimeline option to be set to true in the frontend.contentElementTypes.register call for the content element's type.

Progress is passed to a callback instead of being returned to prevent rerendering the content element on every scroll frame.

useContentElementViewTimelineProgress({
  range: 'cover',
  onProgress: progress => player.seekTo(progress)
});

Returns chapter containing the current scroll position.

const chapter = useCurrentChapter();
chapter // =>
 {
   id: 3,
   permaId: 5,
   title: 'Chapter 1',
   summary: 'An introductory chapter',
   chapterSlug: 'chapter-1'
 }

Returns the credits string (rich text) of the entry.

const credits = useCredits();
credits // => "Credits: <a href="http://pageflow.com">pageflow.com</a>"

Use to invert elements depending on whether they are rendered on a dark or light background to ensure correct display in inverted sections or in sections with card appearance.

Returns boolean indicating whether dark variant has been activated for the widgets of the entry.

Returns a nested data structure representing the metadata of the entry.

const metaData = useEntryMetadata();
metaData // =>
  {
    id: 5,
    locale: 'en',
    shareProviders: {email: false, facebook: true},
    share_url: 'http://test.host/test',
    credits: 'Credits: Pageflow',
    configuration: {darkWidgets: true}
  }

Look up a file by its collection and perma id.

const imageFile = useFile({collectionName: 'imageFiles', permaId: 5});
imageFile // =>
  {
    id: 102,
    permaId: 5,
    width: 1000,
    height: 500,
    urls: {
      large: 'https://...'
    },
    configuration: {
      alt: '...'
    }
  }

Returns a collection of rights and source urls of the files referenced in the entry. If none of the files has a rights attribute configured, it falls back to the default file rights of the entry's site, otherwise returns an empty array.

Lists all files of the entry unless the file_rights_from_references feature is enabled, since schemas do not cover all content element types yet.

const fileRights = useFileRights();
fileRights // => [{text: 'author of image 1', urls: ['https://example.com/source-url']}]

Use translations in frontend elements. Uses the configured locale of the current entry by default. Note that only translation keys from the pageflow_scrolled.public scope are universally available.

to render translations for inline editing controls in the editor preview, you can pass "ui" as locale option and use translations from the pageflow_scrolled.inline_editing scope.

const {t} = useI18n();
t('pageflow_scrolled.public.some.key')

const {t} = useI18n({locale: 'ui'});
t('pageflow_scrolled.inline_editing.some.key')

Use inside a content element component to determine whether the component is being rendered in a static preview, e.g. editor thumbnails.

const isStaticPreview = useIsStaticPreview();

Returns a nested data structure representing the legal info of the entry. Each legal info is separated into label and url to use in links. Both label and url can be blank, depending on the configuration.

const legalInfo = useLegalInfo();
legalInfo // =>
  {
    imprint: {
      label: '',
      url: ''
    },
    copyright: {
      label: '',
      url: ''
    },
    privacy: {
      label: '',
      url: ''
    }
  }

Obtain a locale to translate or format data in. Returns the configured locale of the current entry by default.

Elements that are rendered on top of the entry in the editor preview or while reviewing an entry are part of the user interface rather than of the entry itself. Pass "ui" as locale option to obtain the locale of the user interface for those.

const locale = useLocale();
date.toLocaleDateString(locale)

const locale = useLocale({locale: 'ui'});

Returns boolean indicating whether the entry is currently muted.

Returns boolean indicating whether viewport orientation is currently portrait.

Returns the privacy link URL, label and link props. When vendors are passed, the vendors query parameter and consent hash are appended to the URL. Handles absolute, protocol-relative and relative URLs.

const {url, label, props} = usePrivacyLink({vendors: 'youtube'});
// props => {href: '...', target: '_blank', rel: 'noreferrer noopener'}

Returns a list of attributes (iconName, name and url) of all configured share providers of the entry. The url provides a %s placeholder where the link can be inserted. iconName can be passed to ThemeIcon to render a theme specific icon.

const shareProviders = useShareProviders(options);
shareProviders // =>
  [
    {
      iconName: 'facebook',
      name: 'Facebook',
      url: http://www.facebook.com/sharer/sharer.php?u=%<url>s
    },
    {
      iconName: 'twitter',
      name: 'Twitter',
      url: https://x.com/intent/post?url=%<url>s
    }
  ]

Returns the share url of the entry.

const shareUrl = useShareUrl();
shareUrl // => "http://test.host/test"

Returns an object containing theme asset paths.

const theme = useTheme();
theme // =>
  {
    assets: {
      logoDesktop: 'path/to/logoDesktop.svg',
      logoMobile: 'path/to/logoMobile.svg'
    },
    options: {
      // options passed to `themes.register` in `pageflow.rb` initializer
      // with camleized keys.
    }
  }

Resolve a palette color to a CSS custom property.

<div style={{backgroundColor: paletteColor(configuration.backgroundColor)}}>

Construct data structure that resembles seed generated by server side JBuilder templates.

Render a component that depends on entry state. Accepts all options supported by render of @testing-library/react.

The seed option can be used to simulate rendering the component in the published entry. Data passed in this option would normally be rendered in a server side JBuilder template.

The setup option can be used to simulate rendering the component in the editor where data is synchronized from Backbone models.

To be able to render components that expect the result of certain hooks as part of their props, instead of a React component, you can pass a function returning a React component as first parameter. The function will be evaluated in a context of a React component and can thus make use of hooks

// DOES NOT WORK
renderInEntry(<Image file={useFile({collectionName: 'imageFiles', permaId: 4})} />, {seed});

// WORKS
renderInEntry(() => <Image file={useFile({collectionName: 'imageFiles', permaId: 4})} />, {seed});

When using the rerender function from the result, you again need to use the same type of parameter you passed to the original renderInEntry call.

Provide context as if component was rendered inside of a content element.

Returns additional functions to control content element scroll lifecycle, view timeline progress, editor commands, and storyline mode: simulateScrollPosition, simulateScrollProgress, triggerEditorCommand, and simulateStorylineMode.

simulateScrollProgress passes the given progress to all useContentElementViewTimelineProgress callbacks, no matter which range they observe. Pass a range option to only invoke callbacks observing that range.

const {getByRole, simulateScrollPosition, triggerEditorCommand, simulateStorylineMode} =
  renderInContentElement(<MyContentElement />, {
    seed: {...},
    inlineEditing: {isSelected: true}
  });
simulateScrollPosition('near viewport');
simulateScrollProgress(0.5);
simulateScrollProgress(0.5, {range: 'pinned'});
triggerEditorCommand({type: 'HIGHLIGHT'});
simulateStorylineMode('background');

Takes the same options as renderInEntry but returns additional helper function to the return value of the `useContentElementLifecycle` hook:

const {simulateScrollPosition} = renderInEntry(...)
simulateScrollPosition('near viewport')
// => Turns `shouldLoad` and `shouldPrepare` to true

Render a hook that depends on entry state. Accepts all options supported by renderHook of @testing-library/react-hooks

Can be used to test selector hooks which extract information from the entry state.

Register the public content element matchers for the surrounding describe block: toContainContentElementBox and toContainFitViewport.

Call inside a describe block. Content element plugins can use this to assert that their component opts into the framework chrome correctly.

import {renderInContentElement, useContentElementMatchers} from 'pageflow-scrolled/testHelpers';

describe('MyContentElement', () => {
  useContentElementMatchers();

  it('renders inside a box', () => {
    const {container} = renderInContentElement(<MyContentElement />);
    expect(container).toContainContentElementBox();
  });
});

Assert that the subject contains a ContentElementBox and, optionally, that the box has specific theme styles applied. Registered via useContentElementMatchers.

The subject is a DOM element, e.g. the container returned by renderInContentElement. Negate with .not to assert that no box is present.

expect(container).toContainContentElementBox();
expect(container).toContainContentElementBox({borderRadius: 'circle', boxShadow: 'md'});
expect(container).not.toContainContentElementBox();

Assert that the subject contains a FitViewport and, optionally, that it has a specific aspect ratio. Registered via useContentElementMatchers.

The subject is a DOM element, e.g. the container returned by renderInContentElement. Negate with .not to assert that no FitViewport is present.

expect(container).toContainFitViewport();
expect(container).toContainFitViewport({aspectRatio: 'square'});

Render the configuration editor of a content element. Content element packs can use this to assert how their editor integration behaves.

import {renderContentElementConfigurationEditor} from 'pageflow-scrolled/testHelpers';

Register the configuration editor matchers for the surrounding describe block: toRenderInputsMatching.

Call inside a describe block. Content element plugins can use this to assert that their configuration schema keeps up with their editor integration.

import {
  renderContentElementConfigurationEditor, useConfigurationEditorMatchers
} from 'pageflow-scrolled/testHelpers';

describe('myContentElement/editor', () => {
  useConfigurationEditorMatchers();

  it('renders inputs described by schema', () => {
    expect(() => renderContentElementConfigurationEditor({entry, contentElement}))
      .toRenderInputsMatching(schema);
  });
});

Assert that all inputs rendered by a configuration editor are described by a configuration schema. Registered via useConfigurationEditorMatchers.

The subject is a function that renders the configuration editor. Only inputs of the rendered form are seen. Views on nested routes render a form of their own and are checked against the part of the schema that describes the object they configure.

expect(() => renderContentElementConfigurationEditor({entry, contentElement}))
  .toRenderInputsMatching(require('./schema.json'));

expect(() => renderBackboneView(new SidebarEditAreaView(options)))
  .toRenderInputsMatching(require('../schema.json'), {path: ['areas', '*']});

When generating a .storybook/seed.json via the pageflow_scrolled:storybook:seed:setup Rake task, a couple of examples files are created. This method allows getting the perma id of one of those files from one of the following reference names:

• "turtle" (image)
• "interview_toni" (video)
• "quicktime_jingle" (audio)
• "lottieAnimation" (lottie)

// inlineImage/stories.js

import './frontend';
import {storiesOfContentElement, filePermaId} from 'pageflow-scrolled/spec/support/stories';

storiesOfContentElement(module, {
  typeName: 'inlineImage',
  baseConfiguration: {id: filePermaId('imageFiles', 'turtle')}
});

Add default set of stories for content element to render it in different settings (e.g. different section layouts).

// heading/stories.js

import './frontend';
import {storiesOfContentElement, filePermaId} from 'pageflow-scrolled/spec/support/stories';

storiesOfContentElement(module, {
  typeName: 'heading',
  baseConfiguration: {
    text: 'Some Heading'
  },
  variants: [
    {
      name: 'Large',
      configuration: {size: 'large'},
      themeOptions: {
        properties: {
          root: {
            accentColor: '#0f0'
          }
        }
      }
    }
  ]
});