Extending SharpJS

Let's build a SharpJS Extension!

SharpJS contains many of the core JavaScript DOM and jQuery APIs, as well as ExaPhaser.WebForms for building GUIs. Should you want to add functionality to build something like, say, a compatibility layer, you can either build your libraries on top of the existing, tested, managed and frequently updated SharpJS codebase using the ExaPhaser.WebForms and SharpJS.Dom libraries, or implement new APIs from scratch with JSReplacementAttribute and Verbatim.Expression.

In either scenario, you can distribute a library that adds additional functionality to SharpJS.

Tutorial

In this tutorial, we're going to build a SharpJS extension that wraps console.log and adds Mwahaha!!! to the end of everything we print out.

Step 1 - Setting Up

• You are going to need a C# development IDE. Windows users should opt for Visual Studio or SharpDevelop, while Linux and OS X users should use MonoDevelop and Xamarin Studio, respectively. However, for the purposes of this tutorial, I will assume that you are using Visual Studio on Windows, though the instructions should be almost identical except for the final step, creating a test template. As the template only supports Visual Studio, non-Visual Studio users will have to clone/download the repository and grab the template (the WebFormsTemplate folder) from the VSAddin/ExaPhaser.SharpJS.Addins/ folder.

• Create a new Class Library project. We will name it MwahahaExt for now.

• Rename the default file or create a new C# source file called EvilConsole.cs

• You will now need to install the SharpJS libraries to link against. If you skip this step, you will not be able to use the large number of frameworks SharpJS provides to make your life easier. In fact, interacting with JavaScript and HTML will be near-impossible without linking to SharpJS.

• To install the SharpJS libraries, open the NuGet package manager for you project and install ExaPhaser.WebForms. This is the SharpJS library that contains the entire SharpJS framework including some core extensions.

• You are now ready to start building your extension!

Step 2 - The extension

• Open up the EvilConsole.cs file we created eariler. Replace whatever template code is in there code with this:

using SharpJS.Dom;

namespace MwahahaSJSExt
{
	public class EvilConsole
	{
		public static void Log(object obj)
		{
			JSConsole.Log(obj.ToString() + "Mwahaha!!!");
		}
	}
}

• Your extension is ready! You can now compile the extension with the Release configuration and distribute the files in bin/Release! If you want to distribute your library through NuGet, make sure you set ExaPhaser.WebForms as a dependency, as the extension will not function without the actual SharpJS core.

Step 3 (Optional) Test the extension!

• You will need a template of a SharpJS project. This is best created with the extension available from the official site.
• Create a new ExaPhaser.WebForms SharpJS project. In this project, reference the library you created earlier by right-clicking references and pressing Add Reference in Visual Studio. If you need help for adding references, google it.
• Finally, in your new project, call MwahahaSJSExt.EvilConsole.Log("Hello, World."). Build the project and open the HTML file in your browser. You should see Hello, World.Mwahaha!!! in the browser console.

Good luck building extensions!