Welcome to Jabberwocky’s documentation!¶

Core Libraries¶

• Jabberwocky.Core
• Jabberwocky.Autofac
• Jabberwocky.Glass
• Jabberwocky.Glass.Autofac
• Jabberwocky.Glass.Autofac.Mvc
• Jabberwocky.WebApi

Extra Libraries¶

• Jabberwocky.Autofac.Extras.MiniProfiler

Code Analysis Libraries¶

• Jabberwocky.Core.CodeAnalysis (for Jabberwocky.Core)
• Jabberwocky.Glass.CodeAnalysis (for Jabberwocky.Glass)

Dependency Graph¶

The naming convention for each project attempts to make clear its dependencies.

For instance, the Jabberwocky.Core library contains no dependencies, and can be included in any standard .NET project.

Similar to the Core project, the Jabberwocky.Autofac project has no external dependencies other than Jabberwocky.Core and Autofac, and by extension, its dependencies (ie. Castle.Core). This means that the Jabberwocky.Autofac project may be used outside of Sitecore projects, wherever IoC may be desirable.

The Jabberwocky.WebApi project also has no dependencies other than on Jabberwocky.Core, and WebApi.

The remaining Jabberwocky.Glass.* projects all rely on Glass Mapper, with each subsequent package relying on more and more dependencies (Autofac, MVC). These packages are meant to bootstrap and codify Sitecore development with a common set of patterns and practices.

Simple Usage¶

Generally speaking, when working in a Sitecore solution, you should consider using the following overload that accepts a string key parameter, and a Func<T> callback parameter:

var returnVal = _cacheProvider.GetFromCache<object>("key", () => obj);

This is the simplest way to cache an item, and will keep the cached item in memory until either:

1. A publish operation occurs, or
2. The .NET runtime is under memory pressure, and the cache item gets evicted automatically

You can also use the asynchronous functions to perform the same function, but instead of blocking on the call, you can await it instead.

var returnVal = await _cacheProvider.GetFromCacheAsync<object>("key", () => obj);

or

var returnVal = await _cacheProvider.GetFromCacheAsync<object>("key", async ct => await GetResultAsync(ct));

Generating a Cache key¶

When choosing a cache key, you should ensure that it is unique to the object being cached, and that it appropriately varies by any contextual values that may affect the result of the callback operation.

For instance, if the object being cached relies on the current user (perhaps via HttpContext.Current.User), then the cache key should include a variable that uniquely identifies that user.

Advanced Scenarios¶

You can also use the provided overloads with an absolute expiration.

For the asynchronous overloads, there is also an optional CancellationToken parameter that you can pass to the GetFromCacheAsync function. If the token is cancelled while the function is being awaited, you can either handle it yourself in the callback, or in the case where the current call is awaiting on the underlying asynchronous lock, the operation will be cancelled.

Be sure to check out the section on Asynchronous Caching for more information on the asynchronous functions, including cancellation.

General Cache¶

The GeneralCache uses .NET’s MemoryCache under the hood, and is thus suitable for a variety of situations. Notably, it has no dependencies on the HttpContext, or System.Web DLL, so it can be used in any type of application.

Site Cache¶

The SiteCache is a singleton implementation of the BaseCacheProvider. It is intended to be used for ASP.NET websites, and provides a handler to clear the entire cache.

This is ideal for Sitecore solutions, where it is desirable to clear the site’s cache on publish.

In the next section, we will take a look at how the SiteCache is extended to work seamlessly with Sitecore out-of-the-box, requiring virtually no setup.

Understanding The Cache Callback¶

It is important to understand how the caching operation works. The BaseCacheProvider implements the reusable caching logic, and so all inheritors also inherit this logic.

When caching an object via one of the caching functions, the cache will attempt to locate the object in the underlying MemoryCache using the provided cache key parameter. If it is found, the cached object is immediately returned, and no further processing is required.

On the other hand, if the object is not found, then the cache will be required to execute the cache callback to calculate the value to be cached. Before this happens, the cache will enter a critical region (by locking on an a temporary cache object, discriminated by the unique cache key parameter).

By wrapping all invocations of the cache callback in a critical region, we ensure that only a single thread can execute the callback at a time, thus causing all other concurrent requests for the same cache key to block.

In most cases, this ends up saving time and resources, as this prevents the expensive callback operation from being called more than once. Intead, all blocking threads will receive the cached result once the initial callback operation completes.

Overview¶

The IAsyncCacheProvider interface exposes the asynchronous caching functions.

Unlike their synchronous counterparts found in the ISyncCacheProvider, these functions all follow the Task-based Asynchronous Pattern (TAP), are are thus Task<T> returning.

Effectively, this means that these functions are all non-blocking, and will all execute asynchronously. Furthermore, this means that each of the asynchronous functions can be awaited with the await keyword.

The benefits to using the asynchronous functions become clear in situations where you may have long-running IO operations (like network calls), or are already executing code in an asynchronous context, and want to prevent blocking on synchronous locks.

Thus, by using the asynchronous caching functions, you gain the benefit of:

1. Non-blocking asynchronous locking
2. Asynchronous cache callback execution

The first point is important to note, because as outlined in the callback documentation, when resorting to executing the callback, the cache will enter a critical region. In an asynchronous execution context, it is important to eliminate blocking calls, as these can (potentially) lead to deadlocks.

Thus, the asynchronous caching functions use an asynchronous locking primitive that does not block the thread.

GetFromCacheAsync¶

There are a few variations on the asynchronous caching functions (ignoring the overloads with expiration):

Task<T> GetFromCacheAsync<T>(string key, Func<T> callback,
        CancellationToken token = default(CancellationToken))

Task<T> GetFromCacheAsync<T>(string key, Func<CancellationToken, Task<T>> callback,
        CancellationToken token = default(CancellationToken))

Regardless of which function is used, they are all asynchronous, and will return a Task<T>. This allows you to await the result of the call asynchronously.

There are two variations that allow you to specify either a synchronous cache callback, or an asynchronous one. While it may seem counter-intuitive to include an asynchronous overload that allows for executing a synchronous callback, the reason for this is to allow you to execute expensive synchronous callbacks, while still allowing you to asynchronously await the caching function.

The primary benefit of doing this is that the critical region of the asynchronous function still uses an asynchronous lock, and thus it is desirable to use the asynchronous overload when caching a synchronous callback, so that multiple threads attempting to retrieve the same cached value don’t block.

Cancellation¶

All of the provided overloads accept an optional CancellationToken. By passing in a vaild token, you can cancel an ongoing cache operation. There are two points where a caching operation can be cancelled:

1. When the function attempts to execute the cache callback, and enters the critical region, or
2. When the function has already entered the critical region, and is currently executing the callback.

In the first case, if the CancellationToken is cancelled while the current thread is awaiting on the asynchronous lock, the function will throw.

In the second case, it is up to the implementor of the callback fuction to appropriately handle cancellation, as the token is passed into the callback as the sole parameter.

Introduction¶

The Glass Interface Factory is a re-imagining of the (Custom) Item Interface Factory.

It is built to work with Glass Mapper items, and is intended to be used with auto-generated glass templates (ie. with TDS).

In essence, it provides services that can be thought of as codifying both the Adapter and (more loosely) Dynamic/Multi-Dispatch patterns into a single easy to use framework.

What this means in practice is that you can now easily encapsulate business logic that should apply to specific Sitecore templates within common interfaces. With those defined, you can then create implementations of those interfaces for a given Sitecore template. This defines the adapter pattern part.

The real magic occurs when you consider the Sitecore template hierarchy. Using a form of dynamic dispatch, we can create faux object-inheritance hierarchies between implementations of these interfaces.

Because each Glass Factory Type is an adapter for a particular Sitecore template, when a particular function is not implemented for a particular Glass Factory Type, we can search the base template hierarchy for that particular template to see if there exists another Glass Factory Type that both implements the specified Glass Factory Interface, and acts an adapter for a base Sitecore template of the original template.

This allows us to write code once and apply common behavior to base Sitecore templates, while letting us also override said behavior as needed on more derived Sitecore templates.

You can find more information on how this works in the Implementation Guide section.

Implementations¶

There are two primary implementations of the Glass Interface Factory to allow for use both with, and without Autofac.

In both cases, a factory builder is provided for ease of setup:

• Without Autofac: DefaultGlassFactoryBuilder
• With Autofac: AutofacGlassFactoryBuilder

The next section will cover setting up the factory.

With Autofac¶

If you’re using Autofac, then you don’t need to do anything other than register the factory via the builder.RegisterGlassFactory() extension method.

Then in your code, you should be able to use constructor injection to request the IGlassInterfaceFactory interface as a dependency, like so:

private readonly IGlassInterfaceFactory _factory;
public MyService(IGlassInterfaceFactory factory) {
        _factory = factory;
}

Without Autofac¶

If for any reason you can’t use Autofac, you can manually construct the factory using the provided DefaultGlassFactoryBuilder:

var options = new ConfigurationOptions(debugEnabled: false, assemblies: "YOURPROJECT.Library");
var sitecoreServiceFunc = () => new SitecoreContext() ?? new SitecoreService("web");
_builder = new DefaultGlassFactoryBuilder(options, sitecoreServiceFunc);

var factory = _builder.BuildFactory();

Configuration Options¶

Regardless of whether or not you use Autofac, you can configure the setup of the GlassInterfaceFactory to specify:

• Enable/Disable Debug mode
• Which assemblies to scan for GlassFactoryInterface and GlassFactoryType declarations.

With Autofac, that might look something like:

var options = new ConfigurationOptions(debugEnabled: true, assemblies: "YOURLIBRARY");
builder.RegisterGlassFactory(options);

The debug flag is useful for catching errors during development. It enables behavior that will throw a TypeMismatchException when the Glass Interface Factory attempts to convert a Glass Mapper item to its corresponding Glass Factory Type implementation, and it detects that the runtime type of the Glass Model is incompatible with the Glass Factory Type’s expected Glass Model Type.

This is usually the result of out-of-sync TDS models, and/or incorrectly passing in Glass Mapper models to the GetItem<T> function without using the SitecoreService.GetItem<IGlassBase>(inferType: true) overload.

Setup¶

Getting started with View Renderings is easy. All you need to do is register the RegisterGlassMvcServices extension method with Autofac, and create a few Views and ViewModels.

Registering the services with Autofac is as simple as:

builder.RegisterGlassMvcServices("YOURPROJECT.Web");

Creating a View¶

Creating a View is as easy as adding a new Razor View to your web project. You should then use the @inherits directive to specify the base type for the View. We recommend using the CustomGlassView<T> like so:

@inherits Jabberwocky.Glass.Autofac.Mvc.Views.CustomGlassView<MyViewModel>

The generic type parameter is the type of your ViewModel.

Creating a ViewModel¶

A ViewModel is simply a class that inherits from the GlassViewModel<T> base class. The generic type parameter for the GlassViewModel<T> is the type of Glass Mapper model to use as the GlassModel property. This allows you to, from your View, access your ViewModel from the Model property, or your Glass Mapper model from your Model.GlassModel property.

If you don’t have a need for a particular Glass Mapper model in your View, but you still want to use a ViewModel, you can do so by specifying the generic type parameter as IGlassBase, which all Sitecore items should be assignment compatible with.

Because your View is now decoupled from your Glass Mapper model, and instead is using your custom ViewModel, you can also elect to use constructor injection within your ViewModel. This allows you to pull in arbitrary dependencies in your ViewModel to write logic that dictates specific behavior for your View, without having to resort to polluting your Glass Mapper models (or creating one-off extension methods) with view-specific logic.

In the next section, we’ll look at some of the advanced options available to you when using the Jabberwocky View Model pattern.

DataSource¶

The GlassViewModel<TDatasource> type is used for creating a view-model that expects a strongly typed datasource. This datasource should map to any datasource template type defined on the View Rendering in Sitecore itself.

In the case where no datasource is specified, the type IGlassBase can be used, as all glass templates should inherit from this base type.

You can access the underlying Glass datasource model from the GlassModel property exposed on the GlassViewModel<TDatasource> type.

Rendering Parameters¶

Rendering Parameters provide a nice way to define another set of properties that can be used to configure a rendering. These are defined separately in Sitecore via Rendering Parameter Templates, and are then assigned to View Renderings, independently of Datasource Templates.

You can use Rendering Parameters in a strongly-typed fashion by using the generic type of GlassViewModel<TDatasource, TRenderingParameter>, which defines two generic parameters: the first, for the datasource template, and the second for the type of rendering parameters.

In this manner, you can access the rendering parameters of the rendering via the RenderingParameters property.

Nested Datasource Strategy¶

Sitecore 8 introduced the concept of nested datasources. Previously, if a rendering did not have a datasource specified, the Datasource property on that rendering would resolve to the current Context.Item. However, with Sitecore 8+, there is a new setting (enabled by default) that resolves a rendering’s datasource to any parent rendering’s datasource:

<setting name="Mvc.AllowDataSourceNesting" value="true"/>

The resolution logic now looks like the following:

1. Explicit DataSource specified (in the Datasource field)
2. Nested DataSource (specified by the Rendering.Item property, and inherited from any parents)
3. Sitecore Context Item (page item)

Step 2 may be unexpected for many people used to pre-8.0 resolution logic (steps 1 & 3), as this was the new step added in Sitecore 8+. To solve this, we have introduced the following attributes, each of which may be applied directly to a user-defined GlassViewModel.

• DisableNestedDatasource
• AllowNestedDatasource
• ConfigureDatasource

The third attribute (ConfigureDatasource) exposes a constructor param that dictates whether or not to use nested datasource resolution. The first two attributes are simply extensions of the ConfigureDatasource attribute, and are provided as shortcuts for their particular behavior.

You can use these attributes on ViewModels like so:

[DisableNestedDatasource]
public class NeverFallbackViewModel : GlassViewModel<IGlassBase>
{
    // PRE-Sitecore 8 behavior; ignores Mvc.AllowDataSourceNesting value

    // The datasource may come from the direct datasource, or Context Item
    // It will never be from the nested parent datasource
}

or

[AllowNestedDatasource]
public class AlwaysFallbackViewModel: GlassViewModel<IGlassBase>
{
    // POST-Sitecore 8+ behavior; ignores Mvc.AllowDataSourceNesting value

    // The datasource may come from the direct datasource, or nested parent datasource
    // Or finally the Context Item
}