Subscription widget

A subscription widget displays the details and contents of a subscription to a group or catalog.

Example:

Embedding

Assuming that the widget loader is included in the page, a subscription widget may be embedded as follows:

<div class="drl-widget drl-subscription" drl-code="VF5xLmEzQ9gv-5W9Bklrz5bJ24fSOBc_1eeH2m7Hc95" id="subscription"></div>

Attributes

Attribute	Description
`drl-code`	Represents the unique ID of the catalog or group.
`drl-token`	The user's OAuth token. In order to display a subscription widget, a valid access token is required. An OAuth token may be obtained by using a standard service account or by using the custom delegated login API.
`drl-search-disabled`	If set to `true`, suppresses the built in search functionality. Optional.

Localization

Currently the subscription widget supports the following languages:

🇪🇸 Catalan
🇩🇰 Danish
🇺🇸 English (US)
🇩🇪 German
🇪🇸 Spanish
🇫🇮 Finnish
🇫🇷 French
🇮🇹 Italian
🇳🇴 Norwegian
🇳🇱 Dutch
🇧🇷 Portuguese (BR)
🇷🇴 Romanian
🇷🇸 Serbian
🇸🇪 Swedish

A subscription widget's locale is determined as follows:

stored language preference – for authenticated users there may be a stored language preference
declared language of the containing page – the page that embeds the subscription may have declared a language in the html tag using a lang attribute
browser setting – there may be a preferred language set in the browser
English – in all cases where the language preference cannot be determined, US English is used

If the requested language is not supported, the subscription widget will use English (US). Additional localizations may be added in the future. If you require a specific localization that is not yet supported, please get in touch with us.

Client side events

The subscription widget is able to emit the following client-side events.

Event	Fired if	Payload
`INITIALIZED`	The subscription widget was initialized.	None
`INITIALIZATION_FAILED`	The subscription widget could not be initialized.	None
`CLICKED`	A subscription content item was clicked.	Playable object

Launching the player

An obvious use of the subscription widget is to allow the Player widget to be launched when the user clicks on any of the content tiles. As the subscription widget is a generic component, this is not the out-of-the-box behavior. However, with a little bit of glue logic this is easily achieved.

If a subscription content tile is clicked, a CLICKED event is emitted, including a reference to the object that was clicked. By listening to this event, and acting upon it, the appropriate player may be opened. Additionally, the same glue logic should also listen to a player's PLAYER_CLOSE event, and close the player widget.

The below code provides a working example of such an integration. Note that special care was taken to allow scrolling to work correctly in Mobile Safari.

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Subscription/Player widget integration example</title>
    <style>
      html,
      body,
      .drl-widget.drl-subscription {
          width: 100vw;
          height: 100vh;
      }

      body {
          margin: 0;
      }

      body.player-opened .drl-subscription {
          display: none;
      }

      .drl-widget.drl-player {
          position: fixed;
          top: -100%;
          left: 0;
          width: 100vw;
          height: 100%;
          transition: top .5s ease-in-out;
          overflow:auto;
          -webkit-overflow-scrolling:touch;
      }

      .drl-player iframe {
          width:100%;
          height:100%;
      }

      .drl-widget.drl-player.drl-visible {
          top: 0;
      }
    </style>
</head>
<body>
    <div class="drl-widget drl-subscription"
        drl-code="{subscription ID}"
        id="subscription"
        autoload="false"
    ></div>
    <div class="drl-widget drl-player"
        id="subscription-player"
        drl-allow-full-screen="true"
        drl-can-close="true"
        drl-auto-focus="true"
        autoload="false"
    ></div>

    <script type="text/javascript">
      (function () {
          'use strict';

          // Programatically put the end user's OAuth token here
          var token = 'secret123';

          drillster.widgets('subscription').load(token);

          document.addEventListener('DOMContentLoaded', function () {
              var player = document.querySelector('.drl-widget.drl-player');

              drillster.widgets('subscription').on('CLICKED', function (event) {
                  console.log('Playable clicked:', event);
                  player.setAttribute('drl-code', event.data.playable.id);
                  drillster.widgets('subscription-player').load(token);
                  player.classList.add('drl-visible');
              });

              drillster.widgets('subscription-player').on('PLAYER_CLOSE', function (event) {
                  console.log('Player closed:', event);
                  player.classList.remove('drl-visible');
                  player.innerHTML = '';
                  player.removeAttribute('data-loaded');
              });
          });
      })();
    </script>
    <script src="https://www.drillster.com/widgets/loader.js" type="text/javascript"></script>
</body>
</html>

Last updated on 2024-10-02