Plugins | Yext Hitchhikers Platform

The Pages 2.0 system allows for executing user-defined code in the context of the plugin ecosystem.

Plugin Events

The plugin ecosystem supports several events which happen at different points of the deploy flow. The currently supported event types are:

OnUrlChange - this event happens whenever the path of a production page changes

{
  "entityId": "[[external entity id]]",
  "locale": "[[entity profile locale]]",
  "url": "[[the new url]]",
  "feature": "[[the feature/template which generated this page]]"
}

OnPageGenerate - this event happens whenever a stream document is processed for HTML rendering

{
  "streamOutput": "[[the document body/entity data]]",
  "feature": "[[the feature/template name]]"
}

API - this event happens whenever a specific path is visited on the site

{
  "urlArgs": "[[map of named url arguments to values]]",
  "userAgent": "[[user agent in the request]]",
  "requestUrl": "[[requested url]]",
  "headers": "[[map of request header name to a list of values]]"
}

Plugin Code

The code executed at each of these event invocations is defined within the site’s repository. The code can be housed in the repository in two different ways:

The code can live anywhere in the repo and be collected during the deploy build phase. This is called a “complex plugin”. Complex plugins can contain several files and are registered in the ci.json file under the artifactStructure.plugins section. Check out this doc for more details on the ci.json file. Here is an example configuration:

"plugins": [
  {
    "pluginName": "Generator",
    "sourceFiles": [
      {
        "root": "dist/plugin",
        "pattern": "*{.ts,.json}"
      },
      {
        "root": "dist",
        "pattern": "assets/{server,static,renderer}/**/*{.js,.css}"
      }
    ],
    "event": "ON_PAGE_GENERATE",
    "functionName": "Generate"
  }
]

Plugins registered here must specify:
- pluginName
- sourceFiles: a list of pattern matchers for all files to include in the plugin context
- event: The event type for which this plugin is used. One of “onUrlChange”, “onPageGenerate”, or “api”
- functionName: The name of the exported function to initially invoke for a plugin invocation
The code can live in a single file in a prescribed directory in the repository. This is called a “simple function”. Simple functions must be a single file and must be in the root level functions/<event_type> directory in the repository. Simple functions must export an entry-point function named main.
- For example, functions/onUrlChange/urlUpdater.ts would create a plugin with the name urlUpdater, the content of urlUpdater.ts as the single source file, the event “onUrlChange”, and the function name ”‘main”.

Back

< Directory Management

Active Deployments >

Feedback

<% elem.innerText %>