Appendix D: Data Control Next, it checks whether the bound data collection implements the IData interface If so, it invokes the add method on the data collection to add an empty record to the collection: if (Sys.Preview.Data.IData.isImplementedBy(this._data)) this._data.add({}); If the bound data collection is a JavaScript array, and if it exposes a method named add, the addItem method simply calls this method to add an empty record to the data collection: else if (this._data instanceof Array) { if(typeof(this._data.add) === “function”) this._data.add({}); If the bound data collection is a JavaScript array but it does not expose the add method, the addItem method simply calls the add static method on the Array class to add an empty record to the data collection: else if (this._data instanceof Array) { if(typeof(this._data.add) === “function”) this._data.add({}); else Array.add(this._data, {}); } Next, the addItem method sets the current data index to the index of the newly added data record: this.set_dataIndex(this.get_length() - 1); Finally, the addItem method calls the triggerChangeEvents method, passing the JavaScript object that contains the old values of the dataIndex, canMoveNext, and canMovePrevious properties to raise the appropriate events, as discussed earlier: this.triggerChangeEvents(oldState); Listing D-14: The addItem Method function Sys$Preview$UI$Data$DataControl$addItem() { if (this._data) { var oldState = this.prepareChange(); if (Sys.Preview.Data.IData.isImplementedBy(this._data)) this._data.add({}); (continued) 1367 bapp04.indd 1367 8/20/07 8:59:57 PM Appendix D: Data Control Listing D-14 (continued) else if (this._data instanceof Array) { if(typeof(this._data.add) === “function”) this._data.add({}); else Array.add(this._data, {}); } this.set_dataIndex(this.get_length() - 1); this.triggerChangeEvents(oldState); } } deleteCurrentItem As the name suggests, the deleteCurrentItem method deletes the current data record from the bound data collection — if the data control is indeed bound to a data collection As Listing D-15 shows, this method begins by invoking the prepareChange method to return the JavaScript object that contains the current values of the dataIndex, canMoveNext, and canMovePrevious properties: var oldState = this.prepareChange(); Next, it sets an internal flag to true to signal that all change notifications must be suspended because we’re about to introduce new changes: this._suspendChangeNotifications = true; Then it calls the get_dataItem getter to return a reference to the current data record: var item = this.get_dataItem(); Next, it resets the current data index if the current data record is the last data record in the data collection: if (this.get_dataIndex() === this.get_length() - 1) this.set_dataIndex(Math.max(0, this.get_length() - 2)); Then it checks whether the bound data collection implements the IData interface If so, it invokes the remove method on the bound data collection to remove the current data record: if (Sys.Preview.Data.IData.isImplementedBy(this._data)) this._data.remove(item); Next, the deleteCurrentItem method checks whether the bound data collection is a JavaScript array and whether it supports the remove method If so, it invokes the remove method on the data collection to remove the current data record: 1368 bapp04.indd 1368 8/20/07 8:59:57 PM Appendix D: Data Control else if (this._data instanceof Array) { if(typeof(this._data.remove) === “function”) this._data.remove(item); If the bound data collection is a JavaScript array but does not support the remove method, it calls the remove static method on the Array class to remove the current data record for the data collection: else if (this._data instanceof Array) { if(typeof(this._data.remove) === “function”) this._data.remove(item); else Array.remove(this._data, item); } Next, it resets the _suspendChangeNotifications flag to allow change notifications: this._suspendChangeNotifications = false; Finally, it invokes the triggerChangeEvents method, passing in the JavaScript object that contains the old values of the dataIndex, canMoveNext, and canMovePrevious properties, to trigger the required events, as discussed earlier: this.triggerChangeEvents(oldState); Listing D-15: The deleteCurrentItem Method function Sys$Preview$UI$Data$DataControl$deleteCurrentItem() { if (this._data) { var oldState = this.prepareChange(); this._suspendChangeNotifications = true; var item = this.get_dataItem(); if (this.get_dataIndex() === this.get_length() - 1) this.set_dataIndex(Math.max(0, this.get_length() - 2)); if (Sys.Preview.Data.IData.isImplementedBy(this._data)) this._data.remove(item); else if (this._data instanceof Array) { if(typeof(this._data.remove) === “function”) this._data.remove(item); else Array.remove(this._data, item); } this._suspendChangeNotifications = false; this.triggerChangeEvents(oldState); } } 1369 bapp04.indd 1369 8/20/07 8:59:58 PM Appendix D: Data Control getItem The getItem method of the DataControl base class enables you to return a reference to the data record with the specified data index As you can see from Listing D-16, this method first checks whether the data control is indeed bound to a data collection If not, it returns null If so, it checks whether the bound data collection implements the IData interface If so, it simply calls the getItem method on the data collection to return a reference to the data record with the specified index: if (Sys.Preview.Data.IData.isImplementedBy(this._data)) return this._data.getItem(index); If not, it checks whether the bound data collection is a JavaScript array If so, it uses the specified data index as an index into the data collection to return a reference to the data record with the specified index: if (this._data instanceof Array) return this._data[index]; Listing D-16: The getItem Method function Sys$Preview$UI$Data$DataControl$getItem(index) { if (this._data) { if (Sys.Preview.Data.IData.isImplementedBy(this._data)) return this._data.getItem(index); if (this._data instanceof Array) return this._data[index]; } return null; } moveNext The moveNext method of the DataControl base class enables you to move to the next data record in the bound data collection As Listing D-17 shows, if the data control is not bound to any data collection, the moveNext method does not anything This method begins by invoking the prepareChange method, as usual: var oldState = this.prepareChange(); Next, it calls the get_dataIndex getter to return the current data index, and increments this value by one to arrive at the new value for the current data index: var newIndex = this.get_dataIndex() + 1; 1370 bapp04.indd 1370 8/20/07 8:59:58 PM Appendix D: Data Control If the new value is not greater than or equal to the total number of data records in the bound collection, it calls the set_dataIndex setter to set the current data index to the new value: if (newIndex < this.get_length()) this.set_dataIndex(newIndex); Finally, it invokes the triggerChangeEvents method as usual to trigger the necessary events: this.triggerChangeEvents(oldState); Listing D-17: The moveNext Method function Sys$Preview$UI$Data$DataControl$moveNext() { if (this._data) { var oldState = this.prepareChange(); var newIndex = this.get_dataIndex() + 1; if (newIndex < this.get_length()) this.set_dataIndex(newIndex); this.triggerChangeEvents(oldState); } } movePrevious As the name suggests, the movePrevious method of the DataControl base class enables you to move to the previous data record of the bound data collection As Listing D-18 shows, this method begins by calling the prepareChange method as usual: var oldState = this.prepareChange(); Next, it calls the get_dataIndex getter to return the current data index and decrements this value by one to arrive at the new value: var newIndex = this.get_dataIndex() - 1; If the new value is a positive number, it invokes the set_dataIndex setter to set the current data index to the new value: if (newIndex >=0) this.set_dataIndex(newIndex); Finally, it invokes the triggerChangeEvents method as usual: this.triggerChangeEvents(oldState); 1371 bapp04.indd 1371 8/20/07 8:59:58 PM Appendix D: Data Control Listing D-18: The movePrevious Method function Sys$Preview$UI$Data$DataControl$movePrevious() { if (this._data) { var oldState = this.prepareChange(); var newIndex = this.get_dataIndex() - 1; if (newIndex >=0) this.set_dataIndex(newIndex); this.triggerChangeEvents(oldState); } } onBubbleEvent The DataControl base class overrides the onBubbleEvent method that it inherits from the Control base class, as shown in Listing D-19 Recall that the onBubbleEvent method is where a client control captures the command events raised by its child controls The DataControl base class’ implementation of this method only handles the select event; that is why the method begins by calling the get_commandName method on its second parameter to determine whether the current event is a select event If so, it takes these steps to handle the event First, it calls the get_argument method on its second parameter to return the index of the selected data record: var arg = args.get_argument(); If no data index has been specified, the onBubbleEvent takes these steps to access the current data index, and uses this index as the selected index First, it invokes the get_dataContext to return a reference to the current data record: var dataContext = source.get_dataContext(); Next, it invokes the get_index method on the current data record to return its index, and uses this index as the selected index: arg = dataContext.get_index(); Next, it calls the set_dataIndex method to specify the selected index as the current data index: this.set_dataIndex(arg); 1372 bapp04.indd 1372 8/20/07 8:59:58 PM Appendix D: Data Control Listing D-19: The onBubbleEvent Method function Sys$Preview$UI$Data$DataControl$onBubbleEvent(source, args) { if (args.get_commandName() === “select”) { var arg = args.get_argument(); if (!arg && arg !== 0) { var dataContext = source.get_dataContext(); if (dataContext) arg = dataContext.get_index(); } if (arg && String.isInstanceOfType(arg)) arg = Number.parseInvariant(arg); if (arg || arg === 0) { this.set_dataIndex(arg); return true; } } return false; } descriptor The DataControl base class, like any other ASP.NET AJAX client class, exposes a static property named descriptor that describes its methods and properties to enable its clients to use the ASP.NET AJAX client-side type inspection facilities to inspect its methods and properties generically, without knowing the actual type of the class, as shown in Listing D-20 Listing D-20: The descriptor Property Sys.Preview.UI.Data.DataControl.descriptor = { properties: [ { name: ‘canMoveNext’, type: Boolean, readOnly: true }, { name: ‘canMovePrevious’, type: Boolean, readOnly: true }, { name: ‘data’, type: Sys.Preview.Data.DataTable }, { name: ‘dataIndex’, type: Number }, { name: ‘dataItem’, type: Object, readOnly: true }, { name: ‘length’, type: Number, readOnly: true } ], methods: [ { name: ‘addItem’ }, { name: ‘deleteCurrentItem’ }, { name: ‘moveNext’ }, { name: ‘movePrevious’ } ] } 1373 bapp04.indd 1373 8/20/07 8:59:59 PM Appendix D: Data Control Developing a Custom Data Control Listing D-21 presents the content of a JavaScript file named CustomTable.js that contains the implementation of a new version of the CustomTable control that derives from the DataControl base class As you can see, the render method is where all the action is This is the method that renders the user interface of the CustomTable custom data control As you can see, this method begins by invoking the get_data method to return a reference to the data collection bound to the CustomTable data control This control, like any other data control, inherits the get_data method from the DataControl base class: var dataSource = this.get_data(); Next, the render method raises an exception if the data collection bound to the data control is neither a JavaScript array nor an IData object: if (Sys.Preview.Data.IData.isImplementedBy(dataSource)) isArray = false; else if (!Array.isInstanceOfType(dataSource)) throw Error.createError(‘Unknown data source type!’); Next, the render method simply iterates through the data records in the data collection bound to the data control to render each record in a DOM element Listing D-21: The Content of the CustomTable.js JavaScript File that Contains the Implementation of the CustomTable Custom Data Control Type.registerNamespace(“CustomComponents”); CustomComponents.CustomTable = function CustomComponents$CustomTable(associatedElement) { CustomComponents.CustomTable.initializeBase(this, [associatedElement]); } function CustomComponents$CustomTable$set_dataFieldNames(value) { this._dataFieldNames = value; } function CustomComponents$CustomTable$get_dataFieldNames() { return this._dataFieldNames; } function CustomComponents$CustomTable$render() { var isArray = true; var dataSource = this.get_data(); if (Sys.Preview.Data.IData.isImplementedBy(dataSource)) isArray = false; else if (!Array.isInstanceOfType(dataSource)) throw Error.createError(‘Unknown data source type!’); 1374 bapp04.indd 1374 8/20/07 8:59:59 PM Appendix D: Data Control var sb = new Sys.StringBuilder(‘’); var propertyNames = []; var length = isArray ? dataSource.length : dataSource.get_length(); for (var i=0; i