-
Notifications
You must be signed in to change notification settings - Fork 137
Design Standards
The design guidelines in this section are intended to encourage good practices that lead to maintainable, supportable, well performing scripts.
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);
To make client classes operate in AJAX Control Toolkit environment, properly follow the set of design rules below.
Call initializeBase
at the first line in the constructor:
MyNamespace.Sample = function() {
MyNamespace.Sample.initializeBase(this);
...
}
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');
}
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');
}
-
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); }
-
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);
-
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.
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.
Define enumerations as a JavaScript object:
Sys.UI.Key = {
left: 37,
up: 38,
right: 39,
down: 40
}
Call the base method using callBaseMethod
where applicable:
Sys.Extended.UI.MyControl.prototype = {
initialize: function() {
Sys.Extended.UI.MyControl.callBaseMethod(this, 'initialize');
...
}
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 = [];
}
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.
This content was moved from https://ajaxcontroltoolkit.codeplex.com/documentation to this Documentation wiki. This is now the authoritative location of the AJAX Control Toolkit documentation.
- Step-by-Step Installation Guide
- Upgrading from v7.x and below
- Uninstalling the AJAX Control Toolkit
- Troubleshooting Installer Issues
- Updating the Project from CI Builds
- How to Use Bundling and CDN
- Creating a Custom Localization
- Creating a Custom Control
- Design Standards
Controls:
- Accordion
- AjaxFileUpload
- AreaChart
- AsyncFileUpload
- BarChart
- BubbleChart
- ComboBox
- Editor (deprecated)
- Gravatar
- LineChart
- NoBot
- PieChart
- Rating
- ReorderList
- Seadragon
- TabContainer
- TabPanel
Extenders:
- AlwaysVisibleControl
- Animation
- AutoComplete
- BalloonPopup
- Calendar
- CascadingDropDown
- CollapsiblePanel
- ColorPicker
- ConfirmButton
- DragPanel
- DropDown
- DropShadow
- DynamicPopulate
- FilteredTextBox
- HoverMenu
- HtmlEditor
- ListSearch
- MaskedEdit
- MaskedEditValidator
- ModalPopup
- MultiHandleSlider
- MutuallyExclusiveCheckBox
- NumericUpDown
- PagingBulletedList
- PasswordStrength
- PopupControl
- ResizableControl
- RoundedCorners
- Slider
- SlideShow
- TextBoxWatermark
- ToggleButton
- UpdatePanelAnimation
- ValidatorCallout