API Reference

Plugins

Plugins are a nice way to extend templates with customized functionality which can encapsulate any number of blocks, filters, preferred configuration and dependencies by implementing the IScriptPlugin interface.

The MarkdownScriptPlugin is a good example of this which registers a markdown Page format, Script Methods, Filter Transformer and markdown Block:

public class MarkdownScriptPlugin : IScriptPlugin
{
    public bool RegisterPageFormat { get; set; } = true;

    public void Register(ScriptContext context)
    {
        if (RegisterPageFormat)
            context.PageFormats.Add(new MarkdownPageFormat());
        
        context.FilterTransformers["markdown"] = MarkdownPageFormat.TransformToHtml;
        
        context.ScriptMethods.Add(new MarkdownScriptMethods());

        context.ScriptBlocks.Add(new MarkdownScriptBlock());
    }
}

var context = new ScriptContext {
    Plugins = { new MarkdownScriptPlugin { RegisterPageFormat = false } }
}.Init();

Removing Plugins

When needed any default plugins can be removed with the RemovePlugins() API:

var context = new ScriptContext()
    .RemovePlugins(x => x is DefaulScripttBlocks) // Remove default blocks
    .RemovePlugins(x => x is HtmlScriptBlocks)    // Remove all html blocks
    .Init();

var context = new ScriptContext {
        OnAfterPlugins = ctx => ctx.RemoveBlocks(x => x.Name == "capture")
    }
    .Init();

Advanced plugin registration

For greater control over the registration and execution of plugins, they can implement IScriptPluginBefore to have custom logic executed before plugins are registered or implement IScriptPluginAfter for executing any logic after.

ScriptContext

The ScriptContext is the sandbox where all templates are executed within that can be customized with the available APIs below:

Preconfigured defaults

Some default scripts when called without arguments will use the default configuration shown below that can be overridden by replacing their default value in the ScriptContext's Args collection:

var context = new ScriptContext { 
    Args = {
        [ScriptConstants.MaxQuota] = 10000,
        [ScriptConstants.DefaultCulture] = CultureInfo.CurrentCulture,
        [ScriptConstants.DefaultDateFormat] = "yyyy-MM-dd",
        [ScriptConstants.DefaultDateTimeFormat] = "u",
        [ScriptConstants.DefaultTimeFormat] = "h\\:mm\\:ss",
        [ScriptConstants.DefaultFileCacheExpiry] = TimeSpan.FromMinutes(1),
        [ScriptConstants.DefaultUrlCacheExpiry] = TimeSpan.FromMinutes(1),
        [ScriptConstants.DefaultIndent] = "\t",
        [ScriptConstants.DefaultNewLine] = Environment.NewLine,
        [ScriptConstants.DefaultJsConfig] = "excludetypeinfo",
        [ScriptConstants.DefaultStringComparison] = StringComparison.Ordinal,
        [ScriptConstants.DefaultTableClassName] = "table",
        [ScriptConstants.DefaultErrorClassName] = "alert alert-danger",
    }
}.Init();

Args

ScriptContext Arguments can be used to define global variables available to every template, partial, filter, etc:

Virtual Files

Templates only have access to Pages available from its configured VirtualFiles which uses an empty MemoryVirtualFiles. To make pages available to your ScriptContext instance you can choose to either programatically populate the VirtualFiles collection from an external source, e.g:

var fs = new FileSystemVirtualFiles("~/template-files".MapProjectPath());
foreach (var file in fs.GetAllMatchingFiles("*.html"))
{
    if (!MyAllowFile(file)) continue;
    using (var stream = file.OpenRead())
    {
        context.VirtualFiles.WriteFile(file.VirtualPath, stream);
    }
}

Alternatively if you want to enable access to an entire sub directory you can replace the Virtual Files with a FileSystem VFS at the directory you want to make the root directory:

context.VirtualFiles = new FileSystemVirtualFiles("~/template-files".MapProjectPath());

DebugMode

DebugMode is used to control whether full Exception details like StackTrace is displayed. In SharpPagesFeature it defaults to the AppHost DebugMode, otherwise it's true by default.

ScanTypes

Specify a ScriptMethods or SharpCodePage to auto register.

ScanAssemblies

Specify assemblies that should be scanned to find ScriptMethods's and SharpCodePage's to auto register. In SharpPagesFeature the AppHost's Service Assemblies are included by default.

ScriptMethods

Register additional instances of filters you want templates to have access to.

CodePages

Register instances of code pages you want templates to have access to.

Container

The IOC Container used by the ScriptContext to register and resolve dependencies, filters and Code Pages. Uses SimpleContainer by default.

AppSettings

Specify an optional App Settings provider that templates can access with the {{ key | appSetting }} default filter.

CheckForModifiedPages

Whether to check for modified pages by default when not in DebugMode, defaults to true. Note: if DebugMode is true it will always check for changes.

CheckForModifiedPagesAfter

If provided will specify how long to wait before checking if backing files of pages have changed and to reload them if they have. Note: if DebugMode is true it will always check for changes.

RenderExpressionExceptions

Whether to Render Expression Exceptions in-line (default = false).

PageResult

The PageResult is the rendering context used to render templates whose output can be customized with the APIs below:

Layout

Override the layout used for the page by specifying a layout name:

new PageResult(page) { Layout = "custom-layout" }

LayoutPage

Override the layout used for the page by specifying a Layout page:

new PageResult(page) { LayoutPage = Request.GetPage("custom-layout") }

Args

Override existing or specify additional arguments in the Template's scope:

new PageResult(page) { 
    Args = { 
        ["myArg"] = "argValue",
    }
}

ScriptMethods

Make additional filters available to the Template:

new PageResult(page) { 
    ScriptMethods = { new MyScriptMethods() }
}

OutputTransformers

Transform the entire Template's Output before rendering to the OutputStream:

new PageResult(page) {
    ContentType = MimeTypes.Html,
    OutputTransformers = { MarkdownPageFormat.TransformToHtml },
}

PageTransformers

Transform just the Page's Output before rendering to the OutputStream:

new PageResult(page) {
    ContentType = MimeTypes.Html,
    PageTransformers = { MarkdownPageFormat.TransformToHtml },
}

FilterTransformers

Specify additional Filter Transformers available to the Template:

new PageResult(page) {
    FilterTransformers = {
        ["markdown"] = MarkdownPageFormat.TransformToHtml
    }
}

ExcludeFiltersNamed

Disable access to the specified registered filters:

new PageResult(page) {
    ExcludeFiltersNamed = { "partial", "selectPartial" }
}

Options

Return additional HTTP Response Headers when rendering to a HTTP Response:

new PageResult(page) {
    Options = { 
        ["X-Powered-By"] = "#Script"
    }
}

ContentType

Specify the HTTP Content-Type when rendering to a HTTP Response:

new PageResult(page) {
    ContentType = "text/plain"
}