JS SDK

Usage

There are several ways to employ the Sphere library, depending on placement needs, app style, and ops setup. The simplest usage involves a drop-in <script> tag that only needs an API key to be specified. More dynamic pages can use the library directly, for specific handling of the DOM elements. Fully dynamic, React-based apps can use the components to integrate Sphere recommendation components.

1. Drop-in, placing the script tag where the Recommendations should be loaded:

   <script id                      = "sphere_recommendations"
           src                     = "/path/to/sphere.bundle.js"
           data-api_key            = "{{ YOUR API KEY HERE }}"
           async defer
   ></script>

   A Placement will be created at the spot in the document where the <script> tag is located. data- attributes are used to pass configuration to the library. Replace {{ YOUR API KEY HERE }} with the API key assigned to your publication. The tag MUST have the id of "sphere_recommendations". The script will be loaded asynchronously and will not block rendering of the rest of the document.

   Once the script has loaded, it will fetch a set of recommendations from the Sphere API, by default up to three, and insert them into the page.

2. Semi-dynamic, loading the script with a module system:

   This method requires one or more target containers already present in the DOM.

   The library can be required like other modules:

   var Sphere = require('sphere-sdk');

   When ready, call Sphere.init with the appropriate configuration (same as the drop-in but without the data- prefix):

   Sphere.init({
      api_key      : '<api_key>',
      num_units    : 3,                        // Number of Recommendation Units _per Placement_.
      target       : '.recommended-content'    // Selector matching Placement containers.
   });

3. Dynamic, fully client-side React (or isomorphic):

   At some point during client-side app startup, the Sphere stores and API client MUST be initialized:

   var Sphere = require('sphere-sdk');
   Sphere.init({ ... configuration ... });

   The <SpherePlacement> component is used to place the recommendations into the document.

   var SpherePlacement = require('@marquee/sphere/components/SpherePlacement');

   Within the render method of the appropriate containing element:

   <SpherePlacement num_units=4 grid=2 />

   The <SpherePlacement> component will render Recommendation Units when they are loaded from the Sphere API. This is the same component as is used for server-side rendering, but now that it is in the client it can proceed with the loading and rendering of recommendations.

Configuration

In addition to images and titles, the recommendations can include descriptions, site and category labels, and user actions. By default these features are all enabled, but their presence, positioning, and even look-and-feel can be controlled through configuration on the #sphere_recommendations script tag using data- attributes. Many of these options are constrained by the Sphere Style Guide.

An example fully-configured Sphere tag:

<script
    id                              = "sphere_recommendations"
    src                             = "../dist/sphere.bundle.js"
    data-sphere_api_key             = "{{ YOUR API KEY HERE }}"
    data-sandbox                    = "false"
    data-accent_color               = "#C20000"
    data-grid                       = "2"
    data-num_units                  = "4"
    data-unit_description           = "false"
    data-unit_engage_position       = "below"
    data-unit_engage_reveal         = "hover"
    data-unit_interests             = "true"
    data-unit_interest_bar          = "solid"
    data-unit_interest_separator    = "true"
    data-unit_layout                = "horizontal"
    async defer
></script>

The full list of configuration options and their defaults:

• data-accent_color

  Controls the hover and active state colors of the Engage Bar and Interest buttons.

  Default: "#00cc99" Accepts: Any CSS color string

  Note: in-page CSS can override this setting.

• data-grid

  The number of Recommendation units to show horizontally. Only takes effect when the horizontal space available is above 640px.

  Default: "3" Accepts: "1", "2", "3", "4"

• data-max_width

  Constrains the placement width to the px value specified. The placement is responsive and will automatically adjust to the available width. The preferred way to control sizing and position is with the parent container, but this option is available if that is not possible.

  Default: "null" Accepts: "1", "2", "3",…

• data-num_units

  The number of Recommendations to load. For best results, set as a multiple of the grid option.

  Default: "3" Accepts: "1", "2", "3", …, "8"

  Note: this is a maximum; the Sphere API may occasionally return fewer Recommendations.

• data-powered_by

  When "true", displays a “Powered by Sphere” graphic and link underneath the Recommendations.

  Default: "true" Accepts: "true", "false"

• data-sandbox

  When "true", uses the development version of the Sphere API. Make sure to use the correct API key.

  Default: "false" Accepts: "true", "false"

• data-unit_description

  When "true", shows a brief description of the Recommendation inside each recommendation unit.

  Default: "true" Accepts: "true", "false"

• data-unit_engage_position

  Controls the position of the Engage Bar. It can be above the headline, below, or over the bottom of the image.

  Default: "below" Accepts: "above", "below", "image"

• data-unit_engage_reveal

  Controls the behavior of displaying the Engage Bar. "click" displays an ellipsis button that reveals the bar on click. "hover" will show the bar when the Recommendation unit is hovered over by the user.

  Default: "click" Accepts: "click", "hover"

  Note: hover behavior only happens on non-mobile devices. Mobile will still use the click/tap behavior.

• data-unit_interests

  When "true", shows the site and category Interest bars inside the Recommendation unit. These bars have controls for users to indicate their interest in the category or source site of the Recommendation.

  Default: "true" Accepts: "true", "false"

• data-unit_interest_bar

  Controls the style of the site and category Interest bars. "null" shows a bare text bar. "outline" adds a stroke, and "solid" adds a background color.

  Default: "null" Accepts: "null", "outline", "solid"

• data-unit_interest_separator

  When "true", adds a vertical separating stroke between the Interest name and the “Add to Interests” button.

  Default: "false" Accepts: "true", "false"

• data-unit_layout

  Controls the layout of the individual Recommendation units. "vertical" keeps the image above the title, description, and interests. "horizontal" places the image to the left.

  Default: "vertical" Accepts: "vertical", "horizontal"

Styling

In addition to the above configuration, look-and-feel styles such as fonts and colors can be controlled using CSS. The default stylesheet is added before any site-loaded sheets, allowing them to take precedence.

By default, the Recommendation units will inherit the site’s font sizes and colors. Also, the icons used by the buttons are provided by a font, and will accept any CSS color applied to the button.

For example, the button colors can be controlled using the following rule:

.sphere_Button {
    color: #a2a2a2;
}

The default stylesheet:

.sphere_Button {
    color: #aaaaaa;
}
.sphere_Button.-sphere_color--light {
    color: #efefef;
}
.sphere_Button.-sphere_color--dark:hover {
    color: #00cc99;
}
.sphere_Button.-sphere_color--light:hover {
    color: #00cc99;
}
.sphere_Button[data-selected="true"],
.sphere_Button.-sphere_color--light:active,
.sphere_Button.-sphere_color--dark:active {
    color: #00cc99;
}
.sphere_Recommendation_Link {
    color: inherit;
    text-decoration: none;
}
.sphere_UserActions {
    font-size: 20px;
}
.sphere_Interest {
    height: 1.5em;
}
.sphere_Interest.-sphere_bar--outline {
    border-width: 2px;
    border-color: #aaaaaa;
}
.sphere_Interest.-sphere_bar--solid {
    background-color: #aaaaaa;
    color: #efefef;
}
.sphere_Interest.-sphere_separator .sphere_Interest_Name {
    border-right-width: 1px;
}
.sphere_Interest.-sphere_bar--solid.-sphere_separator .sphere_Interest_Name {
    border-right-width: 2px;
}
.sphere_Recommendation.-sphere_layout--horizontal .sphere_Recommendation_Title {
    font-size: 1em;
}

Developing

nvm use npm install npm run build npm run clearbuild

If you get an error like ReferenceError: Promise is not defined, make sure you are using node 0.12 or higher, preferably 4.x. nvm is recommended.