Skip to main content

Properties

The properties method is where you define the output that goes into the view you fetch from the Delivery API

Properties example
properties: function (sourceEntity, context) {
  return {
    title: sourceEntity.properties.title,
    seo: {
      title: sourceEntity.properties.seoTitle,
      description: sourceEntity.properties.seoDescription,
    }
    categoryIds: sourceEntity.properties.categoryIds
                                .map(categoryId => parseInt(categoryId))
  };
}

The properties method must return an object with the data you want to include in your view.

PropertiesContext object

The PropertiesContext object is passed into the properties method and gives you access to a set of methods described below.

Methods​

MethodDescription
lookupLookup allows you to search source entities using a filter string and work with the source entities directly in the schema.
partialReferencing a partial schema. Mapped data from a partial schema is embedded into the calling schema.
referenceReferencing a full schema. References to other schemas are resolved on delivery request time.

lookup​

Lookup source entities.

Lookup allows you to search source entities using a filter string and work with the data from the source entities directly in the schema.

Note the lookup is an async function so you have to use async/await when you are using the lookup function.

lookup(filter)

note

The lookup function is limited to a maximum number of items to return, based on the tenant plan. It can however be increased per tenant basis. Please reach out to Enterspeed if needed.

The default limits are:

  • Free & Premium plans: 100 items
  • Enterprise plan: 500 items

Parameters​

ParameterTypeDescription
filterstringA filtering criteria. See list of filter examples
lookupOptionsobjectAn optional object with the following structure:
{ excludeProperties?: boolean; }

If excludeProperties is set to true the lookup will only return the base fields of the source entities and not all custom properties. This will help improve performance if you don't need the custom properties, but only some of the base fields like originId, originParentId, url

Required function calls​

After the lookup function it's required to call toPromise to excecute the query and return a promise.

toPromise

Using the toPromise function excecutes the query and return a promise you must resolve.

look toPromise
const newsArticles: await context
                .lookup("type eq 'newsArticle'")
                .toPromise()

Optional function calls​

To filter the source entities even further you can call some of the following optional functions.

limit

The limit function limits the number of source entities.

Parameters​

ParameterTypeDescription
limitnumberThe maximum number of source entities to return.
look and limit
const newsArticles: await context
                .lookup("type eq 'newsArticle'")
                .limit(5)
                .toPromise()
orderBy

The order sequence of the source entities.

Parameters​

ParameterTypeDescription
orderBy{ propertyName: string, direction: "asc" | "desc" }Allows you to specify your desired sorting order.
lookup and orderBy
const newsArticles: await context
                .lookup("type eq 'newsArticle'")
                .orderBy({ propertyName: "properties.createdDate", direction: "desc"})
                .toPromise()
sourceGroup

The sourceGroup function lets you specify the source group. By default the source group of the current source entity is used.

Parameters​

ParameterTypeDescription
sourceGroupstringAllows you to define a different source group. The sourceGroupAlias should be equal to the desired source group alias where you want to look for source entities.

If not defined, it uses the current source group.

lookup and sourceGroup
const newsArticles: await context
                .lookup("type eq 'newsArticle'")
                .sourceGroup("anotherSourceGroup")
                .toPromise()

Examples​

lookup with async/await
properties: async function (sourceEntity, context) {
  const latestNews = await context
                          .lookup("type eq 'newsArticle'")
                          .orderBy({ propertyName: "properties.createdDate", direction: "desc"})
                          .limit(3)
                          .toPromise();

  const mappedNews = latestNews
                  .map((news) => ({
                      url: news.url,
                      title: news.properties.title,
                      teaser: news.properties.teaser
                  }));

  return {
    latestNews: mappedNews
  }
}
lookup without custom properties
properties: async function (sourceEntity, context) {
  const baseNewsArticles = await context
                          .lookup("type eq 'newsArticle'", { excludeProperties: true })
                          .limit(3)
                          .toPromise();

  const mappedNews = baseNewsArticles
                  .map((news) => ({
                      originId: news.originId,
                      url: news.url
                  }));

  return {
    latestNews: mappedNews
  }
}

partial​

Referencing a partial schema.

The partial mapping property type allows for dynamically including partial schemas into the main schema. This is useful when you need to iterate an array of different objects that has an identifier, like an ID, alias or similar.

tip

Partial schemas are typically used when you want a reusable schema for mapping data that is part of the same entity. E.g. if metadata (title, description, etc.) is the same across different entity types, but the data lives on the entity itself.

Read more about partial schemas here

partial(schemaAlias, input)

Parameters​

ParameterTypeDescription
schemaAliasstringThe alias of a partial schema.
inputobjectYou can pass whatever data you need for your partial schema.

Examples​

partial
contentBlocks: sourceEntity.properties.contentBlocks.map((contentBlock) =>
    context.partial(`block-${contentBlock.contentType}`, contentBlock)
  )
passing extra properties to the partial schema
contentBlocks: sourceEntity.properties.contentBlocks.map((contentBlock) =>
    context.partial(`block-${contentBlock.contentType}`, {
        block: contentBlock,
        pageOriginId: sourceEntity.originId
      })
  )

The input defines what goes into the partial schema and can be any custom object, and the schemaAlias is used to resolve what partial schema to use. So, in this case, we could have a partial schema with an alias: block-headline.

reference​

The reference are used to reference other views created from either this source entity or another source entity.

When referenced, Enterspeed will resolve the view when requested by the Delivery API so that the data will stay up-to-date if a reference view is updated.

The reference function is the starting point where you can use our fluent API to configure the reference(s) you want (by filter, by originId, take only top 5, and so on).

tip

Reference schemas are typically used when you are mapping data from another entity. E.g. a page has a reference to another page entity or media entity.

Read more about reference schemas here

reference(schemaAlias)

Parameters​

ParameterTypeDescription
schemaAliasstringThe alias of a schema.

Required function calls​

After the reference function it's required to call one of the following functions to define what source entities you want references to.

byOriginId

Using the byOriginId function lets you create a reference to a source entity by its oringinId.

Parameters​

ParameterTypeDescription
originIdstringThe original id from the source system.
reference by byOriginId
contentTeaser: context
                .reference("contentTeaser")
                .byOriginId(sourceEntity.properties.link.id)
byOriginIds

Using the byOriginIds function lets you create a references to a list of source entity by their oringinId.

Parameters​

ParameterTypeDescription
originIdsstring[]A list of original ids from the source system.
reference by byOriginIds
contentTeaser: context
                .reference("contentTeaser")
                .byOriginIds(sourceEntity.properties.links.map(link => link.id))
children

The children function creates a reference to all the children of the current source entity. It's basicly a shortcut for .filter("originParentId eq '{sourceEntity.properties.originId}'").

reference by children
childPages: context.reference("page").children()
reference by children and type
childPages: context.reference("page").children("type eq 'subpage'")
note

The children function is limited to a maximum number of items to return, based on the tenant plan. It can however be increased per tenant basis. Please reach out to Enterspeed if needed.

The default limits are:

  • Free & Premium plans: 100 items
  • Enterprise plan: 500 items
filter

Using the filter function lets you do a dynamic search for source entities you want to make references to.

Parameters​

ParameterTypeDescription
filterstringA filtering criteria. See list of filter examples
reference by filter
newsTeasers: context
              .reference("newsTeaser")
              .filter("type eq 'newsArticle'")
note

The filter function is limited to a maximum number of items to return, based on the tenant plan. It can however be increased per tenant basis. Please reach out to Enterspeed if needed.

The default limits are:

  • Free & Premium plans: 100 items
  • Enterprise plan: 500 items
parent

The parent function creates a reference to the parent of the current source entity. It's basicly a shortcut for .filter("originId eq '{sourceEntity.properties.originParentId}'").

reference by parent
parentPage: context
              .reference("page")
              .parent()
self

The self method creates a reference to a view created by the specified schema on the current source entity. The helper method is equivalent to calling .byOriginId(sourceEntity.originId).

reference by self
selfPage: context
              .reference("page")
              .self()

Optional function calls​

To filter the source entities you are making references to even further you can call some of the following optional functions.

limit

The limit function limits the number of references.

Parameters​

ParameterTypeDescription
limitnumberThe maximum number of references to return.
reference by filter and limit
topFiveNewsTeasers: context
                      .reference("newsTeaser")
                      .filter("type eq 'newsArticle'")
                      .limit(5)
orderBy

The order sequence of references.

Parameters​

ParameterTypeDescription
orderBy{ propertyName: string, direction: "asc" | "desc" }Allows you to specify your desired sorting order.
reference by filter and orderBy
newsArticles: context
                .reference("newsArticle")
                .filter("type eq 'newsArticle'")
                .orderBy({ propertyName: "properties.createdDate", direction: "desc"})
sourceGroup

The sourceGroup function lets you specify the source group. By default the source group of the current source entity is used.

Parameters​

ParameterTypeDescription
sourceGroupstringAllows you to define a different source group. The sourceGroupAlias should be equal to the desired source group alias where you want to look for source entities.

If not defined, it uses the current source group.

reference by filter and sourceGroup
newsTeasers: context
              .reference("newsTeaser")
              .filter("type eq 'newsArticle'")
              .sourceGroup("anotherSourceGroup")
first

The first function return the first item in the result set. The item i returned as an object instead of an array with one item.

The function must always be called as the last call in the chain.

reference to the first news teaser
newsTeaser: context
              .reference("newsTeaser")
              .filter("type eq 'newsArticle'")
              .orderBy({ propertyName: "properties.createdDate", direction: "desc"})
              .first()

Examples​

Property type: reference (static value) with originId
seoData: context.reference("seo").byOriginId(sourceEntity.originId)
reference by filter and sourceGroup
products: context
            .reference("product")
            .filter("type eq 'product'")
            .orderBy({ propertyName: name, direction: "asc"})
            .limit(10)
            .sourceGroup("commerce")

The schemaAlias can either be a static value, like "seo", or it can be a dynamic value being resolved from the Source Entity that is being processed by Enterspeed. This allows for supporting almost any use case.

Reference response​

The response of references differs in V1 and V2+ of the delivery API. V1 return the id, type and wraps the properties from the referenced view in a view property. The response of references in V2+ is much cleaner and only returns the actual properties from the referenced schema. If a reference is not found in V2+, the reference information is added in the missingViewReference property in the meta object for debugging purpose.

Delivery API V1 uses a nested view property
{
  // This example shows a response of a view with two schema references.
  // image1 is referencing a found view with a url and name property
  // and image2 is referencing a view that doesn't exist.

  "meta": {
    "missingViewReferences": []
  },
  "route": {
    "image1": {
      "id": "gid://Environment/8ef2bdc0-c352-4190-a344-c51d1f5e72ea/Source/dc5d9518-b96a-428a-a9b3-31fb601376c2/Entity/1234/View/image",
      "view": {
        "url": "https://test.com/how-to-write-a-good-blog-post.png",
        "name": "How To Write A Good Blog Post"
      },
      "type": "ViewReference"
    },
    "image2": {
      "id": "gid://Environment/8ef2bdc0-c352-4190-a344-c51d1f5e72ea/Source/dc5d9518-b96a-428a-a9b3-31fb601376c2/Entity/1235/View/image",
      "view": null,
      "type": "ViewReference"
    }
  }
}
Delivery API V2+ only returns the actual view properties
{
  // This example shows a response of a view with two schema references.
  // image1 is referencing a found view with a url and name property
  // and image2 is referencing a view that doesn't exist.

  "meta": {
    "missingViewReferences": [
      {
        "path": "image2",
        "viewId": "gid://Environment/8ef2bdc0-c352-4190-a344-c51d1f5e72ea/Source/dc5d9518-b96a-428a-a9b3-31fb601376c2/Entity/1235/View/image"
      }
    ]
  },
  "route": {
    "image1": {
      "url": "https://test.com/how-to-write-a-good-blog-post.png",
      "name": "How To Write A Good Blog Post"
    },
    "image2": null
  }
}