Skip to main content
Skip table of contents

Publication Widget

Document version 4.3.5

Overview

This article describes the integration process of the Publication Widget provided by the Popsell platform. This widget is intended to display Popsell contents on an external website (brand and member publications) and enable some interactions (zoom, comment, like …)

This widget can be displayed in two different ways:

Stack mode

Each publication card adapts to the size of its content, to avoid image cropping as much as possible.

The “Stack mode” adapts to the screen: from 1 to several columns, depending on the width of the screen. Typically, on a mobile screen, this widget will appear in a single column, just like a social feed.

A “Load more” button can be displayed.

Widget displayed with stacked publications

Slider mode

The Slider mode will display cards with the same height, horizontally, and enabling to scroll them horizontally.

On a mobile, one card will be visible, plus a cut-off of the second image

Widget displayed as a slider

Filters

The publications displayed in the widgets can be filtered through 3 different parameters :

  • Products : allows to display only the publications to which a specific product is attached

  • Categories : allows to display only the publications to which a product of a specific category is attached

  • #Hashtags : allows to displays publications in which the author has added a specific hashtag

These filters can accept several values and be combined (logical operator "OR").

Publications linked to specific Products ID are returned in first position.

Prerequisites

The use of this widget is subject to certain prerequisites:

  • Installation of the Popsell Boostrapper. Please refer to Popsell Bootstrapper Tag [Prerequisite]

  • This widget needs the Session widget to be enabled. See Session Tag
    It will be used to retrieve informations such as guest / user Api keys.

  • To display the ambassador's posts, you must have an API key to authenticate the requests as this one. If you do not have one or if you wish to provide a list of public posts, you will need a guest API key (limited features).

If you do not meet the above requirements, you will not be able to use the widget properly.

If you need assistance with the validation of the prerequisites, you can contact our tech team at the following address: tech@popsell.com.

How it works

The widget is developed as a Vue.JS plugin. No dependency management is required, and its installation is as simple as possible.

Customization of the widget is possible by simply overlaying the generated CSS, all classes are named so as not to impact the rest of your application.

Tag

HTML
<popsell-publications></popsell-publications>

Attributes

attribute

type / default value

description

mandatory

guest-api-key

String

Needed to authenticate the requests.

only if no other API key is provided (in this widget or in the session widget)

user-api-key

String

Needed to authenticate the requests.

only if no other API key is provided (in this widget or in the session widget)

mode

String

default: slider

Sets the display mode :

slider
stack

false

display-likes

Boolean

default: true

Displays Likes on each post. (slider/page mode)

false

display-comments

Boolean

default: true

Displays comments on each post. (slider/page mode)

Displays comments on the each post detail.

false

limit

Number

default: 15

Sets the number of posts displayed on slider mode.

On page mode, it sets the number of posts fetched on each ‘load more’ request.

false

product-filter

String

Sets a filter based on one or several products IDs (comma separated list)

false

category-filter

String

Sets a filter based on one or several product category IDs (comma separated list)

false

hashtag-filter

String

Sets a filter based on one or several Hashtags (comma separated list)

*** Not yet implemented in current version ***

false

card-height

Number

default: 314

Define the card height in pixels. The slider mode automatically keep 9/16 aspects ratio of the card.

false

Integration example

HTML
<popsell-publications
      guest-api-key="guestApiKey"
      user-api-key="userApiKey"
      mode="stack"
      display-comments="true"
      display-likes="true"
      limit="30"
      product-filter="REF123"
      category-filter="C3522,C5677"
      hashtag-filter="#watch"
></popsell-publications>

Adding a custom Title and/or Footer

If needed, a custom HTML section can be added before and/or after the Widget content.
These sections will only be displayed if at least one publication is displayed in the Widget. In other words, this will prevent having a Title being displayed when the widget is empty.

The title object must contain a slot attribute "popsell-publications-title" to be displayed above the Widget, and the footer must contain a slot attribute "popsell-publications-footer" to be displayed below.

The CSS must be embedded in a <style> tag, because the style of the parent cannot be applied inside the component. The parent’s CSS file can be imported, as in the example below.

HTML
<popsell-publications>
    <style slot="popsell-publications-style">@import url("https://site-example/style.css")</style>
    <h1 slot="popsell-publications-title">Title example</h1>
    <p slot="popsell-publications-footer">Footer paragraph example</p>
</popsell-publications>

Be sure to scope your style with CSS selectors. Styling is not applied from host to component, but is applied from component to host !

About Flash Of Unstyled Content (FOUC)

Flash of unstyled content (fouc) may occur whether the user network is slow or the user computer is limited. In order to avoid this kind of behavior, we strongly recommand to add some CSS Code in your stylesheets.

A tag can be styled and behave exactly as a html tag. Combined with :not and :defined attributes, we can easily hide a tag when the content is not ready yet.

CSS
popsell-publications:not(:defined) {
  display: none;
}

The widget will automatically appears when it will be ready and the component hydrated.

Hooks

Events system

Popsell allows you to hook certain parts of the application in order to track user events. For example, when a user clicks on some buttons, you’ll be able to know which button has been clicked and from which context. It is particularly useful if you plan to link systems like Google Analytics.

Available Community tag events

Our tags use the power of web-components and are fully compatible with native Javascript event bus.

In order to hook an event, just plug the listener as you would usually do in a normal Javascript environment.

 

CODE
document.querySelector('popsell-community').addEventListener(<event type>, (event) => {
  //event.detail[0] contains all popsell informations you would need
});

Hook

Event Type

Element

Action

Data

Click on a post

interact

zoom_post

click

JS
undefined

Open a product linked to a post

navigate

open_product

open

JS
undefined

Sign in in order to be able to like or comment a post

navigate

button_sign_in

open

JS
undefined

Sign up in order to be able to like or comment a post

navigate

button_sign_up

open

JS
undefined

Widget has posts

status

has_posts

ready

JS
undefined
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.