SuperScript

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

The Emitter

Along with declarables, emitters are a core concept of SuperScript.

What is an Emitter?

As described in Core Concepts, an emitter can be thought of as a pipeline which deals with the converting of DeclarationBase instances into their client-side form.

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.

The figure above shows that emitters can be thought of as a pipeline through which declarations are passed and whose result is an IHtmlString representing the client-side form of those declarations.

Modifiers

This documentation frequently refers to modifiers, which is simply a collective term for the classes involved in each stage of an emitter's processing. To be clear, and in reference to the above diagram, here are the definitions for each of the available modifiers.

Emitter stage	Class implemented
Pre-modification	`ICollection<SuperScript.Modifiers.Converters.CollectionPreModifier>`
Declaration conversion	`SuperScript.Modifiers.Converters.CollectionConverter`
Post-modification	`ICollection<SuperScript.Modifiers.Pre.CollectionPostModifier>`
HTML writing	`SuperScript.Modifiers.Writers.HtmlWriter`

IEmitter Members

An emitter is an instance of IEmitter.

                        interface SuperScript.Emitters.IEmitter
                        {
                            object CustomObject { get; set; }
                            bool IsDefault { get; set; }
                            string Key { get; set; }
                            IHtmlString ToHtmlString(IEnumerable<DeclarationBase> declarations);
                            CollectionConverter Converter { get; set; }
                            ICollection<CollectionPreModifier> PreModifiers { get; set; }
                            ICollection<CollectionPostModifier> PostModifiers { get; set; }
                            HtmlWriter HtmlWriter { get; set; }
                        }

Let's take a look at each of the members on the IEmitter interface.

Name	Type	Description
CustomObject	object	This property allows the user to pass any required object through the modification and conversion process.
IsDefault	bool	Each declaration should have details of the emitter which should process and render its client-side form. This should be specified on the declaration's `EmitterKey` property. However, by not specifying a value for `EmitterKey` SuperScript will automatically provide the key for the default emitter. The default emitter is the first emitter in the collection with `IsDefault` set to `true`; if none have this value explicitly set then the default emitter is the first emitter in the `Emitters` collection. Important: to allow SuperScript to fall back on the key of the default emitter (which is not the case when a key is explicitly specified) the emitters must have been specified prior to the declaration being added to the collection.
Key	string	This is the value by which an emitter is identified by declarations, and when an emitter is requested to emit its declared contents (the client-side form of all declarations specifying this emitter). Given that the `Key` is essentially an identifier for an emitter, each emitter must have a unique `Key`.
ToHtmlString	IHtmlString	When called, this method emits the client-side form of the specified declarations.
Converter	`CollectionConverter`	The implementation of `CollectionConverter` which has been assigned to this emitter. A `CollectionConverter` is not required for an emitter.
PreModifiers	`ICollection<CollectionPreModifier>`	The implementations of `CollectionPreModifier` which have been assigned to this emitter. A `CollectionPreModifier` is not required for an emitter.
PostModifiers	`ICollection<CollectionPostModifier>`	The implementations of `CollectionPostModifier` which have been assigned to this emitter. A `CollectionPostModifier` is not required for an emitter.
HtmlWriter	`HtmlWriter`	The implementation of `HtmlWriter` which has been assigned to this emitter. An `HtmlWriter` is required for an emitter.

What Next?

Read about creating and configuring an emitter here.

Read about emitting the declarations from an emitter here.

Read about declarations here.