Blog Archive

Home
.Net Development

“This. Is Not. For. Practice!” – a phrase used to emphasize that you must get things right.  Mentors have used it to mean “Get serious, now!”.

For years jQuery has been a tremendous productivity boost for client-side development; so successful, that it gave rise the Single Page Application (SPA) where a good portion of your application logic was now written with Javascript. Soon, so soon, we all learned that the increased complexity of our client side solutions required good organization, a better architecture.  Time to get serious about clean code.

If you are .Net developer, then many times you can fall into the ECMAScript trap: all ECMAScript must be the same.  What I know from C# must be applicable to Javascript, ’cause it looks the same. Sad news, it’s not. Javascript executes in a much different environment. And to make things more confusing, close cognates such as this are not close enough. “this” in C# is a reference to the current object. “this” is Javascript is , well, it all depends. “this” in Javascript changes context dependent on many factors.  A good reference is here at Mozilla.  Let’s create a quick summary, and where relevant we’ll talk relevant areas that impact programming practice:

Global Context

When you are outside any function, this is referred to as the global context.  ”this” will refer to document.  So if you fire up the console and perform this test:


console.log(this == document); // true.

And in web browsers this also equals the window.  So:


console.log(this == window); // true.

Yikes!  Wait there’s more.  Try this little piece:


var yikes = "ouch";

console.log(window.yikes); // ouch

window is our global memory space.  So think back to any client side code you have written, and this should be very familiar to you:


<script type="text/javascript" src="scripts/jquery.min.js"></script>

This loads jQuery into the global memory space.   Go look at window and you will see “window.$” and “window.jQuery”.  You guessed it, jQuery is now loaded into the global namespace.

This may seem like a digression, but we need to pause at this very important point.  You must be really careful what you put into this global space.  As you grow in Javascript capability you will eventually develop your own utils or libraries.  So consider this very innocent utility file:

  function objectToArray(sourceObj) {
    var results = [];

    for (var key in sourceObj) {
      if (sourceObj.hasOwnProperty(key)) {
        var newObj = sourceObj[key];
        newObj.objectKey = key;
        results.push(newObj);
      }
    }

    return results;
  };

function localize(t) {
  var d = new Date(t + " UTC");
  return d;
}

function parseDecimal(d, zeros, trunc) {
  if (d == null)
    return 0;

  if (typeof d == "number") {
    return parseFloat(d);
  }

  d = d.replace(/[a-zA-Z\!\@\#\$\%\^\&\*\(\)\_\+\-\=\{\}\|\[\]\\\:\"\;'\<\>\?\,\/\~\`]/g, "");
  while (d.indexOf(".") != d.lastIndexOf("."))
  d = d.replace(/\./, "");

  if (typeof zeros == 'undefined' || zeros == "") {
    return parseFloat(d);
  }
  else {
    var mult = Math.pow(10, zeros);
    if (typeof trunc == 'undefined' || (trunc) == false)
      return parseFloat(Math.round(d * mult) / mult);
    else
      return parseFloat(Math.floor(d * mult) / mult);
    }
};

All of these functions are now attached to the global namespace, our what is called “polluting the global namespace”.  Most likely a utility class will have 20 – 30 functions, not the mere three listed above.  These functions will remain in memory until the user refreshes or navigates away from the page.  With a small app, this will be no problem, but anything with a moderate degree of code will soon balloon and consume memory.  And in some cases, such as a mobile friendly websites, you want to conserve as much memory as you can, only loading the objects that you need then allowing them to be garbage collected.

Wow – we’ve only covered “this” in a global context, and if your head isn’t a little numb, don’t worry, do another shot and see if it gets worse!

Function Context – Simple Call

Here we get a strange, as this is the rule:  ”this” will depend on how the function is called.  Consider this code:


var myFunc = function(){
   return this;
 };

myFunc() == window;

Since we are not using strict mode “this” must refer to something so it will default to the global object.  Changing the code to:


var myFunc = function(){
  "use strict";
  return this;
 };

myFunc() == "undefined";

Function Context – As An Object Method

The rule here is “this” refers to the object that the method is called on.  For example:


var mathDoer = {
  someNumber: 13,

  addSomeNumber: function(addMe){
    return this.someNumber + addMe;
  };
 };

mathDoer.addSomeNumber(7); // returns 20

You’ll note that both mathDoer.someNumber and mathDoer.addSomeNumber() are public in scope.  When first developing in Javascript it may be tempting to create your objects as depicted below, and while it is legitimate, it will lead to clutter very quickly:


var mathDoer = {};

mathDoer.someNumber = 13;

mathDoer.someArray = [];

mathDoer.addSomeNumber = function(){ ...};

Imagine this is a none trivial object, and you will have a cluttered mess.  Also, all your methods and properties are public, which you may not want to expose.

Function Context – As A Constructor

When used in a constructor “this” will refer to the object that is being instantiated.  This is best illustrated with the following:


var mathDoer = function(){
this.someNumber = 13;

this.addSomeNumber = function(addMe){
    return this.someNumber + addMe;
  };
 };

var mathIsFunObj = new mathDoer();

mathIsFunObj.addSomeNumber(7); // returns 13

Many of you may be coming to Javascript via KnockoutJS, a data binding library that provides two way binding between the DOM and Javascript objects.  Many of the KnockoutJS samples use this “style” for creating ViewModels:


var mathDoerViewModel = function(){
  this.justAnInt = 5;
  this.someNumber = ko.observable();

  this.addSomeNumber = function(addMe){
    return addMe + this.someNumber();
  };
};

var vm = new mathDoerViewModel();
ko.applyBindings(vm);

Again, our observables and functions are public in scope.  If you have a separate file for this ViewModel and simply include it with the HTML your “vm” variable is now added to the window object and part of the global memory space.  This can be considered good or bad.  From a diagnostics perspective, you can sit at the console and see what our ViewModel is doing by simply issuing commands like “vm.someNumber(45);”  Good for debugging.  This is also considered bad by others for two reasons: everything is public, and this can lead to bloated objects that are hard to use; and, you have added yet another item to the global memory space.  Imagine you have several ViewModels for a single page.  Things can get confusing very quickly.

So how can you make items private?  Remember that the scope of “this” when used in a constructor is a reference to that object – in our case that object is mathDoerViewModel.  If you were merely to declare a variable in the constructor, the scope of that variable would be local to the constructor.  This “hides” the variable from contexts that are outside the scope of the constructor.  That would look like this:


var mathDoerViewModel = function(){
  var _justAnInt = 5; //this makes the variable private

  //  function is local in scope
  var privateFunction = function(){

    //  our locals are available as well a methods and properties from the object ("this")
    return _justAnInt + this.someNumber();
  };

  this.someNumber = ko.observable();

  this.addSomeNumber = function(addMe){
    return addMe + this.someNumber();
  };
};

From the console still can interact with mathDoerViewModel.someNumber() and mathDoerViewModel.addSomeNumber(). We also have private functions and variables now: _justAnInt and privateFunction. For the .Net developer these conventions should have more familiar feel.

When you scour the web for Javascript code, you’ll find that many of the Javascript heavies will use a different standard for variable / scope hiding. We touch on that briefly here before we move on.  In Javascript, your constructor returns a reference to the object you are creating.  In other words, your constructor will return a version of “this” that refers to the objects properties and functions.  However, your constructor can also return an object.  This gives you great flexibility, and makes the  “Module Reveal Pattern” possible.  First here is what our ViewModel would look like using the Module Reveal Pattern:


var mathDoerViewModel = function(ko){

  var _justAnInt = 0;
  var _someNumber = ko.observable();

  var privateFunction = function(){
    return _justAnInt + _someNumber();
  };

  var addSomeNumber = function(addMe){
    return addMe + _someNumber();
  };

  var setJustAnInt = function(value){
    _justAnInt = value;
  };

  var showMeTheInt = function(){
    return justAnInt;
  };

  //  We return an object that refers to items we want to be public
  return {
    someNumber: _someNumber,
    addSomeNumber: addSomeNumber,
    showMeTheInt: showMeTheInt
  };
};

Looks a little different. In our constructor we are creating local variables and local functions, and in fact our observable – _someNumber – is now a local variable. But we “reveal” the items that we want to be public with the “return” statement. So in this case, we return an object with someNumber that references _someNumber, and references addSomeNumber. As a result, we can create:

  var vm = new mathDoerViewModel(ko);

  // Set value of someNumber
  vm.someNumber(35);
  vm.addSomeNumber(5); // returns 40

  //  Let's use our setter
  vm.setJustAnInt(12);
  vm.showMeTheInt(); // returns 12

Notice that we are passing in a “ko” variable in the constructor call. This serves many purposes: firstly, it makes the ViewModel modular, and allows us to load the module asynchronously with AMD tools like requirejs or curljs; secondly, the constructor signature lets us know that we are depending “ko” to make our ViewModel work; finally, it gives us a tiny speed boost as now that “ko” is local, since Javascript does not have to search up the stack to find it.

You should avail yourself of the fantastic book “Learning Javascript Design Practises” by Addy Osmani.  He’s been kind enough to place a copy online.  This will help you understand some of the code that is that would otherwise seem very strange compared to what you are used to in C#.

Function Context – As A DOM Handler

Moving on the DOM, “this” takes on a different context.  You’ll most likely be familiar with this common jquery statement:


$(".apparea").on("mouseover", ".milestone-border", function (event) {
//   here this means the DOM element with a class of "milestone-border"

$(this).addClass("selected-children");
 });

The rule here is that “this” means the DOM object that fires the handler.  So in this case “this” is equal to event.currentTarget.

Go Forth And Create

ImageBy now your head should hurt a little, with all these nuances it’s wonder that you don’t feel more beaten up.  That’s where the complexity of web development is under appreciated.  Hopefully we have covered enough here for you to save some time debugging, designing, or trying to understand some the vast Javascript frameworks, utils and libraries that are out there.  If you are coming from .Net and are new to Javascript, you avoid the trap that many have fallen into of creating monstrous Javascript objects of pure public functions and properties jammed into a single file.  This will lead to a deep valley of frustration when it comes time to refactor your code after you realize you have a hard time maintaining things.  If you can keep your code modular and have things reside in separate files, you’ll be better off.

We covered “this” in order to reveal some deeper yet vital nuances to Javascript.  Mastering “this” and the related topics above are going to help.  A lot.  This brings Javascript from being a “toy” to  really productive platform because you can avoid some pitfalls that slow you down.  In future posts we continue to build on this foundation where we focus on modular design and asynchronous loading.

This post focuses on getting started with RavenDB, so we’ll set aside our focus on workflows for a bit.  It’s included in the ApprovaFlow series as it is an important part of the workflow framework we’re building.  To follow along you might want to get the source code.

RavenDB is a document database that provides a flexible means for storing object graphs.  As you’ll see a document database presents you with a different set of challenges than you are normally presented when using a traditional relational database.

The storage “unit” in RavenDB is a schema-less JSON document.  This takes the form of:  Because you are working with documents you now have the flexibility to define documents differently; that is, you can support variations to your data without have to re-craft your data model each time you want to add a new property to a class.  You can adopt a “star” pattern for SQL as depicted here, but querying can become difficult.  Raven excels in this situation and one such sweet spot is:

Dynamic Entities, such as user-customizable entities, entities with a large number of optional fields, etc. – Raven’s schema free nature means that you don’t have to fight a relational model to implement it.

Installing and Running RavenDB

The compiled binaries are easy to install.  Download the latest build and extract the files to a share.  Note that in order to run the console you are required to install Silverlight.  To start the server, navigate to the folder[] and double click “Start.cmd”.  You will see a screen similar to this one once the server is up and running:

The console will launch it self and will resemble this:

How To Start Developing

In Visual Studio, reference Raven with Raven.Client.Lightweight.  For CRUD operations and querying this will be all that you will need.

First you will need to connect to the document store.  It is recommended that you do this once per application.  That is accomplished with


var documentStore = new DocumentStore {Url = "http://localhost:8080"};
documentStore.Initialize();

Procedures are carried out using the Unit of Work pattern, and in general you will be using these type of blocks:


using(var session = documentStore.OpenSession())
{
   //... Do some work
}

RavenDB will work with Plain Old C# Objects and only requires an Id property of type string.  An identity key is generated for Id during this session.  If were were to create multiple steps we would have identities created in succession.  A full discussion of the alternatives to the Id property is here.

Creating a document from your POCOs’ object graphs is very straight forward:


public class Person
{
    public string FirstName { get; set; }
	public string LastName { get; set; }
	public string Id { get; set; }
	public int DepartmentId { get; set; }
    // ...
}

var person = new Person();

using(var session = documentStore.OpenSession())
{
   session.Store(person);
   session.SaveChanges();
}

Fetching a document can be accomplished in two manners:  by Id or with a LINQ query.  Here’s how to get a document by id:


string person = "Person/1";  //  Raven will have auto-generated a value for us.
using(var session = documentStore.OpenSession())
{
   var fetchedPerson = session.Load<Person>(personId);
   //Do some more work
}

You’ll note that there is no casting or conversion required as Raven will determine the object type and populate the properties for you.

There are naturally cases where you want to query for documents based on attributes other than the Id. Best practices guides that we should create static indexes on our documents as these will offer the best performance. RavenDB also has a dynamic index feature that learns from queries fired at the server and over time these dynamic indexes are memorialized.

For your first bout with RavenDB you can simply query the documents with LINQ.   The test code takes advantage of the dynamic feature.  Later you will want to create indexes based on how you most likely will retrieve the documents.  This is different that a traditional RDMS solution, where the data is optimized for querying.  A document database is NOT.

Continuing with our example of Person documents we would use:


int departmentId = 139;

using(var session = documentStore.OpenSession())
{
   var people = session.Query<Person>()
                          .Where(x => x.DepartmentId == departmentId)
                          .ToList();
}

In the source code for this post there are more examples of querying.

Debugging, Troubleshooting and Dealing with Frustration

Given that this is something new and an open source project you may find yourself searching for help and more guidelines.  One thing to avail yourself of while troubleshooting is the fact that RavenDB has REST interface and you can validate your assumptions – or worse, confirm your errors – by using curl from the command line.  For example, to create a document via http you issue:

curl -X POST http://localhost:8080/docs -d "{ FirstName: 'Bob', LastName: 'Smith', Address: '5 Elm St' }"

Each action that takes place on the RavenDB server is displayed in a log on the server console app.  Sensei had to resort to this technique when troubleshooting some issues when he first started.  This StackOverflow question details the travails.

Another area that threw Sensei for a loop at first was the nature of the RavenDB writing and maintaining indexes.  In short, indexing is a background process, and Raven is designed to be “eventually consistent”.  That means that there can be a latency between when a change is submitted, saved, and indexed in the repository so that it can be fetched via queries.  When running tests from NUnit this code did not operate as expected, yet the console reported that the document was created:


session.Store(teamMember);

int posttestCount = session.Query<TeamMember>()
                .Count();

According to the documentation you can overcome this inconsistency by declaring that you are willing to wait until RavenDB has completed its current write operation.   This code will get you the expected results:


int posttestCount = session.Query<TeamMember>()
              .Customize(x => x.WaitForNonStaleResults())
              .Count();

Depending on the number of tests you write you may wish to run RavenDB in Embedded mode for faster results.  This might prove useful for automated testing and builds.  The source code provided in this post does NOT use embedded mode; rather, you have need your server running as this gives you the opportunity to inspect documents and acclimate yourself to the database.

There is much more that you can do with RavenDB, such as creating indexes across documents, assign security to individual documents, and much more.  This primer should be enough to get you started.  Next post we’ll see how RavenDB will fit into the ApprovaFlow framework.  Grab the source, play around and get ready for the next exciting episode.

 

[gigya src="http://listen.grooveshark.com/songWidget.swf" width="204" height="40" flashvars="hostname=cowbell.grooveshark.com&widgetID=25064281&style=water&p=0" allowScriptAccess="always" wmode="window" ]

Like Tolkien, Sensei wants to create the landscapes, cultures and languages before he writes his next epic. You can be the judge whether the work is a series of sketches and notes like the Silmarillion or cohesive, compelling story that you want read again and again. As a bonus Sensei will deliver working software that hopefully will be of use to you.  (Photo credit - utnapistim).

The epic will be called ApprovaFlow. ApprovaFlow is a framework / process / methodology that allows you to create workflow applications that are easy to deploy and are configurable. With ApprovaFlow Sensei hopes to demonstrate how to readily encorporate the inevitable changes that your users will ask of you. Deliver changes effortlessly and without groans. Cast off the chains inconvenient builds and focus on creating solutions that stay out of the users way.

Ok. Managent wants bullet points so here are our goals for ApprovaFlow:

• Model a workflow in a clear format that is readable by both developer and business user. One set of verbiage for all parties.
•. Allow the state of a workflow to be peristed as an integer, string. Quicky fetch state of a workflow.
•. Create pre and post nprocessing methods that can enforce enforce rules or carry out actions when completing a workflow task.
•. Introduce new functionality while isolating the impact of the new changes. New components should not break old ones
•.Communicate to the client with a standard set of objects. In other words, your solution domain will not change how the user interface will gather data from the user.
•. Use one. aspx page to processes user input for any type of workflow.
•. Provide ability to roll your own customizations to the front end or backend of your application.

There it is. These goals will probably take us a good amount of time to review and implement. Is it worth it? Hell yeah. We’ll end up with one simple project instead of a bloated framework where it takes forever to find anything. A nice by product will be that you can spend more time thinking about how to solve your users problems rather than trying to figure out a monsterous framework that requires a huge investment of energy and time learning how to get simple things done.


ActiveEngine Software by ActiveEngine, LLC.