How to use Widget Providers

Widget Providers can only be used with XPLib tenants. Make sure the useMarfeelXPAsALibrary flag in the features.json file of the tenant is set to true before attempting to use a Widget Provider.

WARNING

Widget providers are not compatible with Legacy tenants.

Additionally, in XPLib tenants, make sure the enableReact definition flag is set.

To use an existing widget provider in an XPLib tenant, follow the steps:

Clone the Media Group in your local environment with glue clone, pull the latest version of the master branch.
Run npm i to install or update all the existing dependencies of the Media Group.
Install the widget as a package dependency of the Media Group:

$ cd ~/Marfeel/THE MEDIA GROUP NAME
$ npm install @marfeel/widget-providers-hello-world

...
+ @marfeel/widget-providers-hello-world@1.0.1-snapshot.126
added 1 package from 1 contributor in 13.616s

The installation was successful if you can locate the package in the dependencies field in the Media Group's package.json file.

"dependencies": {
  "@marfeel/widget-providers-hello-world": "^1.0.1-snapshot.126",
  ...
}

Configure the widget in the widgets.json file.

For example:

{
  "widgets": [
    {
      "type": "provider",
      "id": "hello-world",
      "name": "widget-providers-hello-world",
      "selector": ".hello",
      "parameters": {
        "textColor": "cadetblue",
        "name": "Marfeel"
      }
    }
  ]
}

Each Widget comes with a Storybook which you can use to preview the Widget and see what options are available. The Storybook is available at the URL https://marfeel.github.io/PACKAGE_NAME/PACKAGE_NAME/. For example, you can find the Storybook for the widgets-providers-youtube-player at https://marfeel.github.io/widget-providers-youtube-player/widget-providers-youtube-player/.

Example of a Storybook

5a. To add the widget to a section page, add it to the right Layout Descriptor file.

{
  "name": "widgets/widget",
  "repetition": 1,
  "attr": {
    "id": "widget-providers-hello-world"
  }
}

5b. To use the widget in an article page, invalidate a page where the widget appears in Desktop.

TIP

Remember to add a selector in the widgets.json, to be able to detect the widget.

Build the scripts, including the widget with npm:

npm run build -- -v react

Invalidate the page where the widget should appear:

glue invalidate:section 0 # for the home section
glue invalidate:article https://example.com/health/some-article.html # for an article

Open the site in mobile view:

glue open

TIP

If the server returns a 500 response code, try removing the widget from the layout descriptor: if it works then, you didn't declare the widget well in the layout descriptor.

If it still fails, the problem is independent of the widget.

Find the widget with its ID:

Expected HTML:

<div data-mrf-component-id="hello-world" data-mrf-component-type="widget">
  <div class="sc-bdVaJa kyurPH">
    Hello Marfeel!
  </div>
</div>

If the page renders as expected there are 3 possibilities regarding the widget:

The widget shows as expected, like in the picture, you can see "Hello Marfeel!".
The div with the widget ID is present but empty: Try building with npm again, step 6.
The div is absent, but the ID exists in JSON scripts within the page: There is likely a problem with your layout definition. Make sure you are declaring the widget with all the right attributes, in the right layout descriptor.

Debugging

The widget's code in local pages is minified by default. Check out the Widget Providers debugging guide.

← Widgets via Jsp How to Create Widget Providers →

# How to use Widget Providers