Marfeel Docs

# Widgets in Layout Descriptor

Widgets are configurable in the Layout Descriptor. The widgets layouts extend the default Layout and Layout Attributes and adds new fields to easily configure our widgets.

Two different types of widgets can be in the layout descriptor, provider and 3pi widgets.

For Provider widgets, set the layout name to widgets/widget:

{
  "name": "widgets/widget"
}

For 3pi widgets, set the layout name to widgets/widget3pi:

{
  "name": "widgets/widget3pi"
}

Widgets and extraction

It is not necessary to extract any item via the WhiteCollar (or any other ripper) to define widgets in the layout descriptor.

Only use the WhiteCollar for 3pi widgets that have dynamic parameters.

# Provider Widget Attributes

Provider widgets have only 1 always mandatory attribute, the id.

# id

Required. It must match the widget id in the tenant's widgets.json.





 



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

TIP

In Provider widgets, all static and dynamic parameters must be defined in the tenants widgets.json: they cannot come from the WhiteCollar.

# 3pi Widget attributes

Besides the default Layout Attributes we have also:

# className

Type: String

Optional. A String with the class that you want to add in the HTML of the widget.




 



{
  "name": "widgets/widget3pi",
  "attr": {
    "className": "mrf-marfeelDocs-example"
  }
}

The class is appeneded to the wrapper of the widget:

<article class="mrf-3pi-widget mrf-widget mrf-marfeelDocs-example">
  ....
</article>

# src

Type: String

Required. The path of the widget's implementation, starting from the root of the mediagroup.





 



{
  "name": "widgets/widget3pi",
  "attr": {
    "className": "mrf-marfeelDocs-example",
    "src": "example.com/index/MarfeelDocsWidget.js"
  }
}

# selector

Type: String

Required. Selector matching the DOM element to transform into a 3pi Widget.

Example:






 



{
  "name": "widgets/widget3pi",
  "attr": {
    "className": "mrf-marfeelDocs-example",
    "src": "example.com/index/MarfeelDocsWidget.js",
    "selector": ".my-selector .something-goes-here"
  }
}

# width

Type: String

Optional. Custom width for widgets. Defaults to 100%.

Example:







 



{
  "name": "widgets/widget3pi",
  "attr": {
    "className": "mrf-marfeelDocs-example",
    "src": "example.com/index/MarfeelDocsWidget.js",
    "selector": ".my-selector .something-goes-here",
    "width": "100px"
  }
}

# height

Type: String

Optional. Custom height for widgets. Defaults to auto.

Example:








 



{
  "name": "widgets/widget3pi",
  "attr": {
    "className": "mrf-marfeelDocs-example",
    "src": "publisherId/index/MarfeelDocsWidget.js",
    "selector": ".my-selector .something-goes-here",
    "width": "100%",
    "height": "200px"
  }
}

# templateUrl

Type: String

Optional. Proxy Url for the widget.

Example:







 





{
  "name": "widgets/widget3pi",
  "attr": {
    "className": "mrf-marfeelDocs-example",
    "src": "publisherId/index/MarfeelDocsWidget.js",
    "selector": ".my-selector .something-goes-here",
    "templateUrl": "https://MY_PUBLISHER_ID/proxyTemplate.html",
    "width": "100%",
    "height": "200px"
  }
}

# iframeAttrs

Type: Object

Optional. Attributes that are added to the iframe node containing the 3pi widget.

Example:








 
 
 



{
  "name": "widgets/widget3pi",
  "attr": {
    "className": "mrf-marfeelDocs-example",
    "src": "example.com/index/MarfeelDocsWidget.js",
    "selector": ".my-selector .something-goes-here",
    "height": "200px",
    "iframeAttrs": {
      "allow": "autoplay"
    }
  }
}

# Parameters

It is possible to pass parameters to the 3pi widget logic layer, with the parameters attribute. Parameters can be static (i.e. always identical) or dynamic (i.e. vary depending on the HTML source).

# Static parameters

Type: Object

Optional. Parameters that should be passed to the 3pi widget logic.

Example:








 
 
 



{
  "name": "widgets/widget3pi",
  "attr": {
    "className": "mrf-marfeelDocs-example",
    "src": "publisherId/index/MarfeelDocsWidget.js",
    "selector": ".my-selector .something-goes-here",
    "height": "200px",
    "parameters": {
      "someVar": "someValue"
    }
  }
}

# Dynamic Parameters

Dynamic parameters must be set in the WhiteCollar, as it has access to the original HTML page. The WhiteCollar must find an item to select, from which it will extract the dynamic parameters.

Selected item

If no item is found by the WhiteCollar, no widget is rendered at all.

In practice, with a WhiteCollar containing:










 
 
 
 








return {
  getItems: [
  {
    selector: '.some-selector',
    extractors: {
      title: 'Something here',
      uri: 'a',
      pocket: function(node) {
        return {
          key: 'myTestWidget',
          widget3pi: {
            parameters: {
              fetchParams: node.dataset.canal
            }
          }
        };
      }
    }
  }]
};

The corresponding layout is:



 










{
  "layouts": [{
    "key": "myTestWidget",
    "name": "widgets/widget3pi",
    "attr": {
      "className": "mrf-test-widget",
      "selector": ".some-selector",
      "src": "example.com/index/TestWidget.js",
      "templateUrl": "https://www.example.com/proxyTemplate.html"
      }
  }]
}

Key or no key?

The key attribute for a 3pi widget is entirely optional. If the widget does not depend on anything in the HTML of the document, don't include it.

If you add a key, the widget only renders if the WhiteCollar detects content for that item.

← rawHTML →