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
});

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 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();

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 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'
  }

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 all files used 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.

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: ''
    }
  }

Returns boolean indicating whether the entry is currently muted.

Returns boolean indicating whether viewport orientation is currently portrait.

Returns a list of attributes (iconName, name and url) of all configured share providers of the entry. The url provides a %{url} 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}
    },
    {
      iconName: 'twitter',
      name: 'Twitter',
      url: https://x.com/intent/post?url=%{url}
    }
  ]

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 two additionals functions to control content element scroll lifecycle and editor commands: simulateScrollPosition and triggerEditorCommand.

const {getByRole, simulateScrollPosition, triggerEditorCommand} =
  renderInContentElement(<MyContentElement />, {
    seed: {...}
  });
simulateScrollPosition('near viewport');
triggerEditorCommand({type: 'HIGHLIGHT'});

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.

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)

// 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'
          }
        }
      }
    }
  ]
});