Brand

SuperScript

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

Creating an Emitter

One of the first things you'll want to do with SuperScript is create the emitter(s). There are two ways of achieving this:

  1. specifying an emitter in the configuration file
  2. specifying an emitter programmatically

Specifying an emitter in the configuration file

SuperScript allows many of its features to be declared in the configuration file. Although slightly more verbose, this method allows modifiers to be added or removed to the emitter pipeline without having to deploy modified code to a server. 

                        <configSections>
                            <section name="superScript" type="SuperScript.Configuration.SuperScriptConfig, SuperScript.Common, Version=0.0.0.1, Culture=neutral" />
                        </configSections>
                        

                        …
                        

                        <superScript>
                            <emitters>
                                <emitter key="javascript" isDefault="true">
                                    <converters>
                                        <modifier type="SuperScript.JavaScript.Modifiers.Converters.JavaScriptStringify, SuperScript.JavaScript" />
				                    </converters>
                                    <postModifiers>
                                        <modifier emitMode="LiveOnly" type="SuperScript.JavaScript.Modifiers.Post.JavaScriptMinifier, SuperScript.JavaScript" />
				                    </postModifiers>
                                    <writers>
                                        <modifier type="SuperScript.ExternalFile.Modifiers.Writers.ExternalScriptWriter, SuperScript.ExternalFile" />
									</writers>
								</emitter>
                            </emitters>
                        </superScript>

The above example requires the SuperScript.Common as well as additional libraries.

Here is a description of the above example:

  1. The configuration's <configSections> element is modified to allow a custom section (<superScript>), hitherto unrecognised by ASP.NET, to be declared.

  2. An emitter is instantiated and added to the Emitters collection.

    This instance of IEmitter is actually an object of type StandardEmitter, which is the default type (if not specified).

    Of course, it is possible to derive custom implementations of IEmitter with more features, and then specify the type in the type attribute on the <emitter> element.

  3. The value "javascript" is assigned as the Key for this emitter.

    Remember that the Key is essentially an identifier for an emitter. Each emitter must therefore have a unique Key.

  4. An instance of JavaScriptStringify is then assigned to the CollectionConverter property.

    This specific implementation of CollectionConverter has not been covered yet, but it should suffice to say that this is simply an implementation which runs on the JavaScript-oriented declarables found in the SuperScript.JavaScript library.

  5. An instance of JavaScriptMinifier is then assigned to the PostModifiers property.

    This specific type of CollectionPostModifier has not been covered yet, but it should suffice to say that this is simply an implementation which uses Microsoft's WebGrease library to minify javascript.

    Note that this modifier element has its emitMode attribute set to LiveOnly. This will be covered when discussing modifiers.

  6. An instance of ExternalScriptWriter is assigned to the HtmlWriter property.

    Again, this implementation of HtmlWriter is documented elsewhere, but this class writes the client-side form of the emitter's declarations to an external file and places a <script src="…"> tag on the page.

This emitter may now be referenced in declarations' EmitterKey properties. However, because this emitter was also declared as the default emitter, any declarations which are added to SuperScript.Declarations.Collection without an emitter key being stated will automatically be emitted using this (default) emitter.

Implementation-specific Properties

Some implementations of ModifierBase expose custom properties (see here for an example). The following example demonstrates how to declare values for these properties in a config file. 

						<modifier type="…">
							<properties>
								<property name="PROPERTY-NAME" value="PROPERTY-VALUE" type="PROPERTY-TYPE" />
								<!-- multiple <property> elements may be declared here -->
							</properties>
						</modifier>

Unfortunately custom ModifierBase properties which have a collection type (i.e., an IEnumerable) cannot be declared in a config file. Such custom properties must be declared programmatically.

Specifying an emitter programmatically

An alternative to using the configuration file is to call some code which instantiates an emitter and adds it to the Emitters collection. 

                        Emitters.Add(new StandardEmitter
		                                 {
			                                 Key = "whenReady",
			                                 Converter = new JavaScriptStringify(),
			                                 PostModifiers = new Collection<CollectionPostModifier>
				                                                 {
					                                                 new WhenReady(),
					                                                 new JavaScriptMinifier
						                                                 {
							                                                 EmitMode = EmitMode.LiveOnly
						                                                 }
				                                                 },
			                                 HtmlWriter = new ScriptTagWriter()
		                                 });

The above example requires the SuperScript.Common as well as additional libraries.

Here is a description of the above example:

  1. This example makes it clear that we are instantiating an instance of StandardEmitter.

  2. The Key "whenReady" is assigned to this emitter.

    Remember that the Key is essentially an identifier for an emitter. Each emitter must therefore have a unique Key.

  3. An instance of JavaScriptStringify is assigned as this emitter's CollectionConverter.

  4. The PostModifiers property is instantiated as a new Collection.

    Into this collection is added

    1. WhenReady, an implementation of CollectionPostModifier which writes it's JavaScript content into a jQuery .ready closure.

    2. An instance of JavaScriptMinifier is then assigned to the PostModifiers property.

      This specific type of CollectionPostModifier has not been covered yet, but it should suffice to say that this is simply an implementation which uses Microsoft's WebGrease library to minify javascript.

      Furthermore, this JavaScriptMinifier instance will only be implemented when the application is not running in debug mode.

  5. An instance of ScriptTagWriter is assigned to the HtmlWriter property.

    This implementation of HtmlWriter writes the client-side form of the emitter's declarations into a <script> tag on the page.

So in summary, declarations which are instructed to pass through this emitter will be placed inside a jQuery .ready closure, itself written into a <script> tag. And when the application is not running in debug mode, the contents of the <script> tag will be minified.

Important point: When specifying emitters programatically, this code should be placed in a method which is called once per application. For example, the global.asax's Application_Start method presents a good opportunity.

Multiple Emitters

An application may have multiple emitters, each with a different set of modifiers, and each with a different Key. For example, an application may have one emitter for JavaScript to be run immediately upon load, and another emitter with JavaScript to be run only once the DOM has loaded.

These may be emitted one at a time, specifying their individual Key values, or SuperScript can be instructed to write the output of all emitters at the same location in the HTML document.

Another more advanced option is to bundle emitters into a named EmitterBundle and instruct SuperScript to emit for those included emitters. Read about emitter bundles here.

The next page will explain how to retrieve the client-side formatted output of an emitter.

What Next?

Read about declarations here.

Read about emitting the declarations from an emitter here.