Watch Your Scoping

I recently found a bug in a plugin and so I figured that would be a good time to offer a public service announcement as to why you have to be careful with scoping in JavaScript.  The plugin I’m featuring is just a quick example of the problem.  Suppose your had the following HTML snippet:


< div id="section1" class="section" >
First Button
< span id="sp1" >0< /span >
< /div >
< div id="section2" class="section" >
Second Button
< span id="sp2" >0< /span >
< /div >
< div id="section3" class="section" >
Third Button
< span id="sp3" >0< /span >
< /div >

Pretty simple. The idea of my plugin was to target the root DIV tag, and then parse down to the BUTTON and SPAN at an individual level. Now, as I think about writing this, the reality is of the situation, I should have considered the JQuery Widget API, as I think that would have been better situated for what I am about to do. I was under the gun to get this feature completed, and this solution was not optimal, but it worked and did get the job done. Anyway, the JQuery plugin is below:

$.fn.parse = function() {
  return this.each(function() {
    var spn = $(this).find("span");
    btn = $(this).find("button");
    
    btn.on("click", function(e) {
       var n = parseFloat(spn.html());
       n += 1;
       spn.html(n);
    
       btn.html(btn.html() + "(clicked)");
    });
  });
}

The idea is that the span and button are retrieved within the context of the root DIV, and when the button is clicked, both elements are updated to indicate that a click occurred. You’ll notice though, that while the span gets the proper update, the button does not (always targets the last). This is simply because the button doesn’t include “var” declaration. This means the button is scoped beyond the current context of the each() callback. Because of this, the last button was selected and thus the last button is represented in the query.

This produces the result:

jsscreenshot

Adding VAR was the immediate solution. Another reminder why you need to make sure you variables are scoped correctly.

Just to brainstorm, another solution could be to, using the current reference within the button click, access the button through the callback and even target the SPAN that way, rather than relying on variables.

You can view the Gist here.

Kendo UI Lists and Twitter Bootstrap Simplified

Bootstrap is a great CSS layout framework for setting up the user interface of your application. Bootstrap provides a grid system, whereby content can be structured into a grouping of columns up to a maximum of 12 total. This works great for laying out content, and can also be useful for layout out content in grids too. The following is an example of defining a template. Kendo uses templates to define the item view for the list. The following is a row within the eventual list rendered vertically:

<script type="text/x-kendo-template">
  <div class="row">
    <div class="col-md-3">
      #: FirstName #
    </div>
    <div class="col-md-4">
      #: LastName #
    </div>
    <div class="col-md-2">
      #: State #
    </div>
    <div class="col-md-3">
      <a href='@Url.Action("Where", "Some")/#=ID#'>
        View
      </a>
    </div>
  </div>
</script>

Next, we need to use the template, which we would supply to the kendo listview initialization plugin. Below is the initialization of the list, as well as the passing of the template to the list:

<div id="listview"></div>

  $(function() {
    $("#listview").kendoListView({
       autoBind: false,
       dataSource: new kendo.data.DataSource(..),
       template: kendo.template($("#template").html())
    });
  });

Notice our listview doesn’t need to define anything special; it gets built up by the kendoListView widget. The initialization properties passed are disabling auto binding on init (manual binding occurs later, which is good for views that need the user to interact with a form first). It also defines a data source and supplies our template.

The listview then binds the data, grabbing each record and generating a collection of <div class=”row”> objects, one for each record of data. That’s all that it takes to use the listview to bind a collection of rows using the bootstrap styles. Now when the screen collapses, each cell also collapses into it’s own row.

Building a Windows 8 Required Validator Control

Coming from an ASP.NET background, I’ve been used to the way ASP.NET validates user input.  ASP.NET made validation easy; a developer simply dropped a RequiredFieldValidator onto a web form, linked it to the control to validate, supply a set of initialization parameters, and voila, validation problem solved.  Of course, you’d run into some common configuration problems, some easily solved by validation groups, while others solved by some manual method calls.  This worked from the concept of web development, and it has some practicality in a Windows world, and as such, this article is going to look at building a similar capability in WinJS.  Note that I never meant for this component to encompass all validation scenarios, so you may find some faults in my implementation (feel free to point them out in the comments).

To start, we need a class.  Classes have always varied in implementation in the JavaScript world.  The approach WinJS uses is nothing new, but may be a hybrid of existing techniques.  A class starts with a WinJS.Class.define method call.  Define has the following signature:

define(function() { /* constructor */, { /* instance methods */ }, { /* static methods */ }

In our required validator example, we need to define our class as such:

var requiredValidator = WinJS.Class.define(

function (element, options) {
this.element = element;
this.element.winControl = this;        this._errormessage = null;
this._isvalid = true;
this._mode = “text”;
this._targetID = null;
this._text = null;

WinJS.UI.setOptions(this, options || {});

this._buildVisualTree();

var list = window[“Validators”];

if (!list)
list = [];

list.push(this);

window[“Validators”] = list;

},

.

.

);

The first parameter of the define method is the constructor (which is also the only one visible here), which performs a variety of steps.  The first wo steps are common with WinJS controls; we first store the element in an instance field, followed by creating the winControl object reference common through all WinJS component in the framework.  Ever wondered how other windows controls worked when you saw this code: document.querySelector(“#idofwindowscontrol”).winControl?  The setting of the winControl property above establishes the linkage.  Our validator needs to store data in variables defined on the instance (hence the this._X references), and supply them with defaults.  These store the options of the control, and are exposed as properties (which we’ll see later on).  For instance, you probably have seen usage of the data-win-options properties on WinJS control.  Suppose our validator has a configuration of data-win-options=”{text:’$$’, targetID:’#target’}”; the control receives these values in the constructor (via the options parameter), and the values are supplied to the text and targetID values through the control’s properties.  The setOptions method is the way to make this all happen.

Note that the control adds itself to a collection in the windows object; this way, the entire page  can access all of the validators on the view, similar to how ASP.NET provides all of the validators through it’s Page.Validators property.

The next code sample begins our instance methods, or the body of the class.  Notice WinJS (and IE 10 which runs the WinJS application) has a notation for properties using “get:” and “set:”, something that was missing in previous implementations of IE.  The first set of methods are actually property definitions (which consist of getter and setter methods):

errormessage: {
get: function () {
  return this._errormessage;
},
set: function (value) {
  this._errormessage = value;
}
},isvalid: {
get: function () {
  return this._isvalid;
},set: function (value) {
  this._isvalid = value;
  this._changeVisibility();
}},

Each of these properties has a get and set method, interacting with the instance variables defined in the constructor.  Even though the define method has separate method calls, we’re constructing one class, and as such, this just works.

In the class definition, the required validator also defines instance methods.  The following method builds the UI via traditional means, and styles it appropriately.  Nothing special here; it really doesn’t have to be.

_buildVisualTree: function () {
var el = this.element;
el.innerHTML = this.text || this.errormessage;
el.style.display = “none”;WinJS.Utilities.addClass(el, “Validator”);
},

Finally, we get to the main highlight of the control, which is the process for validating the content. Our validator first checks that the input of the control has been provided, and our target element has a valid length string.

_getValue: function() {
    var el = document.getElementById(this.targetID);
    var val;

    if (typeof (el.value) !== “undefined”)
        val = el.value;
    else
        val = el.innerHTML;

    return val;
},

validate: function () {
    var val = this._getValue();
   
    this.isvalid = !!val;
    this._changeVisibility();

    this.dispatchEvent(“validated”, { value: val, isValid: this.isvalid });

    return this.isvalid;
}

We have our validator, of which we can define as many as we want on the page. In ASP.NET, a postback to the page, when the control has it’s CausesValidation property set to true, invokes the validation process. Since we don’t have that here, I added one additional class, whose responsibility it is to trigger the validation, which is something we’ll look at in the next post (including it in this post made the post too long).

Using the Telerik RadDropDownList Control for Windows Store Apps (HTML/JavaScript)

I previously wrote about using the Telerik RadAutoCompleteBox control for Windows Store apps. We’re going to look at another control, which is the RadDropDownList control. This control is as simple as the RadAutoCompleteBox, and I’m going to include some additional steps not mentioned previously. So let’s get started. To begin, we need to add a reference to the Telerik.UI.DLL, which is available once you downloaded and installed the Windows 8 components.  Once installed, you can add a reference to it by right-clicking references, selecting “Add reference”.  It should appear in the extensions list.

Once you have this, we need to add some references to scripts and styles, as shown next:

<link href=”///Telerik.UI/css/common.css” rel=”stylesheet” />
<link href=”///Telerik.UI/css/dark.css” rel=”stylesheet” />
<script src=”///Telerik.UI/js/jquery.js”></script>
<script src=”///Telerik.UI/js/ui.js”></script>

Notice the triple slash at the beginning of the script.  This is the assembly notation.  This signals to the Windows framework to look in Telerik.UI.dll for the associated CSS and JS files, similar to how we pull out embedded references in the ASP.NET AJAX framework.

Next, we need to add a reference to the control in the page:

<span id=”Group” data-win-control=”Telerik.UI.RadDropDownList”
data-win-options=”{dataTextField:’GroupName’,dataValueField:’GroupUserName’,autoBind:false}”></span>

Here we create a new RadDropDownList and initialize the field names, which are pointers to fields in the objects bound to the list.  Next, the autoBind feature signals not to automatically bind on load.  This is because, in this example, we’re going to programmatically bind the grid.  I do so first by making a call to a backend service:

WinJS.xhr({
type:”get”,
url: “..”,
headers: { “content-type”: “application/json” }

})
.then(

function(d) {

var data = JSON.parse(d.response);
var dataSource = new Telerik.Data.DataSource(data);

var group = document.querySelector(“#Group”).winControl;
group.dataSource = dataSource;

}
);

Using the xhr function to make an XML HTTP request, the established JSON data returned from the backend service is passed to the Telerik data source and bound to the control.  Instead of binding from code, we can also bind data inline, as illustrated in the following example.  Below is a snapshot of an example created in the telerik sample documents.

<span id=”Span1″ data-win-control=”Telerik.UI.RadDropDownList” data-win-options=”{
dataSource: [
{ category: ‘Green’, color: ‘#7AD36A’, border: ‘#3A7E2B’ },
{ category: ‘Interesting’, color: ‘#9CB6E7’, border: ‘#28518E’ },
{ category: ‘Orange’, color: ‘#F9BA89’, border: ‘#B14F0C’ },
{ category: ‘Purple’, color: ‘#B6A2E3’, border: ‘#4C318E’ },
{ category: ‘Red’, color: ‘#E6A0A1’, border: ‘#A61C22’ },
{ category: ‘Yellow’, color: ‘#FCFA90’, border: ‘#A0981D’ }
]
}”></span>

I hope this was a good illustration of the Telerik RadDropDownList control, and how easy it is to use in your projects.

Icenium: Mobile HTML 5 Development Offering from Telerik

If you have looked at Telerik’s product offering lately, you may have noticed a new listing for Icenium, a cross-platform hybrid mobile development solution.  Icenium is a toolset allowing developers to code applications using HTML 5, CSS, and JavaScript.  Using Apache Cordova (AKA PhoneGap), Icenium provides a common toolset and framework for developing applications.  It also includes and online and installable editor for developing such applications.  This framework has the ability to push the applications to many test devices at once, allowing for a USB deployment.  However, when it comes time to publish the application, Icenium uses a cloud environment for building the application in each environment (iOS, Android, etc.).

I’m really looking forward to see what Icenium has to offer, and if it is as good as it’s other products are, Icenium is going to be an excellent choice for mobile development.  You can read a more detailed introduction here: http://www.icenium.com/community/blog/icenium-team-blog/2012/10/22/introducing-icenium—an-integrated-cloud-environment-for-hybrid-mobile-app-development

JQuery Mobile Part 2: Grids

JQuery Mobile incorporates a grid feature for laying out content.  It’s important to think of grids not as a grid for binding data, like the jqGrid.  A grid is more like a Twitter Bootstrap grid, where the a grid defines evenly-spaced columns.  For instance, if we wanted to define a two-column grid, we can use the following below:

<div class=”ui-grid-a”>
<div class=”ui-block-a”>First Name</div>
<div class=”ui-block-b”><input id=”FirstName” type=”text” /></div>
<div class=”ui-block-a”>Last Name</div>
<div class=”ui-block-b”><input id=”LastName” type=”text” /></div>
<div class=”ui-block-a”>Email</div>
<div class=”ui-block-b”><input id=”Email” type=”text” /></div>
</div>

Everything JQuery Mobile uses here is convention-based.  To define a grid, we use the ui-grid-X class, where X is a value between a and d.  A grid ending in “a” is a two-column grid, whereas a grid ending in “d” is a five-column grid.  Each column is evenly spaced, but also needs a CSS class to ensure the proper spacing.  Notice there are multiple elements defining a ui-block class, which defines each individual cell.  Each cell must use a suffix between “a” and “e”, depending on the number of cells.  For instance, ui-grid-a, a two-column grid, only uses two cells.  Only ui-block-a and ui-block-b are used in this case, otherwise the elements may not render correctly.  Similarly, if we were using ui-grid-c, we’d use ui-block-a, ui-block-b, ui-block-c, and ui-block-d, excluding ui-block-e which is only used for a 5 column grid (ui-grid-c is four columns).

Notice there is no explicit row designator.  JQuery Mobile is plenty capable of determining this.  Also, it’s possible to omit cells; JQuery Mobile will be able to handle scenarios where there is a 5-column grid, but only three cells included.

<div class=”ui-grid-d”>

<div class=”ui-block-a”>
First Cell
</div>
<div class=”ui-block-b”>
Second Cell
</div>
<div class=”ui-block-c”>
Third Cell
</div>
<div class=”ui-block-d”>
Fourth Cell
</div>
<div class=”ui-block-e”>
Fifth Cell
</div>

</div>

JQuery Mobile Part 1: Basics

JQuery Mobile is a client-side framework that creates a mobile experience on the web.  JQuery Mobile uses a combination of CSS and custom HTML 5 data attributes to create a special appearance for a view.  JQuery Mobile defines a page object, which is a portion of the current view to show to the user.  For instance, a single HTML file can contain one page, or multiple pages.  A page is represented by the following markup:

<div data-role=”page”>..</div>

To create a multi-page template, we simply create multiple pages:

<div id=”Page1″ data-role=”page”>..</div>
<div id=”Page2″ data-role=”page”>..</div>
<div id=”Page3″ data-role=”page”>..</div>

A page can have a header and footer, which can be defined as the following:

<div data-role=”page”>
<div data-role=”header”>..</div>
<div data-role=”content”>..</div>
<div data-role=”footer”>..</div>
</div>

JQuery mobile styles the header and footer to look like the header and footer of a mobile application.

When you have multiple pages, only one page appears at a time (the first one).  You can switch between views either programmably or using a hyperlink, which looks like the following:

<a href=”#Page2″ data-role=”button”>Page 2</a>

A data-role=”button” attribute styles the hyperlink as a button, and loads the next view using AJAX.  The above hyperlink links to another page; however, if you want to link to an external page, use a button that points to the external page as in the following:

<a href=”Pages-Multi.html” data-role=”button”>See Multi-Page Template</a>

Here JQuery will redirect to another page or external link; however, for external links, add a rel=”external” attribute.  This tells JQuery to handle the request specially.  JQuery also has the ability to change the page via script, using the $.mobile.changePage function.  This function takes the   URL to show (#Page or about.html) or a JQuery reference to an element.  See the API documentation for more information.

As changes between pages occur, JQuery supports using animations.  By adding to a button a data-transition attribute, the redirect to another page will use an animation.  For a demo of animations, see the following link.

For more information on pages, see the documentation at: http://jquerymobile.com/demos/1.2.0/docs/pages/index.html

HTML 5 Games with Lime JS, Part 4: Custom UI Classes

Lime JS, through Google Closure, provides an ability to define an inheritance structure, which doesn’t natively exist in JavaScript.  A sample JavaScript class may look like the following:

goog.provide(‘my.class’);

goog.require(‘lime.Sprite’);

my.class = function( /* ctor params */) {
lime.Sprite.call(this);
. . .
}

goog.inherits(my.class, lime.Sprite);

At the beginning of the class defines a provide statement, defining the name of the entity about to be created.  This is for Google Closure.  The require method defines related dependencies that are injected, as managed by Google Closure and not managed here.

The my.class statement defines the constructor of the class, defining any parameters needed at that time.  The first line makes a call to the base constructor; call(this) invokes the base type constructor.  The last line, goog.inherits, defines the inheritance structure, and structures it in a way that the methods of lime.Sprite can be called directly from within my.class (something that’s not always available in other inheritance frameworks).

In our sample demo game that we’ve been building, the letter that the user clicks on.

test.piece = function(letter, r, c, callback) {
goog.base(this);

this.letter = letter;
this.r = r;
this.c = c;

this.label = new lime.Label()
.setText(letter.letter)
.setSize(40,40)
.setFontSize(30);
this.appendChild(this.label);

.
.

}

Within the constructor of the piece, we are setting up fields on the piece itself to store the letter, row, and column.  We also construct the user interface by creating new primitive controls, setting their values, and appending the controls to the parent.  We could construct our own layers for this, if you need to, but I opted not to do that here.  Note that from a positioning perspective, if you were to use setPosition, it would be relative from the current location of the sprite; a position of 20,20 would be an offset of the current sprite, not a position defined on the root layer.

We can also append methods to a class by appending them to the prototype.  This appends methods to the signature of the class, not to a specific class instance.  Note that we can work with instances of objects within the prototype methods.  The label we setup in the constructor above can be modified here.

test.piece.prototype.highlight = function() {
  this.label.setFontColor(“blue”).setFontWeight(“bold”);
  this.isHighlighted = true;
};

test.piece.prototype.reset = function() {
  this.label.setFontColor(“black”).setFontWeight(“normal”);
  this.isHighlighted = false;
  this.isSelected = false;
};

If you are used to creating objects in JavaScript, this shouldn’t be foreign to you as a lot of class development in JavaScript is implemented this way.  Right after the constructor, we have one final step to add; we need to establish the inheritance hierarchy by specifying test.piece inherits from lime.Sprite as so:

goog.inherits(test.piece, lime.Sprite);

And there you have it, we have our own custom sprite class!

Lime JS DOM Rendering

WIth Lime JS, you can choose whether you want HTML or Canvas rendering; this means that the game can be built as elements in the DOM, or using the canvas instead.  It’s very simple to make this change, which can be done at the director or even layer level, using the code: setRenderer(lime.Renderer.CANVAS).  Lime JS has also recently added WebGL support, and you can find more information about it on their site.

When rendering to the DOM, internally LimeJS renders some HTML elements.  I’ve attached a snapshot of the DOM structure to give you an idea of what’s going on; however, first, let’s revisit the hierarchy of objects within LimeJS in order to make this discussion more meaningful.

At the root is the lime.Director.  A director uses a scene to draw to the screen, which a screen is made up of zero to many layers, and other objects.  Most, if not all, objects inherit from lime.Node, but certain objects provide more meaning.  The lime.GlossyButton utility renders a nice rounded corner button, whereas lime.Sprite represents a sprite object that contains rendered elements within.  If we were to draw a hieararchy of objects, it may look like:

lime.Director
    lime.Scene
        lime.Layer
            lime.Sprite

The DOM renderer renders the following hierarchy to the client as DIV elements with given CSS classes, such as the following.

<div class=”lime-director” style=”width: 800px; height: 600px; -moz-transform-origin: 0% 0%; -moz-transform: scale(0.1, 0.1) translate(3560px, 0px) scale(0.71, 0.71) scale(10, 10); opacity: 1; display: block;”>

<div class=”lime-scene” style=”display: block; width: 800px; height: 600px; -moz-transform-origin: 0% 0%; -moz-transform: scale(0.1, 0.1) translate(0px, 0px) scale(1, 1) scale(10, 10); opacity: 1;”>

<div class=”lime-layer” style=”width: 0px; height: 0px; -moz-transform-origin: 50% 50%; -moz-transform: scale(0.1, 0.1) translate(1000px, 1000px) scale(1, 1) scale(10, 10); opacity: 1; display: block;”>

Notice each class has a CSS class, but also applies certain styles inline.  The sprite objects rendered to to the UI also render similarly.  The following HTML below is used to render one letter in view.

<div style=”width: 0px; height: 0px; -moz-transform-origin: 50% 50%; -moz-transform: scale(0.1, 0.1) translate(1000px, 0px) scale(1, 1) scale(10, 10); opacity: 1; display: block; border-width: 0px;”>

<div style=”width: 40px; height: 40px; -moz-transform-origin: 50% 50%; -moz-transform: scale(0.1, 0.1) translate(-200px, -200px) scale(1, 1) scale(10, 10); opacity: 1; display: block; background: none repeat scroll 0% 0% rgba(255, 255, 255, 0); border-width: 0px; line-height: 1.15; padding: 0px; color: black; font-family: Arial; font-size: 30px; font-weight: normal; text-align: center;”>G</div>

</div>

That is quite an amount of HTML to use for one letter, but it’s needed for applying certain styles that are needed to make some of the transitional capabilities (animations, etc.) work.  Additionally, LimeJS renders attributes specific to the browser it’s being rendered for.  For instance, notice in the first example the reference to -moz-transform; the browser being used was FireFox 14.0.1.  When I switch to chrome, we see some references to -webkit-transform and other related properties, as in this partial snippet below

<div style=”. . .  -webkit-transform-origin: 50% 50%; -webkit-transform: scale(0.1, 0.1) translate(500px, 0px) scale(1, 1) scale(10, 10); . . .

Note that it’s not important to know how the internals work to build your game, but it’s always a good idea to know what’s going on inside any program so that you have an idea of what to do when you run into errors, glitches, or performance problems.  I hope this gave a slight glimpse into the DOM rendering capability.

HTML 5 Games with Lime JS, Part 3: Animation

Lime JS is not without the added bells and whistles that make the framework great. Lime JS is complete with various types of animations. From their own web site (referenced here), Lime JS has the following animations:

  • MoveBy – move object by offset from current location.
  • MoveTo – move object to specific location.
  • ScaleBy – scale objects dimensions by a factor. Passing 2 makes object 2 times bigger from its current size.
  • ScaleTo – scale objects dimensions to a given factor.
  • RotateBy – rotate object by a given angle
  • RotateTo – rotate object to a specific angle
  • ColorTo – change objects color from current color to another.
  • FadeTo – fade elements opacity to a given value.

Each of these objects is instantiated in the following manner:

lime.animation.MoveBy()

Where several of the animation attributes are supplied to the constructor.   Each animation is different, and will require different parameters.  The sample effect I was trying to achieve was to fade an element out and back in quickly.  Using the following code, I defined the fade out and in as:

var fadeToAnim = new lime.animation.FadeTo(.5).setDuration(.1);
var fadeBackAnim = new lime.animation.FadeTo(1).setDuration(.1);

You have to think about how fast you want the animation.  Because this is animating letter pieces that the user selects, it needs to be fast.  I chose .1 because it’s very fast with minimal interruption to the user (as of current testing, but may change when played competitively).  To run an animation, get a reference to a lime object, and call runAction.

In order to know when the first animation stopped, we need to attach an event handler to the stop event, defined by a constant, and perform the respective actions.  When the fadeToAnim animation stopped, it triggered the fadeBackAnim animation, then run some additional code after that.

var el = //some element;

this.runAction(fadeToAnim);

goog.events.listen(fadeBackAnim, lime.animation.Event.STOP, function() {

});
goog.events.listen(fadeToAnim, lime.animation.Event.STOP, function() {
el.runAction(fadeBackAnim);
});

All in all, the animation I chose wasn’t the best option for my particular needs.  What I wanted was an animation that ran when two letters were clicked on.  The user chooses the first letter, then selects a second, and the two swap spaces.  The animation that runs this is the MoveTo animation, which moves an object from one space to the other.  The animation uses the following code:

var pPos = piece.getPosition();
var cPos = compare.getPosition();

var pMove = new lime.animation.MoveTo(cPos.x, cPos.y)
.setDuration(.3).enableOptimizations();

var cMove = new lime.animation.MoveTo(pPos.x, pPos.y)
.setDuration(.3).enableOptimizations();

piece.runAction(pMove);
compare.runAction(cMove);

Objects in lime have a getPosition method, which returns the position of the element.  Using this position, the animation calculates the new position of the element, and moves it within a duration of .3 seconds.  Since the action should happen at the same time, we do not need to layer the animation using callbacks; they can run at the same time.

You can see the current progress of this game using the following URL; this test page is hosted on Brinkster.com, a capable host that offers free ASP.NET hosting for personal use:  http://bmains.brinkster.net/lettergame/lettergamephase1.html