Marfeel Docs

# Widgets Providers

Widget Providers are one of the tools you can use to extend the behavior of your Marfeel site. You can place a Widget in any of your sections or article pages with fully customizable functionality.

They are React components (opens new window) written in TypeScript (opens new window). React Functional Components + Hooks (opens new window) is the preferred type of React components to use.

The Widget Provider's architecture makes Marfeel Widgets safe and performant, optimized for SEO thanks to Server-Side rendering, and for AMP thanks to the use of dedicated AMP components. On the other hand, Widget Providers are not compatible with legacy tenants: they require XPLib to work in Marfeel.

Widget Providers are shared across all of Marfeel: each lives in its own GitHub repository, not coupled with a Media Group. This rule applies to any widget, including ones that appear very custom. Pooling all the widgets together rather having some isolated in Media Group repositories guarantees that all sites benefit from the same optimizations, regardless of when they were Marfeelized. There is only one Youtube Player Widget, for example.

What about customizations?

Whenever a widget requires information from the site to display (information from the HTML, or even obtained via JS), it must come from a middleware.

Middleware at Marfeel are the customization mechanism for all types of Providers.

An interactive playground (opens new window) lists and shows in action all the Widget Providers implemented at Marfeel.

Depending on your situation, read the appropriate article:

# Example Widget

This Hello World example gives you a quick overview of the Widget Providers' architecture and principles:

import React, { ReactElement } from 'react';
import styled from 'styled-components';

export interface HelloWorldProps {
  name?: string;
  textColor?: string;
}

interface TextProps {
  textColor: string;
}

const StyledText = styled.div<TextProps>`
  color: ${ (props): string => props.textColor };
`;

export default function HelloWorld = ({ textColor = 'black', name = 'world' }: HelloWorldProps): ReactElement {
  const text = `Hello ${ name }!`;

  return (
    <StyledText textColor={ textColor }>
      { text }
    </StyledText>
  );
};

Schemas

A schema will be auto-generated when you merge your PR, via github actions (check it in the 'actions' tab in the Media Group repository). The schema is taken from the props interface of the provider, so if you change them and merge again it will change the schema with it. This schema is published in the package and is required for the JSON validation to work properly when building a Media Group using the provider. So it's important that it's named correctly for it do be detected. The name of the props MUST be the same as the name of the provider, with -Props e.g. MyWidget => MyWidgetProps

This example shows you the main technical requirements:

  • Typescript
  • Styled components
  • React
  • JSX element

# Resources

If you are not comfortable with any of those techniques or libraries, check out the following resources:

From the official React documentation:

Recommended resources for video learners:

Finally:

← Create a Widget through an iframe →