Adding Algolia data

tip

This tutorial assumes you have completed the basic tutorial and have the artifacts from that already present in Uniform.

Let's add some content data from Algolia into your Uniform Canvas-powered Next app. To do this we will need to add a new Algolia-powered parameter to your component type, and then tell your Next app how to fetch and parse the Algolia data to display it. Canvas provides a framework for enhancing data in your Canvas composition with data from other tools, like CMSes, DAMs, commerce, and search indexes. This enhancement is done on the app side, leaving full flexibility to the developer as to the best and most efficient way to get the data.

First let's connect Uniform to Algolia by installing the integration. You'll need an Algolia account to do this (a free one is fine).

Go to Settings on your on https://uniform.app project, then click Integrations
Find the Algolia integration and add it
Click the button to add a content source
Provide the Application ID, Index Name, Search API Key for the Algolia project that you want to bring content from into Canvas

Algolia parameter CANVAS_ALGOLIA_QUERY_PARAMETER_TYPES

Algolia integration to Uniform provides two types of parameters to be used in a Canvas component:

Algolia Query - storing query parameters such as search phrase, facets and results count, and performing search during SSR
Algolia Record - treating Algolia Index as a headless CMS and saving actual index record IDs, pulling data from index during SSR

Let's start with Algolia Query.

Algolia Query

Now that we're connected to Algolia, we can add a new parameter to our Canvas component type that links to an Algolia query.

Go to your Component Library settings
Open your component type (there should be only one, if you've been following along)
Click (+) next to Parameters
Name your parameter something like 'Algolia Query', choose Algolia Query as the type, pick an Algolia source (repository) from which data will be queried, and as before choose a public ID to use as the name in code. (e.g. algoliaQuery)
Optionally, define Title Field Name that will be pulled from every search result and used as a search result title e.g. properties.Title (case-sensitive). When omitted it will use objectID instead.
Optionally, define Sub-Title Field Name that will be pulled from every search result and used as a search result title e.g. properties.Description (case-sensitive)
Optionally, define Image URL Field Name that will be pulled from every search result and used as a search result image e.g. properties.ImageUrl (case-sensitive)
Optionally, define Document Updated Date Field Name that will be pulled from every search result and used as a search result timestamp e.g. properties.LastModified (case-sensitive)
Optionally, add one or more facets so content authors can use them to filter query results as required e.g. label: Country, facet: properties.Country (case-sensitive)

Now that the parameter is added to the component type, we need to link the composition we have been rendering to an actual Algolia query:

Click Compositions, then open your composition from earlier
You should see an Algolia parameter alongside the text parameter we created before
Adjust an Algolia query and save your composition
That's it - you've linked to an Algolia query in your composition

With the data schema setup complete, now let's set up Next.js. Right now we're doing nothing with the Algolia data - the Next app will look exactly the same as it did before, except it has a new parameter we're doing nothing with. To get the Algolia data, we need to add an enhancer to the Next app's data fetching so that Canvas knows what to do with Algolia parameters.

Install the @uniformdev/canvas-algolia and algoliasearch packages, which contains the Canvas Algolia Query enhancer and the Algolia Client respectively.

Open your pages/index.js file and import the Algolia enhancer, and add enhance to the existing canvas import:

import {
  createAlgoliaQueryEnhancer,
  CANVAS_ALGOLIA_QUERY_PARAMETER_TYPES,
  AlgoliaClientList,
} from '@uniformdev/canvas-algolia';
import { enhance, CanvasClient, EnhancerBuilder } from '@uniformdev/canvas';
import algoliasearch from 'algoliasearch';
import AlgoliaDOM from 'algolia-dom';

In getStaticProps, create the enhancer and configure it to connect to Algolia and enhance your composition data:

// ...fetching the composition here

const client = algoliasearch('your-application-id', 'your-algolia-search-key')
   .initIndex('your-index-name);

// create the Algolia enhancer
const algoliaQueryEnhancer = createAlgoliaQueryEnhancer({ clients: new AlgoliaClientList({ client }) });

// apply the enhancers to the composition data, enhancing it with external data
// In this case, the _value_ of the Algolia parameter you created is enhanced
// with data from the Algolia query you selected in the Algolia query selector.
// You can create your own enhancers easily; they are a simple function.
await enhance({
  composition,
  enhancers: new EnhancerBuilder().parameterType(CANVAS_ALGOLIA_QUERY_PARAMETER_TYPES, algoliaQueryEnhancer),
  context: {},
});

// ...returning the props

The Next app should still be working, but we're not rendering any of the Algolia data yet. Let's do that!

In the Home component implementation, get the Algolia parameter value and pick a field from it:

export default function Home({ composition }) {
  return (
    <Composition data={composition}>
      {({ greeting, algoliaQuery }) => (
        <article>
          <p>{greeting}</p>
          <ul>
           {algoliaQuery.map(document =>
             <li><pre>{JSON.stringify(document, null, 2)}</pre></li>
          </ul>
        </article>
      )}
    </Composition>
  );
}

That's it - now you're rendering data from Algolia!

Algolia Record

Use of Algolia Record property type requires minimal changes to the previously defined Algilia Query. Once a parameter is added to a Component, its type cannot be changed so we need to remove old parameter and add a new one:

Go to your Component Library settings
Open your component type (there should be only one, if you've been following along)
Click (...) next to your Algilia Query parameter in Parameters and click (Delete)
Click (+) next to Parameters
Name your parameter something like 'Algolia Record', choose Algolia Record as the type, pick an Algolia source (repository) from which data will be queried, and as before choose a public ID to use as the name in code. (e.g. algoliaRecord)
Optionally, define Title Field Name that will be pulled from every search result and used as a search result title e.g. properties.Title (case-sensitive). When omitted it will use objectID instead.
Optionally, check Allow multi-select that will allow selecting more than one document at once

Now that the parameter is added to the component type, we need to link the composition we have been rendering to an actual Algolia records:

Click Compositions, then open your composition from earlier
You should see an Algolia Record parameter instead of removed Algilia Query
Select one or several Algolia records and save your composition
That's it - you've linked to an Algolia record in your composition

tip

If you changed the name of the parameter, you may see "Orphan parameter data found" warning that suggests that the composition still holds data of the removed parameter.

Install the @uniformdev/canvas-algolia and algoliasearch packages, which contains the Canvas Algolia Query enhancer and the Algolia Client respectively.

Open your pages/index.js file and import the Algolia enhancer, and add enhance to the existing canvas import:

import {
  createAlgoliaRecordEnhancer,
  CANVAS_ALGOLIA_RECORD_PARAMETER_TYPES,
  AlgoliaClientList,
} from '@uniformdev/canvas-algolia';
import { enhance, CanvasClient, EnhancerBuilder } from '@uniformdev/canvas';
import algoliasearch from 'algoliasearch';
import AlgoliaDOM from 'algolia-dom';

In getStaticProps, create the enhancer and configure it to connect to Algolia and enhance your composition data:

// ...fetching the composition here

const client = algoliasearch('your-application-id', 'your-algolia-search-key')
   .initIndex('your-index-name);

// create the Algolia Record enhancer
const algoliaRecordEnhancer = createAlgoliaRecordEnhancer({ clients: new AlgoliaClientList({ client }) });

// apply the enhancers to the composition data, enhancing it with external data
// In this case, the _value_ of the Algolia parameter you created is enhanced
// with data from the Algolia query you selected in the Algolia query selector.
// You can create your own enhancers easily; they are a simple function.
await enhance({
  composition,
  enhancers: new EnhancerBuilder().parameterType(CANVAS_ALGOLIA_RECORD_PARAMETER_TYPES, algoliaRecordEnhancer),
  context: {},
});

// ...returning the props

The Next app should still be working, but we're not rendering any of the Algolia data yet. Let's do that!

In the Home component implementation, get the Algolia parameter value and pick a field from it:

export default function Home({ composition }) {
  return (
    <Composition data={composition}>
      {({ greeting, algoliaRecord }) => (
        <article>
          <p>{greeting}</p>
          <ul>
           {algoliaRecord.map(document =>
             <li><pre>{JSON.stringify(document, null, 2)}</pre></li>
          </ul>
        </article>
      )}
    </Composition>
  );
}

That's it - now you're rendering statically selected data from Algolia!

tip

You may have notice that Algilia Record and Algolia Query use identical syntax in Next.js which makes them easy to swap.

Adding Algolia data

tip

Algolia parameter CANVAS_ALGOLIA_QUERY_PARAMETER_TYPES​

Algolia Query​

Algolia Record​

tip

tip

Algolia parameter CANVAS_ALGOLIA_QUERY_PARAMETER_TYPES

Algolia Query

Algolia Record