Episerver edit mode use Dojo framework as a client side technology. When creating new custom property, gadget or command button we should use this JavaScript library to prepare user interface. To have static typing and class-based object-oriented programming I tried to create Dojo widget in TypeScript. In this article I will describe how to develop Alloy demo example StringList property in TypeScript.

Setup TypeScript in project

First we need to add TypeScript Dojo definitions to our projects. TypeScript type definitions file allow us to use Javascript libraries that was not written in TypeScript. Dojo, Dijit and Dojox was developed in JavaScript. The definitions containes all members public signatures. Dojo.TypeScript.DefinitelyTyped definitions are available as Nuget Package dojo.TypeScript.DefinitelyTyped.

Dojo TypeScript Nuget package

After adding Nuget we should see a lot of *.d.ts files inside /Script/typings/dojo folder.

Dojo definitions Project structure

Because Dojo use AMD to load module dependencies we need to change TypeScript Module System to AMD. This option is available in project properties->TypeScript Build->Module System.

typescript build

Now we are ready to write new property in TypeScript.

Implementing StringList property

In Alloy EPiServer demo there is a custom StringList property. It’s used to store properties of string[] type. So there are few elements implemented:

  • TypeScriptWidget.Models.Properties.PropertyStringList – backing type, used to store string[] value in database.
  • TypeScriptWidget.Business.EditorDescriptors.StringList – editor descriptor, used to setup edit mode StringList editor,
  • alloy.editors.StringList – client side widget – JavaScript UI component. Used by Forms Editing view to edit property.

No we will change Editor descriptor ClientEditingClass to new custom widget – StringListTs

Then under /CliendResources/Scripts/Editors we will create new TypeScript file – StringListTs.ts.

TypeScript solution structure

Dependencies on EPiServer modules

EPiServer modules doesn’t have definition files that could be downloaded from Nuget. We have to write them manually. There is no need to create all EPiServer modules definitions (it could take few years), but only necessary elements used by StringList widget.
To add definition files we will create new directory ‘epi’ under /Scripts/typings/.
TypeScript EpiServer definitions

StringList use _ValueRequiredMixin mixin. We need to export module namespaces structure epi>shell->widget->_ValueRequiredMixin and then export “epi/shell/widget/_ValueRequiredMixin” path.

Adding widget dependencies

When adding dependencies with AMD system we use define function.

Many times I made mistakes and switch order between dependency definitions and assignment variables. For example, I forgot to add ‘array’ variable as function parameter and Connect variable contained dojo._base.array… It was difficult to fix.
Using the Typescipt all dependencies will be registered separately – the paths and variables will be defined together, each in single line.

Strongly typed parametrs

We could also set types parameters and returning values of functions. For example for _stringToList method

we will set string as type of value parameter and string[] as returning type for function.

Then all places that execute _stringToList function will benefit from strongly typed parameters and returned values.

Adding text resources

In original StringList widget, the templateString was set using inline assignment. For more complex widgets we will probably use dojo/text! plugin. It also requires preparing definition file – StringListDefinitions.d.ts. The module will just define path to StringListTemplate.html file.

Then we can use template as dependency in StringList widget.

Debugging StringListTs

During compilation process of TypeScripts, the *.js and *.js.map files are created. We don’t need to debug generated JavaScript. The map file allows us to debug TypeScript files directly.
debugging TypeScript files

Below is the source code for StringList widget impleneted using TypeScript.