Going beyond the basics with Contentful
If you’re a frontend developer working on an application or two, you’re likely juggling several different systems at any given time. It can be overwhelming or challenging to stay on top of your projects. Is there a better way to do things? Most certainly, yes.
As someone who enjoys getting hands-on with various technologies and sharing useful project outcomes with the community, I find it rewarding to encourage curiosity and exploration. In this post, I’m going to explain some of the really cool things you can do when you go beyond the basics with Contentful.
Join me as we take a quick tour through composable architecture, the App Framework, fresh updates to the GraphQL API, and tips for implementing our new live preview feature.
Implementing composable architecture: Using cross-space references and content orchestration
First up, composable architecture. What is it? Composable architecture gives you the ability to reuse and combine multiple microservices into one unified platform.
In application development, you might be dealing with a variety of systems such as a content management system (CMS), a digital asset management (DAM) system, a product inventory management (PIM) system, enterprise content management (ECM), and so on. The type of application you’re building will determine the systems you use. With multiple applications come multiple APIs, each with its unique structure, which may require mapping for compatibility. Adding to this complexity is the need to publish across multiple channels.
The Contentful approach to implementing a composable architecture is to provide a platform that facilitates the combination of content from all these diverse systems.
Cross-space references
The first step in our approach is to enable content referencing from various spaces within Contentful. For those unfamiliar, let’s briefly discuss ‘spaces.’ Upon signing up to Contentful, you have a platform which consists of multiple spaces. These spaces function as separate workspaces, each potentially corresponding to a different application you’re building. Alternatively, they can correspond to different components within a single application.
It isn’t uncommon for users to utilize multiple spaces for a single application, pulling content from these various spaces into their website. To avoid repeated calls to different spaces for content referencing, we introduced cross-space references. With cross-space references, it becomes easier to manage projects where different teams are working in different spaces.
Imagine a scenario where you have multiple projects, and a single legal team manages standard elements, like terms and conditions or privacy policies, across all these projects.
In an ideal world, this information remains consistent across all applications. You could technically create a unique content model and manually enter these details into different spaces for each project, but this isn’t efficient. Any changes would require updating across all spaces, which can be chaotic. Cross-space references solve this issue.
With this feature, the legal team maintains their content in a dedicated space, and you simply reference that information in your own space. Consequently, you’re free from concerns about tracking changes; the legal team handles all updates, and these are automatically reflected in your web application. This is the core concept of cross-space references.
With cross-space references, you can reference entries from one space to another. Currently, you can link content from three additional spaces to your main one, totaling four spaces. This relationship is represented by a resource link. While it’s not pertinent to delve into the technical specifics of implementation here, it’s worth noting that each space requires a token. These tokens must be converted into a string and passed into headers, a process for which we’ve provided detailed documentation.
Third-party orchestration
The next key feature is content orchestration. This function facilitates the importing of content from various platforms, eliminating content repetition and simplifying the developer’s task by eliminating the need to manage multiple APIs.
Content from external sources can be referenced, promoting content reusability, and all this is achievable with a single API call, removing the need to query data on different platforms.
We’ve successfully implemented this feature in Shopify and in commercetools, too. To illustrate how content orchestration works, let’s perform a quick GraphQL call using my Shopify store as an example.
I’m a big fan of Pokémon. For the purpose of this demonstration, let’s imagine I want to create a website for my Pokémon shop, with references to them in blogs and other content. In my Contentful platform, I’ve already integrated the Shopify app and established a content model that references the product from Shopify. A title field has been added for this reference.
Let’s head over to the GraphQL playground to query this information. When I query for the product, I receive the product ID.
Ideally, I wouldn’t want to make a separate call to the Shopify API using this product ID. So, we’ve integrated the Shopify API within Contentful. I can append product with __data, then pass on the required information.
Upon requesting title and description data, I receive the information directly from Contentful, without needing to make a call to Shopify. Instead, I instruct Contentful on the information I require from Shopify, and it retrieves it for me. This eliminates the need for multiple API calls, achieving the desired result in just a single call. This is an example of content orchestration with Shopify.
For those intrigued by content orchestration, it’s worth noting that this feature is available via our Early Access Program. If you’re interested in trying it out on your project, simply follow this link and complete the form — our team will then get in touch to provide access.
Currently, content orchestration is only enabled for the Shopify and commercetools apps, both specifically designed to import content from various platforms. This leads us to the App Framework, which I like to think of as a package that empowers you to create your own custom apps within Contentful.
New capabilities with changes to the GraphQL API
Something that particularly excites me is the changes we made to our GraphQL API.
If you’ve used Contentful before, you’ll know that using the GraphQL API could be challenging, particularly when dealing with relational or nested filtering, which wasn’t previously possible. This meant that you had to retrieve all data and manage it yourself due to the GraphQL API’s complexity.
However, I’m delighted to announce that we now support multi-level filtering, including relational filtering. For instance, if you have a list of blog posts authored by multiple individuals and you want to filter for posts written by an author named Harshil, this is now achievable.
Earlier, you were unable to perform this kind of filtering at the top level; you can now do so in the blog collection level by specifying ‘where author is Harshil,’ for example, to retrieve all blog posts written by Harshil. This is known as relational filtering.
Nested filtering is also now possible. Let’s assume you want to retrieve only certain tags (JavaScript for this example) from your blog posts collection. You can dive into the tags collection field and apply your filters there, making the GraphQL API more developer-friendly.
The above query will fetch all the blog posts and return only the JavaScript tag.
Implementing live preview for real-time updates
Another exciting development is the live preview feature. This highly requested feature is now available, much to the delight of many users. It enables you to preview content within Contentful, directly on your website.
This new feature allows you to preview your content directly within Contentful, even though your website, CSS, and frontend remain separate. There’s no need to establish a separate environment or perform additional publishing and building steps to preview your content. Moreover, it supports real-time updates.
To illustrate this, let’s consider a quick demo. I have a space with an entry related to Stockholm, filled with some random content. I’ve already configured the live preview, so clicking ‘open live preview’ displays the website just as it is. If I navigate to localhost 3000, that’s exactly how my website appears.
The live preview feature can be configured for any website, whether it’s locally hosted or a live production site. You can view and edit the content directly, with changes reflected in real time. For instance, if I add an exclamation mark to my content, the update is immediately visible.
This feature also includes an ‘inspect’ option. This is particularly useful if you’re unsure about certain content elements. For example, if you’re uncertain where a specific date is located, the ‘inspect’ function can help identify it.
The inspector mode simplifies the process of locating and adjusting content. By enabling it, you get an edit button for all fields. Clicking on it navigates directly to the selected field. For instance, if you want to alter a date, you can directly access and modify it, with changes reflected live. However, it’s worth noting that while these updates are visible in real time, they remain in draft state and are not published. For these changes to go live, you must publish them.
Implementing this feature is straightforward with the live preview SDK that we provide. While the code I’ve discussed pertains to a Next.js app, the SDK is compatible with any frontend framework you’re using.
In my setup, I’ve configured a provider with several flags. I’ve specified the locale as English U.S. and enabled both the inspector and live update modes. For troubleshooting, I’ve also turned on the debug mode.
As I’m utilizing GraphQL and wish to incorporate its features, it’s necessary to pass on the type name for each of my fragments. When using the GraphQL API, including the type name allows you to obtain the type of any given field, which is essential for accurate data manipulation.
Once the typename is included, all that’s left is to pass the ‘Contentful live preview’ attribute, ‘get props,’ and then pass the ID and field. This informs Contentful precisely which field is being referenced. For instance, in the case of the body, I pass the ‘Contentful live preview’ attribute and the ‘get props,’ which include the entry ID and field ID (in this case, ‘content’).
Detailed information is available in our documentation, and one of our engineers who worked on the live preview feature published a blog post explaining how to implement it. While I’ve provided an overview, this blog post delves deeper into how it works. If you’re keen to learn more, I encourage you to read it.
Wrapping up
To recap, our ongoing efforts are aimed at facilitating the management and publication of your content from various platforms and within different spaces in Contentful. We’ve also introduced new capabilities to the GraphQL API. Finally, the live preview feature is available to all users, enabling you to visualize, edit, and observe real-time changes to your content directly within Contentful.
For those with queries or comments, joining our community Discord offers an excellent opportunity to interact with others, ask and answer questions, help the community, and learn about various Contentful uses. See you there!
