Extend listing data in Sharetribe Web Template

This guide shows you a code-based approach to expanding the listing data model in your marketplace. We'll have a look on how the listing can be configured so that the data gets added, and how it can then be presented and used to filter searches.

Adding new attributes to the data model relies on extended data. In Sharetribe Web Template, top-level listing extended data is configured in the configListing.js file.

└── src
    └── config
        └── configListing.js

Configuring the listing data this way allows you to

• declare the attribute and its possible values
• show the attribute selection inputs in the listing editing wizard
• optionally show the attribute values on the listing page and
• optionally use the attribute as a search filter.

If you want to configure a complex extended data attribute, e.g. a JSON object, it is good to note that Sharetribe only allows searching and filtering top-level attributes. In other words, complex attributes cannot be used to filter listings. However, they can be useful in storing other relevant listing data.

For a more complex attribute, you will need to add extended data directly to a listing. You will also need to make custom changes to your listing page, if you want to show the attribute there.

In this article, we will extend top-level data using configListing.js.

Add a new top-level attribute

Let's extend the default bike related listing data by adding an attribute 'accessories' to show what accessories are included. The full configuration looks like this:

  {
    key: 'accessories',
    scope: 'public',
    schemaType: 'multi-enum',
    enumOptions: [
      { option: 'bell', label: 'Bell' },
      { option: 'lights', label: 'Lights' },
      { option: 'lock', label: 'Lock' },
      { option: 'mudguard', label: 'Mudguard' },
    ],
    saveConfig: {
      label: 'Accessories',
      placeholderMessage: 'Select an option…',
      isRequired: false,
    },
    filterConfig: {
      indexForSearch: true,
      label: 'Accessories',
      searchMode: 'has_any',
      group: 'secondary',
    },
    showConfig: {
      label: 'Accessories',
    },
  },

Declaring the attribute and its possible values

Extended data attributes in the configListing.js file need to be defined, at minimum, by key, by scope, and by schemaType.

key: 'accessories',
scope: 'public',
schemaType: 'multi-enum',
enumOptions: [
  { option: 'bell', label: 'Bell' },
  { option: 'lights', label: 'Lights' },
  { option: 'lock', label: 'Lock' },
  { option: 'mudguard', label: 'Mudguard' },
],
// If you have multiple listing types, you can define the types that should have this field
// limitToListingTypeIds: [...],

This attribute is defined as public, so it will be saved into the listing as publicData.accessories. The schemaType attribute determines the shape of the data being saved:

• enum attributes are saved as a single string value from a list of predefined options
• multi-enum attributes are saved as an array of string values from a list of predefined options
• boolean attributes are saved as true or false boolean values
• long attributes are saved as long i.e. as an 8-byte whole number
• text attributes are saved as a single text entry

If the schema type is enum or multi-enum, you will need to define an array of enumOptions for the attribute. This allows the listing editing wizard to show the options when your user creates the listing, and it also provides the options for the search filters.

If your marketplace uses multiple listing types, you can optionally define an attribute limitToListingTypeIds. This attribute is an array of the listing types that should have this field. If this attribute is not set, then the field is included in all listing types.

Configuring the listing detail editing page

The EditListingDetailsPanel is configured to show specific inputs for specific schema types. This means that you only need to configure how the attribute shows up in the panel.

You can separately determine the label for edit listing page and the other contexts where the attribute shows up. You can also set the attribute as required, and determine the error message to show if the attribute is missing.

saveConfig: {
  label: 'Accessories',
  placeholderMessage: 'Select an option…',
  isRequired: false,
},

Configuring search

Top-level attributes can be set as searchable, but you might have listing attributes you do not want to use for filtering listings. For instance, you may have private data text fields that the provider can use for listing-specific notes.

For searchable attributes, you will need to include the filterConfig attribute to your listing configuration. In addition, you will need to define a search schema. Make sure you define the search schema type according to the listing configuration schemaType.

For multi-enum attributes, you can use searchMode to define whether you want to show

• listings with all the query attributes (has_all), or
• listings with any of the query attributes(has_any).

If searchMode is not defined, or if you define a listing field in Console, the default is has_all. To define a multi-enum listing field with has_any search logic, you will need to define the field in your local code.

filterConfig: {
  indexForSearch: true,
  label: 'Accessories',
  searchMode: 'has_any',
  group: 'secondary',
},

Configuring the listing page

The configuration for showing top-level extended data on the listing page is straightforward. In addition to the label, you can determine whether to show specific attribute values on the listing page.

By default, all listing config attributes with a showConfig.label are shown on the listing page, but by setting isDetail to false on an attribute with schema type enum, long, or boolean, you can hide the attribute from the Details section on the listing page.

showConfig: {
  label: 'Accessories',
},

And that is it! With this configuration, the attribute can be added to the listing, used for search, and shown on the listing page.