## Introduction

### Goal

Create a new "Promotions" page component, extending the query base component, that renders documents of the "Promotion" type.

### Prerequisites

Before starting:

  • Follow the [previous tutorial](🔗) to create the "Promotion" document type.

  • [Obtain an authorization token](🔗) for the Site Management API if you haven't already done so.

  • Have the [Site Management API](🔗)[Base Components](🔗) and [SPA SDK](🔗) and [React SDK](🔗) reference documentation handy.

To perform the Site Management API request in this tutorial it is recommended to use the [Postman collection](🔗) for the Site Management API. However, you can use any other method or tool you like such as the [_Site development_ app](🔗) or curl or httpies.

## Approach

In the [Promotion Document Type](🔗), you created a promotion document type and some promotion documents.

In this tutorial, you will create a React page component that renders current promotions (i.e. promotions that haven't expired).

You will extend the [query base component](🔗) and override its default configuration so that it queries only promotion documents with an expiry date in the future.

The corresponding React implementation will consist of two components:

  • "Promotion", rendering a single promotion document

  • "Promotions", rendering a list of Promotion components

## Define the Promotions Component using the Site Management API

Before you start, add your channel to your development project if you haven't done that already, and make sure it has your local SPA URL configured.

Use the Site Management API's [component endpoint](🔗) to create a new "promotions" component in the "brx-reference-spa" component group.

Use the following request body:

Note the following in the configuration above:

  • The "brx-reference-spa/promotion" component extends the "base/query" component.

  • The following default configuration parameters of the "base/query" component are overridden with new default values:

    • "documentTypes" is set to "brxsaas:Promotion", the technical name for the "Promotion" document type.

    • "sortField" is set to "brxsaas:expirydate", the technical name for the "Expiry Date" field.

    • "sortOrder" is configured with an enumeration of possible values ("Ascending" and "Descending") and set to "Ascending" by default.

    • "dateField" is set to "brxsaas:expirydate", the technical name for the "Expiry Date" field.

    • "hidePastItems" is set to "true" so that promotions with an expiry date in the past are excluded.

## Implement the Promotion React Component

Let's start with the Promotion component which will render the "Promo Code" and "Text" values for a single promotion document.

First, define a corresponding interface in `components/brx.d.ts` for the "Promotions" document type:

Create a folder `components/Promotions`. Both the Promotion and the Promotions components will live inside this folder.

Let's also define some styles before implementing the component.

Create `components/Promotions/Promotion.module.scss` with the following contents:

Next, create the actual Promotion component in `components/Promotions/Promotion.tsx`:

Note the following about the component implementation:

  • It assumes a reference to a document is provided by the parent component (which you will implement in the next section).

  • It retrieves the promocode and text properties from the document, using the Promotion interface defined earlier.

  • It renders promocode and text.

  • It imports and applies the styles defined earlier.

  • If the page is rendered in a preview context (i.e. in the Experience manager app), it renders a "Manage Content" button.

## Implement the Promotions React Component

Create the Promotions component in `components/Promotions/Promotions.tsx`:

Note the following about the component implementation:

  • It retrieves the pagination object returned by the [query component](🔗).

  • It retrieves the documents from the pagination object.

  • It renders a Promotion component for each document in documents.

Export the Promotions component in `components/Promotions/index.tsx`:

Finally, add the required wiring to make the Promotions component available in the application.

At the bottom of `components/index.tsx`, add:

In `components/App.tsx`, add `Promotions` to the list of components imported from `'./components'` as well as to the mapping in the `App` class.

You are now ready to test the Promotions component.

## Add the Promotions Component to the Homepage

Open your channel in the _Experience manager_ app and make sure the "Promotions" project is selected. Add the homepage to the project if you haven't already.

Open the left sidebar and click on the _Components_ tab. The list of available components should include Promotions:


Click on _Promotions_ and add it to the container on the homepage.

If you did everything right, it should automatically show the promotions you created:


The promotions should be sorted in order of their expiry dates and "Manage content" buttons should appear if the content buttons overlay is active.

Click on the "Manage content" button for one of the promotions. The content editor will appear in the right sidebar.

Change the expiry date of the promotion to a date in the past. After you click Save, the promotion should no longer be displayed:


Change the expiry date back to a date in the future and save again and close the editor.

Now click inside the component on the page to open the component configuration in the right sidebar:


You'll see all the default values you configured for the component using the API.

Try changing the _Sort order_ using the dropdown and toggle the checkboxes for _Hide past items_ and _Hide future items_ to see what happens.

If everything works as expected, you completed this tutorial!