How to use the offer list widget on your website

Anna-Lena Bahr

Modified on: Tue, 16 Nov, 2021 at 11:05 AM

What's offer list widget?

V-Hub includes a fully featured offer list widget. This allows sellers on V-Hub to present their coffees anywhere on the web. Their coffees can be easily added to their own website or any other website or page they chose. The offer list widget is simple to setup. It also comes with extensive customization options so sellers to present their offer list in a style that matches their own website or any other website.

To get started with offer lists we recommend you first see what your current offer list looks like using the tool below. Simply enter your shops name at the end of it's individual URL (also called a Slug). You can also select one of the examples below to see an offer sheet in action at another Hub seller.

Given the nature of building something like this on the web the instructions below assume you have some experience with HTML and posting active content to a website. If that's not your thing please contact us directly from your shop for help.

Shop slug

You can get it from your Shop URL or by reading from the shop edit page.

Example

Nordic Approach

Demo

Open in a new tab

Code

<hub-offer-list shop="nordic-approach"></hub-offer-list>

Setup

V-Hub comes with a responsive widget enabling you to show your coffees anywhere on the web.

Installation

In order to use the widget on your page you have to load widget script in <head> or at the end of <body> (recommended):

<script src="https://vll-dev-vhub-offerwidget.azureedge.net/hub-offer-list-v2.js"></script>

Usage

Using the widget is as simple as including the dedicated <hub-offer-list> tag anywhere in your page:

Configuration

There's a bunch of options to customize the widget to meet your requirements:

shop (= mandatory)

The slug of your shop from URL like http://v-hub.vollers.com/store/shops/<slug> .

<hub-offer-list shop="slug"></hub-offer-list>

Type: String

Values: any

Default: null

fields (= optional)

Defines the visible columns of the offer list widget.

<hub-offer-list  shop="slug"  fields="['name', 'country', 'region', 'price']">
</hub-offer-list>

Type: Array

Values: name country region availableAmount availableAmountKG availability processingMethod varieties sensorialDescriptors cropYear cuppingScore packaging price priceDoubleVal producer warehouse

Default: ['name', 'region', 'availableAmount', 'availability', 'processingMethod', 'varieties', 'sensorialDescriptors', 'price']

group-by (= optional)

Defines according to which field data should be grouped. To disable grouping at all, please set null as value.

<hub-offer-list  shop="slug"  group-by="availability">
</hub-offer-list>

Type: String

Default: 'country'

filter-by (= optional)

Filter data by certain properties, which is not corresponding to field attribute values. Currently, we support priceMin , priceMax , amountMin , amountMax , amountUnit , availability , certifications , country , descriptors , ids , processingMethods , scoreRanges , warehouseNames , grades and specialOffer .

<hub-offer-list  shop="slug"  filter-by="['availability', 'SPOT']">
</hub-offer-list>

To filter by multiple fields and values at once, please provide attribute as follows:

<hub-offer-list  shop="slug"  filter-by="[    ['availability', ['SPOT','AFLOAT']],    ['specialOffer', true],    ['country', 'BR']  ]">
</hub-offer-list>

Type: Array

Values: any

Default: []

The property priceMin from type Number accepts numeric values.

The property priceMax from type Number accepts numeric values.

The property amountMin from type Number accepts numeric values and requires amountUnit to be set as well.

The property amountMax from type Number accepts numeric values and requires amountUnit to be set as well.

The property amountUnit from type String is required with amountMin / amountMax and accepts:

'LBS'
'KG'

The property availability from type String accepts:

'SPOT'
'AFLOAT'
'ORIGIN'

The property certifications from type Number accepts a list of certification IDs.

The property country from type String supports all ISO country codes.

The property descriptors from type Number accepts a list of descriptor IDs.

The property ids from type Number accepts a list of coffee IDs. The easiest way to get it is from its detail page at 'http://v-hub.vollers.com/store/listings/<ID>' on V-Hub.

The property processingMethods from type String accepts:

'NATURAL'
'FULLY_WASHED'
'SEMI_WASHED'
'PULPED_NATURAL'
'HONEY'
'YEAST_FERMENTED'
'OTHER'
'MISC'

The property scoreRanges from type String accepts:

'UNDER_X'
'FROM_X_TO_Y'
'OVER_Y'

Examples:

To get only coffees with a rating < 50, use UNDER_50.
To get only coffees with a rating >= 90, use OVER_90.
To get only coffees with ratings >= 80 and < 85, use FROM_80_TO_85.

The property warehouseNames from type String supports all your defined warehouses by their names.

The property grades from type String supports all your defined grades by their names.

The property specialOffer from type Boolean accepts true only.

sort-by (= optional)

Defines according to which fields data should be sorted.

<hub-offer-list  shop="slug"  sort-by="'country'">
</hub-offer-list>

To sort by multiple fields and values at once, please provide attribute as follows:

<hub-offer-list  shop="slug"  sort-by="[    ['country', 'DESC'],    ['region', 'DESC'],    'cuppingScore'  ]">
</hub-offer-list>

Type: Array

Values: any

Default: []

To change ascending sort direction (= default), please set the sort property as an array with 'DESC' as second value.

Note: If you want to sort the formatted values 'price' and 'availableAmount' numerically, please use the numeric counterparts 'priceDoubleVal' and 'availableAmountKG' instead.

show-header (= optional)

Flag indicating if header including title and shop button is visible.

<hub-offer-list  shop="slug"  show-header="false">
</hub-offer-list>

Type: Boolean

Values: true false

Default: true

show-footer (= optional)

Flag indicating if footer including shop link and copyright is visible.

<hub-offer-list  shop="slug"  show-footer="false">
</hub-offer-list>

Type: Boolean

Values: true false

Default: true

title (= optional)

Custom title to be displayed above the offer list table.

<hub-offer-list  shop="slug"  title="Brazilian offerings"  filter-by="['country', 'BR']">
</hub-offer-list>

Type: String

Values: any

Default: 'Offer list'

label (= optional)

Custom label to be displayed both in shop button (header) and link (footer).

<hub-offer-list  shop="slug"  label="Go to shop">
</hub-offer-list>

Type: String

Values: any

Default: 'Visit us'

empty-message (= optional)

Custom empty message in case empty result set is returned from Vollers server. This might happen if you are using filters, which are currently matching no coffees in your inventory.

<hub-offer-list  shop="slug"  empty-message="We are out of coffee at the moment!">
</hub-offer-list>

Type: String

Values: any

Default: 'No coffees available at the moment!'

error-message (= optional)

Custom error message in case data cannot be loaded from Vollers server.

<hub-offer-list  shop="slug"  error-message="Cannot show offerings at the moment!">
</hub-offer-list>

Type: String

Values: any

Default: 'Could not load coffees!'

Advanced

To get full control over display you can make use of the advanced integration approach using templates. The esssential step is to provide <hub-offer-list-table-head-col> providing the column setup via field attribute. Thus, enabling the definition of how data shold be displayaed with <hub-offer-list-table-col> and {value}.

Code example

<!-- setup mandatory configuration -->
<hub-offer-list shop="nordic-approach">
  <!-- include header-->  <hub-offer-list-header>  </hub-offer-list-header>
  <!-- include table -->  <hub-offer-list-table>
    <!-- define fields -->    <hub-offer-list-table-head>      <hub-offer-list-table-head-col field="name">        NAME      </hub-offer-list-table-head-col>      <hub-offer-list-table-head-col field="region">        REGION      </hub-offer-list-table-head-col>      <hub-offer-list-table-head-col field="varieties">        VARIETIES      </hub-offer-list-table-head-col>      <hub-offer-list-table-head-col field="price">        PRICE      </hub-offer-list-table-head-col>    </hub-offer-list-table-head>
    <!-- define content -->    <hub-offer-list-table-body>      <hub-offer-list-table-col>        <strong>{value}</strong>      </hub-offer-list-table-col>      <hub-offer-list-table-col>        {value}      </hub-offer-list-table-col>      <hub-offer-list-table-col>        <ul>          <li each="{variety in value}">            {variety}          </li>        </ul>      </hub-offer-list-table-col>      <hub-offer-list-table-col>      </hub-offer-list-table-col>    </hub-offer-list-table-body>
  </hub-offer-list-table>
  <!-- include footer -->  <hub-offer-list-footer>  </hub-offer-list-footer>

</hub-offer-list>

More information

Our widget is based on the small, but excellent RIOT framework, which you can use for advanced templating. The <hub-offer-list-table-col> tag provides both {value} and {data} properties for further usage, whereas the former represents current column value, the latter the whole row data as a JSON object.

If you have feedback, questions, or concerns, please feel free to send it to your representative or directly to [email protected]. We design and make alterations to our software based on user feedback, so we look forward to seeing what you have to say!

Installation

Usage

Code example

More information

Related Articles