Forem: Aaron Pavlick

Data Consistency with Webhook Functions

Aaron Pavlick — Tue, 21 Jun 2022 14:30:19 +0000

In my previous post, I explained how I was able to edit the primary photo for each entity in my Knowledge Graph utilizing a Typescript function plugin, the Cloudinary Image Transformation API, and the Data Connectors framework. If my Knowledge Graph continues to expand with new Beverage entities, I want to ensure that their new photos have the same format as all the existing photos.

With Webhooks, I was able to apply the same logic to create a newly computed field called Transformed Photo.

Updating my Function Plugin

I didn’t need to change any of the existing code that I already wrote. I just needed to add a few things to make it compatible with a Webhook invocation.

First, I added types.ts for some type definitions used for validating the input to the Webhook function.

// types.ts

export interface WebhookPayload {
  changedFields: ChangedFields;
  entityId: string;
  primaryProfile: PrimaryProfile;
  meta: {
    eventType: string;
  };
}

export interface PrimaryProfile {
  primaryPhoto: PrimaryPhoto;
}
export interface PrimaryPhoto {
  image: Image;
}
export interface Image {
  url: string;
}
export interface ChangedFields {
  fieldNames: string[];
}

In api.ts, I added a Knowledge API client function for editing the newly created entity.

// api.ts

import axiod from "https://deno.land/x/axiod@0.23.2/mod.ts";

declare const YEXT_ACCOUNT_API_KEY: string;

export const editEntity = async (
  entityId: string,
  // deno-lint-ignore no-explicit-any
  data: Record<string, any>
) => {
  try {
    // using fetch instead of axios works too. I just prefer axios syntax.
    await axiod.put(
      `https://api-sandbox.yext.com/v2/accounts/me/entities/${entityId}`,
      data,
      {
        params: {
          api_key: YEXT_ACCOUNT_API_KEY,
          v: "20220322",
        },
      }
    );
  } catch (error) {
    if (error.response) {
      console.error(`${error.response.status}: ${error.response.data}`);
    }
    throw error;
  }

  console.log(`Edited entity ${entityId}`);
};

Lastly, I added the removeBackgroundHook function to mod.ts that checks if the primary photo is a changed field. If the primary photo field is updated, the function calls my removeBackground function to get the new Image URL, and then calls the edit entity API and updates a new field I added to the beverage entity called c_transformedPhoto.

// mod.ts

export const removeBackgroundHook = async (payload?: WebhookPayload) => {
  if (payload?.changedFields.fieldNames.includes("primaryPhoto")) {
    console.log(`Transforming primaryPhoto for Entity ${payload?.entityId} `);

    const imageUrl = await removeBackground(
      `${payload.entityId}|${payload.primaryProfile.primaryPhoto.image.url}`
    );

    if (imageUrl) {
      await editEntity(payload.entityId, {
        c_transformedPhoto: { url: imageUrl },
      });
    }
  }
};

Before running yext resources apply, I updated my _resource.json to include the additional variables I am going to need to call the Edit Entity API.

{
  "$id": "TransformImagePlugin",
  "$schema": "https://schema.yext.com/config/platform/plugin/v1",
  "globals": {
    "CLOUDINARY_API_KEY": "${{CLOUDINARY_API_KEY}}",
    "CLOUDINARY_API_SECRET": "${{CLOUDINARY_API_SECRET}}",
    "YEXT_ACCOUNT_API_KEY": "${{YEXT_ACCOUNT_API_KEY}}"
  }
}

Adding a Webhook in the Developer Console

In the Developer Console of my account, I added a new Webhook to my existing app. The API Key that I uploaded along with my plugin needs permission to update entities so I needed to add Read/Write access to the Entities Knowledge API in the API Credentials screen.

Then, I set the Webhook Type which determines when the hook should be trigged.

After selecting the Webhook Type, I gave my new hook a name, description, and the function it should invoke when triggered.

To make sure my hook was working correctly, I added a new primary photo to an entity in my Knowledge Graph and then checked to see the c_transformedPhoto field changed.

You can see that any time the Primary Photo field changes, I get a new value added to the Transformed Photo field. Whether I create or edit entities via the UI, CSV upload, Data connector, or API call, the webhook will be called to create a new transformed photo. Webhooks can also be configured to run based on a variety of other events and could be used to call an API rather than a function.

You can find the complete Webhook function plugin code here.

Enriching a Knowledge Graph using Connectors and Functions

Aaron Pavlick — Mon, 23 May 2022 22:21:27 +0000

I was recently developing a React web app designed by one of the product designers on my team. She created a clean looking home screen design that featured some image carousels where each image appears over top of a light orange background. After I wrote the necessary components, I realized they didn’t look the way I wanted.

Each image returned by the Answers API had a white background when I needed them to have a transparent background. I knew that Cloudinary offered an image transformation API that I could use to remove the white background, but I needed to transform every image for over 1000 entities in my Knowledge Graph. In this article, I will show how I transformed every image in my Knowledge Graph data with the Cloudinary Image Transformation API, a function plugin, and the Data Connector framework.

Writing My Function Plugin

All of the images in my Knowledge Graph were JPEGs which do not support transparent backgrounds. I needed to use Cloudinary chained transformations to first convert my images to PNGs and then remove the white background. I also chose to use Eager Transformations to receive the transformed asset immediately after storing it in my Cloudinary account.

After creating my plugin folder structure, added uploadImageTransform to mod.ts to make the transformation request and return the new URL.

// Chained, eager tranformation 
const eager = "f_png,e_bgremoval";

const uploadImageAndTransform = async (
  file: string,
  public_id: string,
  signature: string,
  timestamp: number
): Promise<string> => {
  console.log(`Uploading ${public_id} to Cloudinary and transforming ${file}`);

  try {
    const response = await axiod.post(
      "https://api.cloudinary.com/v1_1/yext/image/upload",
      {
        file,
        public_id,
        api_key: CLOUDINARY_API_KEY,
        eager,
        signature,
        timestamp,
      },
      {
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
      }
    );

    return response.data.eager[0].url;
  } catch (error) {
    if (error.response) {
      console.error(`${error.response.status}: ${error.response.data}`);
    }
    throw error;
  }
};

Cloudinary’s transformation API requires a digital signature to provide authentication for each request. Since I am not using a Cloudinary SDK, I had to write my my own function for generating a signature using the web crypto API that is included with Deno.

const generateCloudinarySignature = async (params: string) => {
  const data = new TextEncoder().encode(params);
  const digest = await crypto.subtle.digest("sha-1", data.buffer);
  return encodeToString(new Uint8Array(digest));
};

I then wrote the removeBackground function for my Data Connector to call. The function accepts a string that is expected to be delineated with a ‘|’. The public_id is intended to be the Knowledge Graph entityId and url is the original url of the photo that needs transformed.

export const removeBackground = async (input: string) => {
  const timestamp = Math.floor(Date.now() / 1000);
  const [public_id, url] = input.split("|");

  const signature = await generateCloudinarySignature(
    `eager=${eager}&public_id=${public_id}&timestamp=${timestamp}${CLOUDINARY_API_SECRET}`
  );

  if (public_id && url) {
    const imageUrl = await uploadImageAndTransform(
      url,
      public_id,
      signature,
      timestamp
    );

    return imageUrl;
  }
};

I wrote a function in test.ts to make sure the transformation worked for one of the images in my Knowledge Graph.

const testInput =
  "beer_60|https://a.mktgcdn.com/p-sandbox/rrK5bxcoVAgkGckDnA7GlhyC1VOpV6eEf4KjjlFumQs/400x600.jpg";

Deno.test("test remove background", async () => {
  const newUrl = await removeBackground(testInput);
  console.log(newUrl);
});

Applying the Function Plugin to a Data Connector

After uploading my function plugin to my Yext account, I created a new Data Connector with “Pull from API” as the source to pull the entities from my own account using the Knowledge Graph Entities: Get API. I also needed to create an app in the Developer Console to get an API Key to allow my Data Connector to make requests to the Entities API.

I autogenerated my selectors and then applied a Merge Columns Transformation to combine entityId and primaryPhoto.image.url into a new column called Transformed Image.

I took the new column and applied my removeBackground function to it.

Finally, I mapped the meta.id back to entityId to let the Connector know that I am editing existing entities and replacing the Primary Photo Image URL with a new URL.

I ran my newly created Connector and it completed in less than 5 minutes. When I refreshed my app home screen, the white backgrounds were gone.

Conclusion

I had the option of making a request to Cloudinary from my React application each time I wanted to fetch the transformed image. However, I am already fetching the entities from my Knowledge Graph via the Answers API. Making the additional request to Cloudinary would eat into my month bandwidth allotment. If this were a production application, I would go over my free account allotment pretty quickly. This way, the resources are only fetched when I make the initial request for each image on the Connector run.

This example could be extended to apply more complex image transformations. I could also upload a separate function to call a different API for further Knowledge Graph enhancements.

You can see the complete code for the function here and read more about Data Connectors here.

Building Modern Search with Yext: Part 2 - Expanding Search Capabilities

Aaron Pavlick — Wed, 02 Mar 2022 16:36:51 +0000

In part 1 of this blog series, I introduced how to quickly get a simple search page up and running using the Yext Knowledge Graph, Answers, and the React site starter repo. So far, I only have Movie entities in my Knowledge Graph.

In this guide, I want to add a new Actors search vertical and improve the user interface of my search experience. I’m going to add Actor entities, link them to the Movies they are associated with (and vice-versa), and reconfigure my Answers API to return the most relevant results possible. I may be using Movies and Actors in this project, but I could build a similar experience associating restaurants with limited time offers or gym locations with workout classes.

Finally, I’ll update my React application to provide a more visually appealing search experience.

NOTE: If you would like to copy the Yext account I create in this guide, check out the README of the Github repo to copy the experience described below to your Yext account.

Adding a Custom Actor Entity

I need a new custom entity type to represent the top actors from each of the movies that I added to my Knowledge Graph in part 1. After adding a new entity type with the name “Actor” and the plural name “Actors,” I’ll navigate to the newly-created type and add the following fields:

Primary Photo - This is a built-in field that I’ll use to store an image URL as the headshot for each Actor’s entity.
Birth Place - Custom Single-Line Text field used to represent the Actor’s home city, state, and country.
Bio - Custom Multi-Line Text field that contains a description of the Actor and their career.
Height - Custom Single-Line Text field containing the Actor’s Height
Birth Date - Custom Single-Line Text field containing the Actor’s Birth Date

By adding these fields, users will be able to search for some basic information about movie stars. But what if a user wants to see the movies that Keanu Reeves has starred in or find out who voiced Buzz Lightyear in Toy Story 2? I need a custom field type that will contain the role the actor played/voiced (e.g. Neo, Buzz Lightyear) and the movie which they played it in (e.g. The Matrix, Toy Story 2). I’ll navigate to the Field Type section in my Knowledge Graph Configuration, add a new custom field type, and name it Role.

Before saving, I need to add 2 subfields to my custom type:

Character Name - Single-line text field for the name of the character that an actor played or voiced in a given movie
Movie - Entity List type to link the role to the movie that the actor performed the role in. I have added validation here to ensure that only Movie type entities can be linked.

When I go back to my Actor entity type configuration, I will create a new custom field called Filmography. When choosing the Field Specification, I’ll choose Role as the field type and Make it a List.

Expanding the Movie Entity Type

I need to add some new fields to my custom Movie entity to provide more interesting search results, enhance my search experience UI, and link Movies back to Actors:

Poster - Simple Photo field for storing the promotional movie poster associated with the movie’s release.
MPA Rating- Single-line text field for storing the Motion Picture Association film rating (e.g. G, PG, PG-13, R)
Runtime - Number field for storing the movie’s runtime in minutes. The field will be returned as a string by the Answers API.

Just like how I linked Movies to Actors with the Filmography field and Role field type, I’m going to create a custom Star field type to establish a relationship between Movie and Actor entities. I’ll add the following subfields to the new field type:

Role - Single-line text field to represent the name of a movie role
Actor - Entity List type to link the role to the Actor that performed the role. I have added validation here to ensure that only Actor type entities can be added

I will add a field called Stars to the Movie entity type with a field type of Star and I will select “Make it a List” so that I can link all of the Actors from a given movie.

Actors Search Configuration

In my search configuration, I need to add an Actors vertical so that I can search on the new entities that I have added. The Entity Type and Name fields will be enabled as searchable fields by default. I will leave the Entity Type search field configuration as-is with NLP filter still enabled so that any universal search containing the phrase “actor” or “actors” will only return Actor entity types. For the Name field on the other hand, I will disable Semantic Text Search and apply Phrase Match and Text Search.

If I search for “buzz lightyear”, I want the Buzz Lightyear voice actor to appear at the top of the search results while searching for “toy story 2” should return the top voice actors from that movie. I’ll add c_filmography.characterName and c_filmography.movie.name as searchable fields with the NLP Filter turned on. That way, a search for a character name will filter out any actors who don’t have that character in their Filmography and searching for a movie will remove actors who didn’t star in that movie.

I’m also going to add Height, Birth Date, and Birth Place as Direct Answer fields so that those fields can be extracted from the entity separately from the entity itself. I’ll also add some synonym sets in my search configuration to teach the Answers algorithm to apply the same meaning to specific sets of words. Now if user asks questions like “How tall is keanu reeves” or “where was brad pitt born” the answer will be extracted from the Actor entity and returned before the other results.

Updating the Movies Vertical

I also need to update my Movie vertical configuration to account for the new fields that are part of my Movie entities. Similar to the Actors vertical, I’m going to add c_stars.role and c_stars.actor.name as NLP Filter fields. That way, when I search for a character or actor’s name, only movies that meet those conditions should be returned. Searching for ‘Neo’ should just return The Matrix and searching for Keanu Reeves should return any movies in the Knowledge Graph that he has starred in.

I’ll also add MPA Rating as a Direct Answer field and “mpa rating” “rated” and “rating” as a synonym set so that a universal query can answer questions like “what is the matrix rated”

After adding all of the configuration for my Movies and Actors, I can test out some search queries in my Answers test search:

Customizing the UI

In part 1, I cloned the Yext React Site Search Starter repo and added my Answers configuration. Now I want to add some of my own components and change some of the default stying to give my application it’s own look and feel.

The Site Search Starter includes Tailwind CSS; a CSS framework that provides utility classes for customizing components in a web application. Unlike CSS frameworks like Bootstrap or Materialize, Tailwind does not provide pre-built components. Instead, its utility classes make it easy to style components that are built from scratch.

In App.tsx, I’m going to remove some of the default styling to make the content of my search experience take up most of the page. I’m still going to leave some padding on the outer container

// App.tsx

export default function App() {
  return (
    <AnswersHeadlessProvider {...answersHeadlessConfig}>
      <div className='flex py-4 px-6'>
        <div className='w-full'>
          <PageRouter
            Layout={StandardLayout}
            routes={routeConfig}
          />
        </div>
      </div>
    </AnswersHeadlessProvider>
  );
}

StandardLayout.tsx is provided to the PageRouter to organize the search bar and search results for each page in my application. I’m going to modify the StandardLayout component by commenting out Navigation and SampleVisualSearchBar because I’m only going to worry about my Universal Search results and page for now.

I also want to override some of the builtInCssClasses within the SearchBar component so I’m passing searchBarCssStyles and a cssCompositionMethod of ‘assign’ as props. The ‘assign' method will assign the Tailwind classes I have added to searchBarCssStyles to their corresponding elements. Every built-in style not included in searchBarCssStyles will be left alone. The README in the React Site Search Starter provides an explanation of cssCompositionMethod and its different options.

// StandardLayout.tsx

const searchBarCssStyles = {
  container: 'h-12 font-display text-xl w-2/5', 
  logoContainer: 'hidden', 
  inputContainer: 'inline-flex items-center justify-between w-full mt-1',
  inputDropdownContainer: 'bg-white border rounded-lg border-gray-200 w-full overflow-hidden text-black',
}

const StandardLayout: LayoutComponent = ({ page }) => {
  // const isVertical = useAnswersState(s => s.meta.searchType) === SearchTypeEnum.Vertical;

  return (
    <>
      {/* example use of the VisualSearchBar which is used to display entity previews on autocomplete for Vertical searches */}
      {/* {isVertical
        ? 
        : <SampleVisualSearchBar />
      } */}
      <SearchBar
        placeholder='Search...'
        screenReaderInstructionsId='SearchBar__srInstructions'
        customCssClasses={searchBarCssStyles}
        cssCompositionMethod='assign'
      />
      {/* Navigation is commented out as app only displays Universal Search results */}
      {/* <Navigation links={navLinks} */}
      {page}
    </>
  )
}

In the container field within my custom css classes, I am including a class called font-display. This class is not included with Tailwind and is something that I added to my Tailwind configuration. After downloading some fonts from Google fonts and adding them to my project, I imported them into the application CSS via the tailwind.cssfile.

/* tailwind.css */

@font-face {
  font-family: "Bebas Neue";
  src: url(./fonts/BebasNeue-Regular.ttf);
}

@font-face {
  font-family: "Roberto";
  src: url(./fonts/RobotoSerif-VariableFont.ttf);
}

@tailwind base;
@tailwind components;
@tailwind utilities;

tailwind.config.js is where I can extend the the default theme and add new font family classes that reference the fonts that I imported. I have also added a color to the default color palette, added a custom box shadow class, and added a custom min-width class. I’ll be using these classes later on when creating some of my own components.

// tailwind.config.js

module.exports = {
  purge: ['./src/**/*.{js,jsx,ts,tsx}', './public/index.html'],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {
      fontFamily: {
        display: [ 'Bebas Neue'],
        body: ['Roberto']
      },
      colors: {
        'slate': '#0f2027',
      },
      boxShadow: {
        'movie': 'rgba(243, 244, 246, 0.35) 0px 5px 15px',
      },
      minWidth: {
        '1/3': '33.3333333%'
      }
    },
  },
  variants: {
    extend: {
      dropShadow: ['hover']
    },
  },
  plugins: [ 
    require("@tailwindcss/forms")({
      strategy: 'class',
    }),
  ],
}

I’m also going to rearrange the InputDropdown component within SearchBar to move the search icon to the start of the container. Because I assigned the hidden Tailwind class to the logoContainer, the Yext logo will no longer appear in the search bar.

// InputDropdown.tsx

return (
    <div className={inputDropdownContainerCssClasses} ref={inputDropdownRef} onBlur={handleBlur}>
      <div className={cssClasses?.inputContainer}>
        <div className={cssClasses.searchButtonContainer}>
          {renderSearchButton()}
        </div>
        <div className={cssClasses.logoContainer}>
          {renderLogo()}
        </div>
        <input
          className={cssClasses.inputElement}
          placeholder={placeholder}
          onChange={evt => {
            const value = evt.target.value;
            setLatestUserInput(value);
            onInputChange(value);
            onInputFocus(value);
            setChildrenKey(childrenKey + 1);
            dispatch({ type: 'ShowSections' });
            setScreenReaderKey(screenReaderKey + 1);
          }}
          onClick={() => {
            onInputFocus(inputValue);
            setChildrenKey(childrenKey + 1);
            dispatch({ type: 'ShowSections' });
            if (numSections > 0 || inputValue) {
              setScreenReaderKey(screenReaderKey + 1);
            }
          }}
          onKeyDown={handleInputElementKeydown}
          value={inputValue}
          ref={inputRef}
          aria-describedby={screenReaderInstructionsId}
          aria-activedescendant={focusedOptionId}
        />

      </div>
      {/* ...other code */}
    </div>
  );

After making these changes, saving, and starting my application locally with npm start, I now have a slightly different layout for my application.

Adding MovieCard and MovieSection

Each Movie search result is currently using the StandardCard component. I want to replace this with my own movie card component to make each card more visually appealing and interactive. Each card I add to my app needs to be of type CardComponent. The CardProps passed to each card component contain the search result from which I can pull out the data I need to customize the look and feel of my card.

In MovieCard.tsx, I have defined the interface Movie which contains the fields I will use in my new result card. Because I know that each result will be of type Movie, I can safely use a type assertion to convert the unknown rawData contained in props.result to a Movie. I’m going to use the poster url from movie as the background image of an element and style it with some Tailwind classes.

// MovieCard.tsx

// Name is only required field for a Movie entity, every other field needs the conditional operator
interface Movie {
  name: string,
  description?: string,
  c_poster?: {
    url: string
  },
  c_genres?: string[],
  c_mpaRating?: string,
  c_runtime?: string
}

export function MovieCard(props: CardProps): JSX.Element {
  // type asserting unknown because I know it will contain Movie entity
  const movie = props.result.rawData as unknown as Movie;

return (
    <div className='w-64 h-96 flex flex-col rounded-lg relative group' >
      <div className='w-full h-96 bg-cover rounded-lg shadow-movie' style={{ backgroundImage: `url(${movie.c_poster?.url})` }}/>
    </div>
  );
}

I also want to change how my movie search result cards are organized when they appear in a universal search. Universal search results are laid out in vertical search sections. For example, search results for ‘the matrix’ will return a Movies vertical section containing the Matrix result card followed by an Actor vertical section containing the Keanu Reeves, Carrie-Anne Moss, and Laurence Fishburne result cards.

VerticalResults.tsx is where the results for each vertical section of the universal search results are rendered. I’m going to add a field to the VerticalResultsCssClasses interface called container and modify the resultsClassNames object in the VerticalResultsDisplay component to include the container field.

// VerticalResults.tsx

export interface VerticalResultsCssClasses {
  results___loading?: string,
  container?: string // Added to existing component
}

const builtInCssClasses: VerticalResultsCssClasses = {
  results___loading: 'opacity-50',
  container: '' // Added to existing component
}

interface VerticalResultsDisplayProps {
  CardComponent: CardComponent,
  cardConfig?: CardConfigTypes,
  isLoading?: boolean,
  results: Result[],
  customCssClasses?: VerticalResultsCssClasses,
  cssCompositionMethod?: CompositionMethod
}

/**
 * A Component that displays all the search results for a given vertical.
 * 
 * @param props - The props for the Component, including the results and the card type
 *                to be used.
 */
export function VerticalResultsDisplay(props: VerticalResultsDisplayProps): JSX.Element | null {
  const { CardComponent, results, cardConfig = {}, isLoading = false, customCssClasses, cssCompositionMethod } = props;
  const cssClasses = useComposedCssClasses(builtInCssClasses, customCssClasses, cssCompositionMethod);

  if (results.length === 0) {
    return null;
  }

  const resultsClassNames = cssClasses.results___loading
    ? classNames({ [cssClasses.results___loading]: isLoading }, cssClasses.container) // Added to existing component
    : '';

  return (
    <div className={resultsClassNames}>
      {results && results.map(result => renderResult(CardComponent, cardConfig, result))}
    </div>
  )
}

Now, I can add my MoviesSection component. It is almost identical to the built-in StandardSection component, but I am passing custom container styling to layout my movie cards in a grid rather than a list. I am using Tailwind responsive utility variants to change the number of grid columns based on the size of the screen.

// MoviesSection.tsx

import { VerticalResultsDisplay } from "../components/VerticalResults";
import { SectionComponent, SectionConfig } from "../models/sectionComponent";
import { StandardCard } from "../components/cards/StandardCard";

const verticalResultsContainerCssStyles = { container: 'grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 xl:grid-cols-4 2xl:grid-cols-5 gap-8' }

const MoviesSection: SectionComponent = function (props: SectionConfig): JSX.Element | null {
  const { results, cardConfig, header } = props;

  if (results.length === 0) {
    return null;
  }
  const cardComponent = cardConfig?.CardComponent || StandardCard;

  return (
    <section>
      {header}
      <VerticalResultsDisplay
        results={results}
        CardComponent={cardComponent}
        {...(cardConfig && { cardConfig })}
        customCssClasses={verticalResultsContainerCssStyles}
      />
    </section>
  );
}
export default MoviesSection;

In universalResultsConfig.ts, I’ll add my new movie card and section.

// universalResultsConfig.ts

/* 
  Adding a new config for a vertical section looks like:


    cardConfig: {
      CardComponent: [custom card component]
    },
    SectionComponent: [custom section component]
  }

*/

export type UniversalResultsConfig = Record<string, VerticalConfig>;

export const universalResultsConfig: UniversalResultsConfig = {
  movie: {
    cardConfig: {
      CardComponent: MovieCard,
    },
    SectionComponent: MoviesSection
  }
}

I added some white-colored box shadow to my movie cards to give them a glowing effect. I won’t be able to see the effect on a white background so I’m going to change the background color of the body of the entire application in tailwind.css using the custom color I defined in tailwind.config.js earlier.

// tailwind.css

@layer base {
  body {
    @apply bg-slate;
  }
}

Now, if I save everything and take a look at my app, my movie results look a lot different than before.

MovieCard Enhancements

I want each MovieCard to show more of the Movie entity fields from my Knowledge Graph. Each time the mouse is hovered over the card, I want the Name, MPA Rating, Runtime, Genres, and Description to appear overtop the movie poster. Tailwind makes it easy to style elements based on the state of their parent element. By adding the group class to the parent element Tailwind classes, changes to the parent element’s state can be used to change the styling of its elements.

I’ve added a div element that is absolutely positioned on top of its parent element (Tailwind classes: absolute top-0 bottom-0 right-0 left-0). It has a gray background color (bg-gray-200), rounded border (rounded-lg), and is invisible (opacity-0). By adding group-hover:opacity-90, the element will go from invisible to visible when the mouse is hovered on its parent element. On hover, the element will transition to being visible over the course of 300 milliseconds at an even speed (transition duration-300 ease-linear). At the same time, the text container div will go from invisible to visible over a slightly longer duration (opacity-0 transition duration-500 group-hover:opacity-100). I have left out some helper functions below for brevity but you can see the whole component here.

const movieCardCssStyles = {
  container: 'w-64 h-96 flex flex-col rounded-lg relative group',
  moviePosterContainer: 'w-full h-96 bg-cover rounded-lg shadow-movie',

  // textPanel and textContainer each have the transition Tailwind classes mentioned in the blog
  textPanel: 'absolute top-0 bottom-0 right-0 left-0 rounded-lg bg-gray-200 opacity-0 transition duration-300 ease-linear group-hover:opacity-90',
  textContainer: 'w-60 px-4 mt-1 mb-2 flex flex-col font-body text-gray-800 absolute opacity-0 transition duration-500 group-hover:opacity-100',

  // the following 4 fields are used by helper functions
  descriptionContainer: 'flex flex-col mt-4',
  descriptionText: 'text-sm',
  headingText: 'font-display text-lg',
  movieInfoList: 'space-x-1 text-sm'
}

export function MovieCard(props: CardProps): JSX.Element {
  const movie = props.result.rawData as unknown as Movie;

    // helper functions

  return (
    <div className={movieCardCssStyles.container} >
      <div className={movieCardCssStyles.textPanel}></div>
      <div className={movieCardCssStyles.moviePosterContainer} style={{ backgroundImage: `url(${movie.c_poster?.url})` }}/>
      <div className={movieCardCssStyles.textContainer}>
        <span className={movieCardCssStyles.headingText}>{movie.name}</span>
        {renderMovieInfo()}
        {renderDescription()}
      </div>
    </div>
  );
}

After saving these changes, I can see my new animation in action:

Actors Cards and Other Styling

For Actor search results, I have created an ActorCard and ActorSection component and added them to the universalResultsConfig.ts. In addition, I added some other minor styling to the application:

Passing sectionHeaderStyles and the ‘assign’ CSS composition method as props to SectionHeader in UniversalResults.tsx
Where AppliedFiltersDisplay is rendered in SectionHeader.tsx, I added cssCompositionMethod as a prop so that I can use the ‘assign’ method when passing the the appiledFiltersConfig prop to UniversalResults in UniversalSearchPage.tsx
Added nlpFilter styling and the ‘assign’ CSS composition method to the universalResultsFilterConfig that is passed as the appliedFiltersConfig prop to UniversalResults in UniversalSearchPage.tsx
Passing custom styling to the DirectAnswer component in UniversalSearchPage.tsx

Running the same test searches I tested in the platform earlier, I can see all of the UI changes I have made to the cloned repo:

Next Steps

I have hosted the code for this project here and the live version of the app here.

At this point, I have added a second search vertical to my Answers configuration and my own React web application for surfacing search results. However, I only have 10 Movies and 30 Actors in my Knowledge Graph. Next, I’m going to use a Data Connector and a Typescript plugin function to add hundreds of more entities to my KG. In the UI, I’m going to add individual vertical sections so that users more easily filter on the results they are looking for. Stay tuned!

Building Modern Search with Yext: Part 1 - Getting Started

Aaron Pavlick — Thu, 03 Feb 2022 14:54:42 +0000

It’s pretty hard to find a website that doesn’t have a search bar somewhere. Sometimes it’s front and center, and other times it’s behind a 🔎 in the upper right hand corner. Either way, you probably use them often when searching the web. But have you ever thought about what goes into building that search experience? I know I didn’t until working on a web application at a previous job.

We used an Apache Solr search server indexed with production data so that users could quickly find what they were looking for. The problem was that every time our PM put in a feature request regarding a change to the search experience, the development process looked something like:

Update the Solr document schema
Update the ETL that indexed the data
Refactor the Java-Spring Boot API that we had sitting between Solr and our UI
Refactor the React-Redux UI to account for changes to the API

I tried to create the most concise list I could for the sake of this guide, but each step could take multiple days depending based on different factors.

As a Developer Evangelist at Yext, I want to show developers that there’s an easier way to build search-based applications. This is the first in a multi-part series around building a modern search-based web application with the Yext Platform utilizing data from IMDB.

Setting up an Account

First, I created an account on Yext Hitchhikers. Hitchhikers is the Yext learning platform where you can learn everything you need to know about our AI search platform. After I’ve created my Hitchhikers account, I will create a Playground account to begin designing my search engine.

Building a Knowledge Graph

For this example, I’m going to create a search experience based on movie information from IMDB. Yext accounts come with a bunch of pre-defined entity types, but I need to create a custom Movie entity.

After creating my entity type, I need to add some fields that I will eventually use to search my data and view in my UI. The ID and Name fields are required, but beyond that I could add whatever schema I want to each type. For now, I am also going to add the Custom Fields 'Tagline' and 'Genres'. 'Tagline' is generally a shorter string so I’ll set it to the type Single-Line Text. I’m also going to add the built-in 'Description' field.

A movie could have multiple genres so I need to make 'Genres' a text list field. I can do this by selecting the Single-Line Text type, but I’ll also select “Make it a list” so that it can contain an array of strings.

There’s a variety of additional standard field types I could use and I can also create my own custom field types. Now that I’ve created a my custom entity type configuration, I’ll upload 10 entities I have stored in a CSV file.

There are a variety of different ways to add entities to a Knowledge Graph, such as by manually adding individual entities, using one of the pre-built API integrations (Twitter, Shopify, etc.), or building a custom API connector.

Creating an Answers Experience

Having added a few different movies to my Knowledge Graph, I need to create an Answers experience to enable search. An Answers Experience is a search experience powered by Yext Answers. What sets Answers apart from Lucene-based search engines is that it leverages Natural Language Processing (NLP), which uses artificial intelligence to put text or speech into context. I only have a few movies with a few fields in my Knowledge Graph, but that’s enough to show off a bit of what Answers can do.

I navigate to the Answers section of my account and click on Create Answers Experience. From here, I name my Answers experience and select the entity I want to search on. I only have Movie entities right now, but I could eventually add new entities like Actors or Directors to expand my search capabilities.

Customizing My Answers Experience

Now that I’ve created my Answers experience, I need to add a bit of backend configuration. Every search result that is returned by the Answers API is part of a search vertical.

So what is a search vertical? When I go to Google and enter a search query, I am automatically directed to the All results page, but I have the option of selecting from different verticals including Images, Shopping, Maps, Videos, and More.

Answers allows me to configure my own verticals that can each have different entities and configurations. I only have movie entities right now, so a movie vertical was created by default. From here, I’ll set a few configuration options to get my search working the way that I want.

When I first look at the configuration options for my vertical, see that Entity Type and Name are included as searchable fields by default.

The Entity Type is automatically included as an NLP feature because in the case that a user queries “movies”, I want only Movie results to be returned. If I had other entity types in my Knowledge Graph, I would want those entity types to be be filtered out of my search results.

The 'Name' field, on the other hand, should be kept as searchable by ‘Semantic Text Search’. Semantic Text Search uses BERT, Google’s open-source machine learning framework for NLP, to represent queries as embeddings. Instead of looking for overlapping keywords, Semantic Text Search allows Yext Answers to analyze the meaning behind a query and uses neural networks find the entities that have the most relevant answer. Some notes on the other fields:

'Genres' - Since a movie might have 1 or more genres, I have marked it as an NLP filter and facet field. This means that when I search for “action movies”, the Answers algorithm will filter out any non-action movies and will return additional facets I could apply after my initial search like “Adventure” or “Comedy.”
'Tagline' - Movie taglines are usually just short catchphrases associated with a film so phrase match and text search are appropriate.
'Description' - I used the built-in ‘Description’ field for the movie description because it can handle multi-line text containing a few sentences. The Document Search algorithm is applied by default because it knows how to search for relevant text snippets from the description.

I can test my search configuration by either using the Experience Preview within my Yext Account UI or by dropping this cURL command into Postman to see everything that’s returned by the Answers API each time a query is made.

curl --location --request GET 'https://liveapi-sandbox.yext.com/v2/accounts/2700040/answers/query?experienceKey=movies-search&input=woody and buzz&api_key=cb8b942209662817e117b4d037e85f6c&v=20211012'

Clone and Modify Answers Sample Repo

Now that I have my backend configured the way that I want, I need to start building my search UI. Yext offers a low-code solution for building branded search experiences, but I want more control over the look and feel of my site. I’ll use the React starter application that is designed to work with Answers Experiences. First, I’ll fork the project into my personal Github. Then, I’ll clone it to my machine and rename it.

git clone https://github.com/yext/react-site-search-starter.git movies-answers-part-one

To display search results from my Answers experience in my web app, I’ll first modify answersHeadlessConfig.ts with my API key and experience key. Both can be found by navigating to the Experience Details page within a Yext Account.

Since I am using a sandbox account, I also need to add the optional endpoints field to my configuration with the sandbox API URLs. Otherwise, the app will use production endpoints by default.

// answersHeadlessConfig.ts
import { AnswersHeadlessProvider } from '@yext/answers-headless-react';

type HeadlessProviderProps = Parameters<typeof AnswersHeadlessProvider>[0];

export const answersHeadlessConfig: HeadlessProviderProps = {
  apiKey: 'cb8b942209662817e117b4d037e85f6c',
  experienceKey: 'movies-search',
  locale: 'en',
  sessionTrackingEnabled: true,
  endpoints: {
    universalSearch:
      "https://liveapi-sandbox.yext.com/v2/accounts/me/answers/query?someparam=blah",
    verticalSearch:
      "https://liveapi-sandbox.yext.com/v2/accounts/me/answers/vertical/query",
    questionSubmission:
      "https://liveapi-sandbox.yext.com/v2/accounts/me/createQuestion",
    status: "https://answersstatus.pagescdn.com",
    universalAutocomplete:
      "https://liveapi-sandbox.yext.com/v2/accounts/me/answers/autocomplete",
    verticalAutocomplete:
      "https://liveapi-sandbox.yext.com/v2/accounts/me/answers/vertical/autocomplete",
    filterSearch:
      "https://liveapi-sandbox.yext.com/v2/accounts/me/answers/filtersearch",
  },
};

Since I only have one search vertical, I’ll remove most of the code in universalResultsConfig.ts and routeConfig.tsx. I can come back to these later once I have to account for new verticals I create later on.

// routeConfig.tsx
import UniversalSearchPage from '../pages/UniversalSearchPage';
import { universalResultsConfig } from './universalResultsConfig';

export const routeConfig = [
  {
    path: '/',
    exact: true,
    page: <UniversalSearchPage universalResultsConfig={universalResultsConfig} />
  },
];

// universalResultsConfig.ts
import { VerticalConfig } from '../components/UniversalResults';

export type UniversalResultsConfig = Record<string, VerticalConfig>;

export const universalResultsConfig: UniversalResultsConfig = {}

Running npm start in the terminal runs my app locally in the browser. Once the page loads I can try out a few queries. You can checkout the React frontend code for this guide here. In a future post, I’ll make stylistic and layout changes to my application.

As you can see in the video above, the 10 movies I added to my Knowledge Graph appear when I load the page. I tried a few different queries to narrow down the results:

“The Matrix” - This is an exact match of the name of one of the movies in my Knowledge Graph, so it’s the only result that’s returned.
“Family Movies” - “Family” matches with one of the genres that “The Iron Giant” and “Toy Story 2” have, and genre is an NLP filter; therefore, they’re the only movies that are returned.
“Tatooine” - This is a string that is contained in the description of “Star Wars: Episode I - The Phantom Menace.” I turned on Document Search for the movie description field so the Answers algorithm was able to associate my query with a search result.

Next Steps

Right now, I only have a few search results of one entity type appearing on a plain white screen. In my next post, I’m going to add some more entity types so that I can get some more interesting search results and give my UI a more personal touch. Stay tuned!