Although this project is used in a production environment, some featrues still request thoroughly testing, and some behaviors are subject to change. Since 1.0.0 it has some breaking changes.
Developed under NodeJS 6.x with ES6 features: arrow function, class, object literals, promise, spread operator. Please find a compatible node version from http://node.green/.
Install the connector for your project.
$ npm install loopback-connector-contentful --savevar contentful = app.datasources['contentful'];
contentful.isActual(function(err, isActual) {
if (!isActual) {
contentful.autoupdate(function(err, result) {
});
}
})Only one space can be connected with each datasource definition. Previously aimed to support multiple spaces with a single datasource, however this adds complexity to the logic.
"contentful": {
"name": "contentful",
"connector": "contentful",
"spaceId": "<space id>",
"locale": "en-US",
"respectContentfulClass": false,
"uniqueBy": "name",
"accessTokens": {
"delivery": "<access token>",
"management": "<access token>",
"preview": "<access token>",
}
}| Property | Options | Default | Description |
|---|---|---|---|
| accessTokens | string | {} | If string is provided, it will be treated as |
|
| respectContentfulClass | bool | false | If set to true, this module will return objects of underlying contentful library directly. It is recommended to set to false, and let this module help you do the model transformation according to loopback model definition. |
| uniqueBy | "id" | "name" | "id" | Since contentful SDK starts supporting creating content type with id, now id can be used to map LoopBack models and content types, rather than by content type name. The camel case of LoopBack model name will be used as content type id implicitly, otherwise please specify id in LoopBack model definition. |
When saving or retrieving a model, its local is resolved in the following order:
- Use locale defined in model-config.json.
- Use locale defined in datasources.json.
- If locale is not defined above, use the default locale of the space to save and retrieve models from contentful
{
"name": "Product",
"options": {
"contentful": {
"id": "<content type id>",
"name": "Shining Product",
"locale": "en-US",
"displayField": "productName",
"description": "model description for product"
}
},
"properties": {
"productName": "string",
"productDescription": {
"type": "string",
"required": false,
"contentful": {
"name": "Product Description",
"dataType": "Text",
"localized": false,
"validations": [{"size": {"min": 20, "max": 200}}],
"disabled": false,
"omitted": false
}
},
"tags": {
"type": [
"string"
]
}
},
"relations": {
"categories": {
"type": "hasMany",
"model": "Category",
"contentful": {
"name": "Product Categories",
"localized": false,
"validations": [],
"itemValidations": [],
"disabled": false,
"omitted": false
}
},
"brand": {
"type": "belongsTo",
"model": "Brand"
},
"image": {
"type": "hasMany",
"model": "Asset"
},
}
}Content type names and field names are automatically generated with lodash method _.startCase. You don't need to explicitly provide "contentful"."name": "Product Description" for property productDescription.
Relation model Asset is reserved for Contentful Asset content type, no need to define a corresponding Asset model in LoopBack.
!!!Caution: the following behavior is no longer needed if you use "uniqueBy": "id", which is also the default behavior.
Contentful supports duplicated model names within the same space. However this module does not support such behaviour, model names must be unique within a space.
If you just want contentful model name to be different from loopback model name, please define string value for options.contentful.name field:
{
"name": "Product",
"options": {
"contentful": {
"name": "My Product"
}
},
...
}If you want to rename the model, an array of names should be provided to options.contentful.model, such as:
{
"name": "Product",
"options": {
"contentful": {
"name": ["New Name", "Old Name 2", "Old Name 1"]
}
},
...
}- If "Old Name 2" is found in contentful space, it will be renamed to "New Name".
- Else If "Old Name 1" is found in contentful space, it will be renamed to "New Name".
- If both "Old Name 2" and "Old Name 1" are not found, a new model with "New Name" will be created.
| LoopBack Data Type | Contentful Data Type |
|---|---|
| any | Text |
| string | Symbol |
| number | Number |
| date | Date |
| boolean | Boolean |
| geopoint | Location |
| object | Object |
| ["string"] | Array |
For types cannot be mapped implicitly, please use contentful specific settings:
"propertyName": {
"type": "string",
"contentful": {
"dataType": "Text"
}
}| Loopback Relations | Status |
|---|---|
| belongsTo | Implemented |
| hasOne | Implemented |
| hasMany | Implemented |
| hasManyThrough | N/A |
| hasAndBelongsToMany | N/A |
Delivery API should only funciton with get methods. Currently filter._contentfulApifilter.contentful.api is default to management delivery when omitted.
GET api/products?filter={"contentful": {"api": "preview"}, "include":["categories", "brand"]}
| Property | Type | Values | Default |
|---|---|---|---|
| contentful.api | string | "delivery" | "preview" | "management" | "delivery" |
According to loopback document, filter.include must be provided to expose relation fields.
| Connector API | Delivery (Published) | Preview (Draft) | Management (All) |
|---|---|---|---|
| connector.autoupdate | ✓ | ||
| connector.create | ✓ | ||
| connector.all | ✓ | ✓ | ✓ |
| connector.update | ✓ | ||
| connector.updateAttributes | ✓ | ||
| connector.count | ✓ | ✓ | ✓ |
- connector.updateOrCreate (optional, but see below)
- connector.replaceOrCreate (a new feature - work in progress)
- connector.findOrCreate (optional, but see below)
- connector.buildNearFilter
- connector.destroyAll
- connector.save
- connector.destroy
- connector.replaceById (a new feature - work in progress)
The following references are used, while building the module:
- LoopBack Types
- LoopBack Building a Connector
- loopback official connector loopback-connector-mongodb
- contentful management API
- contentful delivery API
- fix content type reference issue internally
- fix versionMissMatch issue, during create content type relations
- model definition keypath change
options.contentful.model=>options.contentful.name - datasource definition changes, as only one space is alowed to be accessed from one datasource.
- add support for preview api
- implemented
connector.updateAttributesmethod, therefore HTTPPATCHmethod is available.
- significant change on datasource.json definition file, to support both delivery API and management API.
- Relations can also be returned when fetch data with delivery API, please check Delivery API.
- fix isActual API bugs, which always return isActual to false when relations are defined for models.
- expose original contentful entries directly without transform, by adding
respectContentfulClass: truein datasources.json. - fix version missmatch issue, when both properties and relations need to be updated for a content type.
- added isActual API to skip autoupdate, when no changes detected.
- prevent belongsTo relations to automatically add foreign keys to content types, such as brandId.
-
loopback does not recoganize text data type, and will prompt error message
Swagger: skipping unknown type "text".. Although it can be ignored, it is recommended to write as below for text:"productDescription": { "type": "string", "contentful": { "dataType": "Text" } }
-
added hasOne relation. Note: hasOne and belongsTo have the same implementation in contentful, they can be treated as alias.
-
Relations now support Asset as model type.
-
relation definitions will implicitly add the specified models to type validations. Categories field can only contains Category model object now:
"categories": { "type": "hasMany", "model": "Category" }
- move all contentful specific options directly under
options: {...}tooptions: { contentful: {...} }, such as spaceId and locale etc. - contentful model name can be different from loopback model name now.
- model display field and description can also be updated now.