Firstly before I begin, I would like to thank all the sponsors for today’s events (especially the SharePint) and the crew of SharePoint Saturday UK.

Who am I? What do I do? Who I was?

No I haven’t lost my mind, and yes I do like asking questions.

My names Hugh Wood, I’m still young, and I have been doing some software development thing for now 14 years. I started at Kodak debugging filters, now I work at Rencore AB building analysis engines for SharePoint Code Analysis. So how did I get into SharePoint, I’m sure if you are interested you will visit my Linked In, like me, dislike me, perhaps add me up to you.

This is my cat Momo, hes a ragdoll and fond of walking over my keyboard while writing code, or sitting on my shoulder. So if you have recently found a bug in SPCAF then a donation of cat treats might help. (He likes the cheesy ones by dreamies).

Riiight... Tough crowd, not because of my lame jokes but because we are talking JavaScript. The nasty word that may as well be 4 letters long and banned by your parents.

So to ease your pain, and to help you use nicer words like “EcmaScript” in order to hide from your embarrassment to other .net based developers, who in reality have been comfy with JavaScript for about 4 years now? Yes SharePoint is behind in technology, but that doesn’t mean we can’t learn from modern practices and apply them, and build a framework which is safe, and simple to use.

So what does this huge cover story entail? I will cover:

  • How to approach framework design
  • Common developer mistakes in JavaScript
  • Picking a structure
  • Loading into SharePoint
  • What to include
  • What not to include

How to approach framework design

As with anything, framework design requires some forethought and research. Having built quite a few JavaScript frameworks now, and I have identified the places where I went wrong, and what I did right.

The first framework, I thought I knew it. I wrote the framework for me. A simple design that allowed me to extend the code. It was for an old website written in Classic ASP, and I can tell you now it sucked to high heaven. 10 years on however I have refined this process, and I advise people on how to not make my mistakes.

Frameworks need to be

  • Reliable
  • Extensible
  • Manageable
  • Performant
  • Secure
  • Simple to understand

We also have some SharePoint Challenges:

  • Minimal Download Strategy / Client Side Rendering
  • Complex JavaScript in place already
  • Limited remote provisioning tooling

If we don’t cover all of these points then somewhere down the line we are going to have to fix what went wrong, and this costs us time and money.

The first thing I did was to research…s

Why JavaScript used wrongly makes people hate it

JavaScript, its simple isn’t it. Write a few lines of code, change some text… some more add a click event and a button, and before you know it you’ve screwed up your sites, you can’t retract something because you used declarative deployment processes and suddenly you are looking at a P45 without a clue to what went wrong.

So without a doubt the top 10 things you can do wrong with JavaScript are going to apply to your framework.

You reference “this” in a Block Statement, and suddenly you get a TypeError. Why? It’s in the correct closure? Errors like this happen far too often. Asynchronous calls aren’t in the scope you think they are. Infact they hoist their variables to the context they run in, and boom your asynchronous call failed. Be a setTimeout or an Ajax call, your object reference failed.

If a reference fails, your framework fails at that point. It won’t slightly fail, it will break. Completely. Straight forward code analysis can’t catch this, you need data flow analysis with a full overview of the flow graph of the code. Basically, just like having to know you have to dispose certain objects in SharePoint, you need to know how scope really works in JavaScript. Once you know how they work, you can abuse this knowledge and do some really awesome stuff. Just remember, Block Statements act differently in JavaScript, to C#, variables can leak, and asynchronous parts are executed elsewhere.

So memory leaks! My favourite subject with JavaScript. They are going to happen, you can almost not avoid it, unless you craft your JavaScript carefully to avoid them. TypeScript and other transcompilers will have this issue a whole lot more, so remember if you are going that route, include memory leak testing in your project schedule across the board. Otherwise you can do some checks that created objects, aren’t a) made in loops and b) are correctly dereferenced (disposed of) when finished with.

Take for example, you are polling say a web service every so often, this polling method uses this very large object. A nested method also refers to that same large object, and this suddenly changes the whole lexical scope for our large object. So it can’t be dereferenced. You might only be calling one method over and over, but the engine thinks it can’t dereference the object, so every loop it makes a new version and BOOM. Eventually your browser crashes, and you just lost the upload you were doing, and you have to explain to your boss why the document is late. End users hate memory leaks, so test for them, if you use transcompiling methods (TypeScript, CoffeeScriptetc) then have someone run tests to eat up some of that time you saves not learning JavaScript in the first place.

So again, scope, and object reachability are still the same error that most people make. So whatever we build has to combat these issues.

So after we have realised that JavaScript is built and referenced differently, we realise that there are actual other real differences in Syntax that can cause some issues.

The next thing that links all of the rest of the issues together is inheritance. All objects and chains of objects delegate all parts they share from their parents back to the original copy. With this in mind, we can use inheritance like a parasite, and if you think of inheritance in JavaScript as a parasite you won’t have any problems with it. If you do the thing you need to lookup is Prototypal Inheritance and Inheritance Patterns in JavaScript by Douglas Crockford (Clever chap, he develops the JavaScript Language).

All are created equal. Well except JavaScript, let us not be languagist against this behemoth of the development world. It’s probably the most used language that has moved from a scripting language to an actual development language.

If you have done ANY JavaScript development, then you would know there are some loose comparison operators. These looser operators are the same as we find in C# and we like those, they are friendly and familiar. Don’t use them. They are a trap. Use the longer form for everything and you can’t go wrong. If you need to know more, then do an internet search for Type Coercion. Then give up and do as I suggest you can’t really go wrong.

You want to edit your html with JavaScript. Awesome load of up jquery and stick some code up, loop through elements make your changes and read and write to the DOM however you want to. Actually don’t because have you ever seen that popup that tells you that your script is taking too long? Yeah I don’t like that either. So to help you, I will help you avoid this as much as possible.

There are 2 reasons for this, you are referencing the dom directly in loops, or you are causing what is known as layout thrashing. Both are bad. Both have good simple techniques to avoid the issue. 1) Reference DOM elements and Objects outside of loops, and read the reference only in the loop. 2) Group layout updates together, and layout reads together as much as possible. This will mean that you won’t invalidate the DOM, so often to cause significant slow down. Html5 gives us animation frames which are a million times better, allowing us to queue these asynchronously. But let’s face it our clients are using IE6 and we wouldn’t be learning JavaScript if we didn’t want to fix the world… or apps yeah it’s the app the model and we are developing for the future. I know Enterprise I lived in that sphere too long. At least you will learn JavaScript for next release when you will be developing apps/apparts because hopefully webparts will be redundant.

So in summary loops. Don’t create references or methods in a loop ever. Oh yeah methods. If you are expecting to use a variable in a loop inside a method, which you are binding to an event. Don’t. It doesn’t work like that, and in all likeliness you just created a memory leak. Instead define a single method, and add a method call with a parameter, binding that into the event. Actually looks neater too and disposes of the objects correctly.

So the last is security. We all know Eval Is Evil! Don’t touch it (Until the next version of JavaScript that is, when it has been made safe). But, what if I told you evil has many faces. Implied Eval is were methods accept strings as a method parameter in place of the method object. This results in the code being evaluated before being run. The two guilty partys here are setTimeout and setInterval. They both evaluate strings, so when you are performing a risk analysis ensure that these are method objects, not strings.

And the last security issue is Cross Domain Security. The JavaScript same origin policy is something you don’t want to bypass without proper usage. So lets make this short. JSONP isn’t secure, CORS is better. Use a CORS endpoint and SP.RequestExecutor for your cross domain ajax calls. SP.RequestExecutor is actually awesome, so use it anyway, it does your canary checks for you.

Designing the framework structure.

I’m sure you all know, if you are going to build a framework in JavaScript you use what is known as the module pattern. If you didn’t well you do now.

The module pattern gives you an enclosed area which you can create new modules of code. It allows for private and public variables and methods, we can augment the module further down the line, we can split the structure across multiple files (Which will allow us to use the Minimal Download Strategy of SharePoint version 15 or above), we can create sub modules inside our module allowing for neat compartmentalisation.

We do have some challenges still with the module pattern. The pattern means you are a) building a seemingly complex ecosystem, and it needs to be simplified in usage, and b) private variables to one files module part, are not accessible in other files module parts. But by combining it with a sealing pattern, and a builder pattern, we can get around these limitations and bring simplicity back into its usage.

The builder pattern allows us to use a jQuery style development, we can implement extensions on SharePoint collections, and objects allowing for semantic and readable code.

The sealing pattern gets around a limitation of variable scope, when spreading a module across separate files. Each files module methods can’t see the other modules privates. So in order to allow this, we implement a method which moves the private variables public, instantiates the new file and then makes them private again, giving the new module methods access to the private variables.

This is the limitations taken care of, so now we need to integrate this with SharePoint.

We have to deal with MDS and Scripts on Demand.

MDS and SOD

When dealing with MDS we need to ensure that the framework is registered as a namespace, and that if we have an initialisation method that needs re-firing because say we need to reset some variables on amds page change, that this method is registered.

For our framework we have no initialisation method so far, just instantiation. However we should support this in our framework incase we need to add a module on later than does this.

We have 2 options, use the internal method Register Module Init or we go the MDS route and allow SharePoint to register it for us by merely following convention. A stickler for convention I vote for the latter being the better option as it also happens to register our module correctly with MDS and SOD at the same time.

The global namespace init pattern, follows the filename, and allows for an init method to be called on every page refresh, by firing off an event when the pages checksum changes.

The global namespace init pattern, as I like to call it is a basic revealing pattern than allows sharepoint to detect what methods have been loaded, and if they have been correctly registered with scripts on demand. While you can do the same thing yourself manually, I feel allowing the check to proceed reduces error in registering your module, and also enforces a naming convention on our frameworks files.

Scripts on Demand requires some repeated code, so perfect for a framework implementation, we can wrap this up nice and easily with a couple of helper methods which we can use in all subsequent files loaded. We need to be able to register new scripts on the fly, load scripts asynchronously or synchronously, and inform sharepoint that scripts modules have been read by the browsers engine, and that any waiting methods on this code can be executed.

So we have added functionality to load our scripts, register our scripts, and for our scripts to work well with MDS. We can also split our scripts into smaller chunks which works nicely with MDS, meaning the framework will be loaded in parts as they are required. The size of these chunks is entirely up to you, but this basically means it doesn’t matter how large your framework grows, only a few KB will be required at a time, even if its total size is megabytes.

code

Now we have the structure to our framework what do we include?

Each category of things a developer will do wrong, has a simple implementation in order to prevent the developer from making these mistakes, also blocking cross site scripting attacks and man in the middle attacks from happening in the process.

If you aren’t familiar what these attacks entail, don’t worry for now, just know they are bad and we don’t want to allow them, even accidently.

So here is a small sample of methods that will prevent the majority of our issues from happening.

Implied eval is evil.

We provide our developers a nicer version of setTimeout to use, and block usage of setInterval (its bad and causes problems)

code

We can also make a method that implements a fast iteration pattern for developers… A reverse while loop, with minimum object reads per iteration is the fastest way we can process collections.

And finally… how do we deal with the other things, the things we shouldn’t be doing?

We have 2 types of tool we use with the team, to prevent the use of things like setTime, referencing objects in loops, and causing memory leaks.

The first is to provide intellisense for visual studio for your JavaScript file.

The best way to do this for your team is by extending intellisense. It’s incredibly easy, you can provide descriptions or just hints to the code.

For general JavaScript issues, a code analysis for JavaScript, be it JS Hint, Resharper or of course SPCAF is extremely extensible and already provide many rules protecting you from harm.

Any questions?