When you start using Episerver CMS, you will come across the content reference class very quickly. The content reference class is used to retrieve an Episerver content items unique identifier. The bigger underlining question I think some developers have, is why does Episerver need any object to do this and why can’t I access a page directly via an ID or a code? In today’s guide, I am going to explain why Episerver uses an object and go over some of the benefits of this approach.
In Episerver, we work with content. This content can be pages, blocks, reviews, comments, images, youtube videos… pretty much anything that you want. To get this to work Episerver created the IContent interface. Any content that appears in the CMS must implement this interface. The benefit of IContent is that it gives us, as developers, a lot of flexibility of what content we can work within inside the CMS. Most companies will have their own bespoke services and systems, by providing a standard interface it allows third-party content to be integrated, using content from anywhere we want.
This ability to use multiple data source brings us to the first dilemma… how to design a solution where you work with content that might come from one of multiple data sources. These sources might include different database tables or even third party services, so guaranteeing a single data source between an unlimited number of potential database sources is impossible.
If you look in the content reference properties, you will see a something called ‘ProviderName’. ProviderName is the thing that allows you to choose where you want to get your data from. On most standard Episerver CMS builds that you will work on, you will probably only ever need to use one data source for the content, so it is very likely that you may never come across this property, however, it is a requirement for some sites and the first reason why the content reference is needed.
Content changes; websites are not static entities that you publish once and then that’s it. Some companies have dedicated content teams to constantly update work.
This provides us to the second challenge, if you want to access previous versions of content for whatever reason and you only have a single ID or code, how do you specify which version of the page you want to retrieve?
If you look in the content reference properties, you will see a something called ‘WorkID’. WorkID is the mechanism that tells Episerver the version Id of the content item to use.
The options above are probably more obvious for any developer who has worked with Episerver for a while, but this third consideration may sound a little strange. When I first started using Content Reference to get content out of Episerver, it feels like you might be writing more code than you need to get items out of it. Sometimes you might need to query the database or a config file to get the content reference ID you want to query, then you use the content repository to perform a second query to get the item’s content.
If you have read this article, How Does The Episerver Cache Objects?. I’ve talked about how the API caches items in the background. Episerver caches individual pages in memory. Episerver does not store the navigation hierarchy in memory. Instead, it caches the results of the GetChildren<> command. This data is stored as a list of ContentReferences.
By using the Content Reference object approach, Episerver can implement two kinds of backend caching. One cache that contains the content. The other cache contains a list of references to the content for any items children. When the items are all cached, Episerver can iterate through the list of cached content references and pull all the data back out of the content data cache.
This has two benefits, first, if a content editor updates a page only, that item needs to be refreshed. If Episerver held the whole hierarchy in cache somehow, the whole tree would need to be refreshed whenever a content item was changed (in case it had changed the hierarchy). Instead, only the cache of the GetChildren() would need to be updated.
This process also works the same for adding and accessing content in a content area. A content editor can add blocks or pages into a content area. The cache can then save them as a list of content references. As blocks can live in multiple content areas simultaneously, if the block was updated it only needs to be updated in the data cache and not updated in every content item.