Skip to content
This repository has been archived by the owner on Oct 14, 2024. It is now read-only.

Design Standards

MikhailTymchukDX edited this page Jan 23, 2017 · 7 revisions

The design guidelines in this section are intended to encourage good practices that lead to maintainable, supportable, well performing scripts.

  1. Choosing a parent class
  2. Implementing class members
  1. Documentation
  2. Minification

Choosing a Parent Class

Use Sys.UI.BehaviorBase as the base class for a script that enhances an existing DOM element. When using ASP.NET Web Forms, associate the script Behavior with a server-side Extender.

Use Sys.UI.ControlBase as the base class for a script that fundamentally changes a single DOM element’s behavior to provide new functionality. When using ASP.NET Web Forms, associate the script Control with a server-side control.

When selecting a base class, prefer Sys.Component where possible. If the control has visual representation through a relationship with a DOM element, stick to Sys.UI.Behavior where possible. This means that multiple Behaviors may be applied to a single DOM element instead of a Control which takes exclusive ownership of a single DOM element at a time.

Use the Type.registerClass method to define the base class for a script when inheritance functionality is required, such as implementing an interface, overriding base class members, or creating Components, Controls or Behaviors:

MyNamespace.MyClass.registerClass('MyNamespace.MyClass', Sys.IComponent);

Implementing Class Members

To make client classes operate in AJAX Control Toolkit environment, properly follow the set of design rules below.

Constructor

Call initializeBase at the first line in the constructor:

MyNamespace.Sample = function() {
    MyNamespace.Sample.initializeBase(this);
    ...
}

Disposing

Call $removeHandler to remove a particular handler. Call $clearHandlers to remove all handlers attached to a DOM element.

Ensure that member variables holding references to DOM elements or browser plug-ins are set to null:

this._myEventHandler = null;

or

delete this._myEventHandler;

When implementing the dispose method, call the dispose method of the base class as the final action:

dispose: function dispose() {
    $clearHandlers(this.get_element());
    this._myEventHandler = null;
    MyNamespace.MyClass.callBaseMethod(this, 'dispose');
}

Properties

Apply the ExtenderControlProperty attribute to bind a server property to a client property with the same name. Client properties have get_ and set_ prefixes. Apply the ClientPropertyName attribute if a client property name differs from a server property.

Server:

[ExtenderControlProperty()]
[ClientPropertyName("myClientProperty")]
public int MyProperty { get; set; }

Client:

get_myClientProperty: function () {
},
set_myClientProperty: function () {
}

Call raisePropertyChanged to notify about property change:

set_text: function(value) {
    ...
    this.raisePropertyChanged('text');
}

Events

  1. Create public methods to add and remove an event handler.

    add_amountChanged: function(handler) {
    	this.get_events().addHandler("amountChanged", handler);
    }
    remove_amountChanged: function(handler) {
    	this.get_events().removeHandler("amountChanged", handler);
    }
  2. Optionally, create a class derived from Sys.EventArgs to carry any data payload.

    MyNamespace.AmountChangedEventArgs =  function(amount) {
    	MyNamespace.AmountChangedEventArgs.initializeBase(this);
    	...
    }
    
    MyNamespace.AmountChangedEventArgs.prototype = {
    	get_amount: function get_amount () {
    		...
    	}
    }
    
    MyNamespace.AmountChangedEventArgs.registerClass(‘MyNamespace.AmountChangedEventArgs’, Sys.EventArgs);
  3. Create a method prefixed by raise_ to raise each event. Allow the Sys.EventArgs derived class to be passed as a parameter, if required.

    raise_amountChanged: function(args) {
    	var handler = this.get_events().getHandler("amountChanged");
    	if (handler)
    	   handler(this, args);       	
    }

Do not pass null as the sender or EventArgs parameter. By default, use this and EventArgs.Empty respectively.

Event Handlers

Define event handlers to expect two parameters;

_handleAmountChanged: function(sender, args) {
    ...
}

Use the Function.createDelegate method when attaching a handler to an event from within a class instance:

var handler = Function.createDelegate(this, this._handleAmountChanged);

This ensures that it refers to the current class instance in the _handleAmountChanged method.

Enumerations

Define enumerations as a JavaScript object:

Sys.UI.Key = { 
    left: 37,
    up: 38,
    right: 39,
    down: 40
}

Overriding Base Class Behavior

Call the base method using callBaseMethod where applicable:

Sys.Extended.UI.MyControl.prototype = {
    initialize: function() {
        Sys.Extended.UI.MyControl.callBaseMethod(this, 'initialize');
        ...
}

Documentation

Client-side documentation tags mainly reflect server-side XML-documentation with a few exceptions.

Every documented member has a <member> tag with an attribute name. This attribute has one of the following prefixes:

  • cP: for properties
  • cM: for methods
  • cE: for events

Properties have to be documented with an additional tag <getter> and <setter>, if supported. These tags contain a property getter and setter method names.

MyNamespace.MyClass = function(elements) {
    /// <summary>
    /// A list of data.
    /// </summary>
    /// <getter>get_data</getter>
    /// <setter>set_data</setter>
    /// <member name="cP:MyNamespace.MyClass.data" />	
    this._data = [];
}

Minification of Client Resources

JavaScript files come in two variants: the debug and release version. The debug version’s name ends with .js, while the release version’s name ends with .min.js

CSS files also have two variants. The debug version’s name ends with .css, while the release version’s name ends with .min.css.

Visual Studio 2015 automatically minifies JavaScript and CSS files using gulp tasks.

To make a minified version of these files in Visual Studio 2013 or earlier, use the Web Essentials extension.

Note: results of minification made in Visual Studio 2015 differ from the previous VS versions.

Clone this wiki locally