Properties
The properties
method is where you define the output that goes into the view you fetch from the delivery API
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
Method | Description |
---|---|
partial | Referencing a partial schema. Mapped data from a partial schema is embedded into the calling schema. |
reference | Referencing a full schema. References to other schemas are resolved on delivery request time. |
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.
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
Parameter | Type | Description |
---|---|---|
schemaAlias | string | The alias of a partial schema. |
input | object | You can pass whatever data you need for your partial schema. |
Examples
contentBlocks: sourceEntity.properties.contentBlocks.map((contentBlock) =>
context.partial(`block-${contentBlock.contentType}`, contentBlock)
)
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).
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
Parameter | Type | Description |
---|---|---|
schemaAlias | string | The 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
Parameter | Type | Description |
---|---|---|
originId | string | The original id from the source system. |
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
Parameter | Type | Description |
---|---|---|
originIds | string[] | A list of original ids from the source system. |
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}'")
.
childPages: context.reference("page").children()
childPages: context.reference("page").children("type eq 'subpage'")
filter
Using the filter function lets you do a dynamic search for source entities you want to make references to.
Parameters
Parameter | Type | Description |
---|---|---|
filter | string | Your filtering criteria. |
See list of filter examples here
newsTeasers: context
.reference("newsTeaser")
.filter("type eq 'newsArticle'")
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}'")
.
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)
.
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
Parameter | Type | Description |
---|---|---|
limit | number | The maximum number of references to return. |
topFiveNewsTeasers: context
.reference("newsTeaser")
.filter("type eq 'newsArticle'")
.limit(5)
orderBy
The order sequence of references.
Parameters
Parameter | Type | Description |
---|---|---|
orderBy | { propertyName: string, direction: "asc" | "desc" } | Allows you to specify your desired sorting order. |
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
Parameter | Type | Description |
---|---|---|
sourceGroup | string | Allows 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.
newsTeasers: context
.reference("newsTeaser")
.filter("type eq 'newsArticle'")
.sourceGroup("anotherSourceGroup")
Examples
seoData: context.reference("seo").byOriginId(sourceEntity.originId)
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.
{
// 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"
}
}
}
{
// 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
}
}