contentful-hooks v1.0.8
Contentful hooks
The goal of the Contentful hooks is to fetch data from Contentful, and transform Contentful objects from response, into more simple ones.
What hooks also do, is appling localization, so at the end, they return content in specific locale for specific country.
Response is also filtered by tags.
Hooks contain of two main methods: useContentfulQuery() and transformContentfulData().
useContentfulQuery()
useContentfulQuery() is used for fetching entries from Contentful. Call to the Contentful is wrapped into the TanStack Query hook. This method requires next parameters to be sent:
- queryParams - object that contains:
- search parameters for filtering and querying Contentful objects (for example sys.id, content_type etc)
- include - specify the number of levels to resolve (maximum number is 10)
- locale - locale in the format language-COUNTRYCODE (example: en-NL, nl-NL etc..)
- contentfulConfig - object that contains:
- contentfulSpace - 'Namaste' for example
- contentfulAccessToken
- contentfulHost - 'cdn.contentful.com' (delivery API) or 'preview.contentful.com' (preview API)
- options - object that contains anything from the available options for the TenStack Query requests useQuery except queryKey and queryFn since this data is generated based on the queryParams and contentfulConfig params.
This method returns response from the TenStack Query requests useQuery where the data will be response from the Contentful library call.
Also it is necessary to wrap the coponent, components or whole app in the QueryClientProvider and pass the parameter client which is new instance of QueryClient. Guide how to set it up, can be found in this simple example.
contentfulTransformation()
transformContentfulData() is used for transforming fetched entries.
This is a recursive method for transforming Contentful objects into localized, more simple ones. Localization can be based on: country, language and locale or all together - based on the modeled objects.
Method requires next parameters to be sent:
- locale - locale in the format language-COUNTRYCODE (example: en-NL, nl-NL etc..) - mandatory parameter
- contentfulResponseData - data from the response of the useContentfulQuery() hook - mandatory parameter
- contentfulConfig - configuration of contentful (token, space, environment, host) - please check the explanation bellow for skipMappingOfPreviewData attribute
- tags - array of tags, which contentful models will be filtered by needs to have (for example- spacewebmobile, spaceweb etc)
- skipMappingOfPreviewData - flag for enabling/disabling mapping of data for preview. By default it is set to false. ***
*** If skipMappingOfPreviewData is false, it is necessary to pass contentfulConfig as well. By providing these 2 values, the primitive type values of the fields will transform into the object that contains:
- contentfulId - id of the contentful component where the field can be found
- contentfulType - type of the contentful component where the field can be found
- value - primitive type value of field
- contentfulLink: - link to the Contentful where the field can be found (https://app.contentful.com/spaces/${contentfulConfig.space}/environments/${contentfulConfig.environment}/entries/${contentfulId})
- contentfulAttributeName - name of the field
contentfulTransformation() returns simple object that contains only localized Contentful content. This content is also filtered by tags. Objects "metadata" and "sys" are removed after transformation, and all content from fields object is moved to top level (parent object). If previewing is enabled, method also saves some additional info needed for previewing, like ids of elements.
Please also refer to Contentful library and TanStack Query.