Rocketmakers.Templates 0.2.1

Rocketmakers.Templates

A library for rendering content using templates from an external source and including dynamic data.

• Rocketmakers.Templates
  • Packages
    • Rocketmakers.Templates
    • Rocketmakers.Templates.Http
    • Rocketmakers.Templates.Handlebars
  • Usage
    • Prerequisites
    • Setup
    • Retrieving templates
    • Rendering

Packages

Rocketmakers.Templates

This is the core library used by implementations that includes core types and interfaces.

Rocketmakers.Templates.Http

This library contains an implementation for ITemplateService, whose purpose is to obtain the templates from a Http source. An in memory cache is also provided to support caching template content to avoid over-fetching.

Rocketmakers.Templates.Handlebars

This library contains an implemention for ITemplateRenderer, providing the ability to render templates using Handlerbars.JS.

Usage

Prerequisites

This assumes you have setup and configured your template repo.

Setup

The first thing you'll want to do is configure your TemplateService. For templates stored at a remote source, we'll be using Rocketmakers.Templates.Http.

This can be setup using the following snippet.

// Initialise the template service
var templateService = new HttpTemplateService(
    repository: new AnonTemplateRepository(
        new HttpClient { BaseAddress = "https://gitlab.com/my-org/my-templates/-/raw/develop/" }
    ),
    cache: new InMemoryTemplateContentCache(
        new InMemoryTemplateContentCacheConfig(
            UseCache: true,
            CacheExpirySeconds: 3600
        )
    )
);

If you are utilising the default .NET dependency injection, then you can set it up as follows

// Inject service into Microsoft.Extensions.DependencyInjection.IServiceCollection
services.AddHttpTemplateService(
    repositoryUrl: new Uri("https://gitlab.com/my-org/my-templates/-/raw/develop/"),
    cacheConfig: new InMemoryTemplateContentCacheConfig(
        UseCache: true,
        CacheExpirySeconds: 3600
    )
);

You'll also want to register your ITemplateRenderer implementation. In our example, we'll be using Rocketmakers.Templates.Handlebars for processing handlerbars based templates.

services.AddSingleton<ITemplateRenderer, HandleBarsTemplateRenderer>();

Retrieving templates

Retrieving templates is done in the following way. You will repeat the following process for each service whose templates you want to setup.

// Maps to 'myService.json' in the source containing your templates. This is what contains the
// metadata describing the location of the layouts and partials comprising your templates
var serviceName = "myService";

// Get the latest templates for your service
TemplateGroup templateGroup = await templateService.GetTemplatesAsync(serviceName);

// Update the renderer with the latest templates
await renderer.UpdateTemplateGroupAsync(templateGroup);

There are two ways you can setup the above, and which one you use will depend on where you want to compromise.

1. You can update the templates on bootstrap of your application. This means that rendering templates will be quick as they won't need to be downloaded and compiled. However startup time of your application will be slower. This will be benefical for services that are active for a long time, but not very handy for services that scale to zero or you need to start up quickly.

2. You can update the templates everytime you render them. This means that startup time of your application wont be compromised, but requests that require content to be rendered will be slower.

Rendering

You can then render your template(s) with your dynamic data, as follows

// Render the template with the supplied payload of parameters
IReadOnlyCollection<RenderedTemplate> rendered = await renderer.RenderAsync(
    layoutId: "resetPassword",
    payload: new { username = "Alan", returnUrl = "https://rocketmakers.com" });

Your layoutId must match a layout defined in your specified service.