SuperScript

This documentation is still being written. Please bear with us while we complete this documentation.

Core Concepts

The What Does It Do? section explained that SuperScript allows developers to make declarations from almost anywhere in their server-side web application - programmatically or in container controls in a WebForms .aspx file or MVC Razor view.

This page will build upon that simple explanation and discuss the fundamental mechanisms of SuperScript. Although that first explanation describes the two aspects of SuperScript, it is actually a three-stage process:

1. adding declarations
2. processing an emitter's declarations
3. writing the output of the emitter

Adding Declarations

SuperScript allows developers to make declarations, whatever these might be: a JavaScript variable is a simple, convenient example. These declarations are added to a central, application-wide collection of all declarations.

The figure above shows that wherever declarations are made, they are all added to the same collection, SuperScript.Declarations.Collection.

Throughout the lifecycle of an HTTP request declarations of various types may be added to this single collection, ready to be emitted in a location of the developer's choosing. Declarations may be added to this collection directly (as well as removed or modified) or via helper methods for specific declaration types.

A declarable is simply an instance of SuperScript.Common.Declarables.DeclarationBase. The content of the declaration can be many things, depending upon the implementation of DeclarationBase. For example, SuperScript.Templates allows a client-side HTML template to be declared.

The central collection of declarations is an IList<DeclarationBase>, so it's trivial to derive a custom implementation of SuperScript.Common.Declarables.DeclarationBase and have this added to the collection.

Emitting Declarations

Once we've added our declarations, whatever they may contain, the next logical step is to write them out to a desirable location. This is what emitters are used for.

An emitter may be thought of as a pipeline consisting of objects which can modify the declarations, and then write the output to the webpage. An emitter is passed a collection of DeclarationBase objects, and the end of the process returns an IHtmlString which contains the output of each declaration passed to this emitter.

Although the writing of an emitter's output is listed above as being the final step in the process, this is actually a two-stage process: when an emitter receives the instruction to write its output, it must then process all declarations which pass through this emitting pipeline; once processed, the IHtmlString is then compiled.

Processing Declarations

The emitter pipeline offers four opportunities to modify the client-side form of the emitter-specific collection of declarations:

• CollectionPreModifier

  The first stage in the emitter pipeline is passed the raw, currently-unmodified collection of DeclarationBase objects, and returns a collection of DeclarationBase objects.

  View this class on GitHub

• CollectionConverter

  The second stage in the emitter pipeline takes the output from the first stage, a collection of DeclarationBase objects, and uses the internal logic of the specific implementation of DeclarationBase to convert this server-side object into its client-side form.

  The output of this stage is a string consisting of the concatenated output from all instances of DeclarationBase passed to this emitter.

  View this class on GitHub

• CollectionPostModifier

  The next stage in the emitter pipeline takes the output from the second stage and offers the opportunity to modify the client-side form of the declarations passed to this emitter.

  An example of the advantage which this stage offers is the possibility to minify JavaScript or to pre-compile HTML templates.

  View this class on GitHub

The final step implemented by an emitter uses an instance of an HtmlWriter to write the output to the webpage. In actuality, this still offers the opportunity to modify the output.

• HtmlWriter

  The HtmlWriter is passed a string and returns an IHtmlString.

  However, this stage offers the opportunity to write the passed string to one location and write out something entirely different to the emitting location.

  For example, this stage could write the passed string to the local file system as a *.js file, then write a <script src="…"> tag to the webpage which references the created *.js file.

  View this class on GitHub

It should now be clear that the output from processing an emitter's declarations is the output of the emitter, thus stage 3 in an emitter's process.

Further Information

Read more about the emitter here.