					Borland DBWeb: Data Aware Asp.Net Web Controls
					==============================================

A.  DBWebDataSource
===================
	DBWebDataSource takes care of maintaining state and session information for all the DBWeb controls connected to it.
	1.  Row State Information: DBWebDataSource maintains the current row, last row, and row count for each table in
	the data set.  This information is associated with a session.
	2.  Row State Changes: DBWebDataSource maintains a stack of row changes made since the data was refreshed, again
	on a session-by-session basis.  This allows a user to undo changes one at a time.
	3.  Session state: since row state and change state information is stored on a session basis, each client 
	maintains a separate copy of this information.
	4.  The AutoRefresh property: if AutoRefresh is false (the default), changes from the DataProvider are not 
	taken unless the client requests that the Dataset be refreshed.  If AutoRefresh is true, changes from the 
	DataProvider are taken everytime a page is loaded.  If a user has changes which affects data changed by the 
	DataProvider, no warning is issued.
	5.  ErrorOption: 
		logOnSamePage: this is the default; any error messages will appear on the same Page as the Web Application
			Warning: This should not be used if WebControls are using Absolute Position.
		logOnErrorPage: any error messages will appear on a separate page with an OK button which will return you
			to the Web Application.
		logWithErrorEvent: indicates that user wants to handle all errrors, using the OnError event.  
	6.  Events:
		OnApplyChanges: this is the preferred way of applying changes back to the DataProvider.  
			If the DataSet is connected to a BdpDataProvider, you can simply call:
				bdpDataAdapter1.AutoUpdate();
			If you are updating multiple bdpDataAdapters, it is recommended that this code be placed within
				a transaction so that changes can be rolled back if an error occurs.
			If the DataSet is connected to a SqlDataProvider, you will have to set up an UpdateCommand to
				handle the update.
		OnScroll: this event is called whenever a row movement occurs.  The OnScrollEventArgs provide the user 
			with the TableName, the current Row, and the row that was current prior to the change.
		OnRefreshRequest: called whenever a request is made to refresh the dataSet from the DataProvider.
		OnError: called when an error has occurred during the processing of a request.  The eventArgs contain an
			ArrayList of any error messages and an ArrayList of all warning messages.  The user can then
			decide how to handle the errors.  If an OnError event is in place, it is called regardless of the
			ErrorOption setting.
	7.  DataSource property: 
		The DataSource property currently can be set to a DataSet, a DataTable or a DataView.  All of the tables
		associated with DataSet (or the DataTable or DataView's DataSet) can be used be DB Web controls connected
		to the DBWebDataSource.
	8.  ErrorDlg properties: Color and Border properties are available for controlling the appearance of the error 
		Dialog.

B.  WebDataLink Interfaces:  
===========================
 	All of the DB Web controls that connect to a DBWebDataSource implement one of the following interfaces:
	1.  (DBWebNavigator and DBWebGrid)
		   interface IDBWebDataLink
		     	IDBDataSource DBDataSource -- the DBWebDataSource component to use for DataSet access.
		     	string TableName -- the TableName within that DataSet a particular Webcontrol is 
						linked to.
	2.  (DBWeb Column Controls, such as DBWebImage, DBWebTextbox, DBWebCalendar, etc.)
		   interface IDBWebColumnLink : IDBWebDataLink
		   	string ColumnName -- the ColumnName a DBWeb Column Control is linked to.
		
	3.  (DBWeb Lookup Controls: DBWebListBox, DBWebRadioGroup, DBWebDropDownList)
		   interface IDBWebLookupColumnLink : IDBWebColumnLink
		   	string LookupTableName -- the TableName with a DataSet to be used as the source for
						lookup data
		      	string DataTextField -- the ColumName within LookupTableName Table containing the
						data to be displayed in the lookup.
		      	string DataValueField -- the Column containing the values which, when a value is selected,
						are to be placed into the ColumnName field linked to the control.
						By default, this is the same as DataTextField.

C.  Web Controls
================
	1.  DBWebNavigator:
		a.  Contains Buttons for: First, Previous, Next, Last, Insert, Delete, Apply, Refresh, Undo and UndoAll.
		b.  Rules for enabling at RunTime:
			- if table has no rows, Delete, First, Last, and Next are not enabled.
			- if no changes have been to the table, Undo and UndoAll are not Enabled.
			- if changes have been made to the table, Refresh is not Enabled.
			- if there is no DBWebDataSource.OnApplyChanges is null AND the DBWebNavigator's Click event is null,
				the Apply button is not enabled.
		c.  ButtonType property: three choices
			- ButtonText -- text is used to indication button selection:
				First, Previous, Next, Last, Insert, Delete, Apply, Refresh, Undo, Undoall
			- ButtonSymbols -- character symbols are used to indicate Button selection:
				"|<", ,"<<", ">>", >|", "+", "-", "[>]", "[<]", "X", "XX"
			- ButtonIcon -- picture files are to be used.  By default the picture files
				provided by the IDE are used, or a user can select any valid picture files.  
				The "ButtonIcon" category contains the names of the files which will be
				used for the different buttons.  If ImagesVirtualPath is not blank,
				then the images must be kept in the local directory specified by that
				VirtualPath.  If ImagesVirtualPath is blank, then the user must manually
				copy the images to the local directory for the asp project.
		d.  ImageVirtualPath -- used only when ButtonType is ButtonIcon, as noted in C.1.c above.  The
				default ImageVirtualDir is BorlandImages, which maps to a path in the 
				Delphi IDE containing the default image icons.
		e.  Click event: the Click event can be used to allow program to provide addition code for
			handling button events.  The DBWebButtonsClickArgs argument contains two important
			members: ButtonName provides the name of the button clicked.  TableOrView is an
			object which will either be the DataTable or the DataView that is connected
			to the Navigator.

			Caution!  It is recommended that the DBWebDataSource's OnApplyChanges event be used
				for applying changes to the server, rather than using the Navigator's
				Click event.  The former will handle exceptions and clearing session 
				changes.  With the latter, the user will be entirely responsible for
				taking care of this.
		f.  Buttons: 	First, Previous, Next, Last: scroll to first, previous, next and last rows 
				respectively
				Insert: insert a new row into the table
				Delete: delete the currently selected row
				Apply Changes: call the DBWebDataSource's OnApplyChangesRequest event.
				Refresh: refresh data from dataset.  This button is only relevant if
					DBWebDataSource.AutoRefresh is false (the default).
				Undo: Undo the last change.
				Undo All: Undo all changes.  If connected to a master table, UndoAll removes
					all changes to the dataset.  If connected to a detail table, UndoAll
					only removes changes to that detail table.

	2.  DBWebGrid:
		a.  Derived from Asp DataGrid, and supports all of the functionality of this base control,
			including AutoFormat and PropertyBuilder verbs.
		b.  At design time, Data is live -- connect the DBDataSource and TableName properties to a
			DBWebDataSource connected to a DataSet.
		c.  Bound Columns: using the Property builder, it is possible to select the columns and the
			order they appear in the Grid:
			i.  Open the PropertyBuilder, on the General Tab, set the DataSource to either the
				DBWebDataSource or to the DataSet it points to.
			ii.  On the Columns tab, select 'Bound Columns', and select the columns you wish
				to appear.  You can move them about using the listbox on the right.
			iii.  Warning: if Bound Columns are used, "Create columns automatically at run time"
				must be unchecked (or in other words, the AutoGenerateColumns property must
				be false).  If the same column is bound to a grid more than once, an error
				will occur at runtime.
		d.  HandleColumnEvents property: by default, when the linked columns 'Delete' and 'Edit, Update,
				Cancel' are added to a DBWebGrid, no code needs to be written.  Hitting the 
				'Delete' Column link will delete the selected row.  Hitting 'Edit' will 
				cause that row to become current.  Hitting 'Update' updates the changes to
				a row, and hitting 'Cancel' cancels the changes.

				If HandleColumnEvents is false, then the user takes responsibility for handling
				these events.
		e.  HandlePagingEvents property: by default, when 'AllowPaging' is true, the DBWebGrid will take
				care of setting the selected row based on paging changes.  If PagingStyle.Mode
				is NextPrev, then it will move the currently selected row to the next or previous
				page, and if PagingStyle.Mode is NumericPages, then it will move to the correct
				page.

				If HandlePagingEvents is false, then the user takes responsibility for handling
				these events.  If the user wants to continue with the default behavior, the 
				public method UpdatePageIndex(DataGridPageEventArgs e) can be called.
	3.  DBWebTextBox 
		a.  Derived from Asp TextBox.  Set the DBDataSource, TableName and ColumnName properties to
				achieve read-write binding to that column.
		b.  All field types are valid except for blob fields, and only non-blob fields will appear
			in the ColumnName dropdown.
	4.  DBWebImage 
		a.  Derived from Asp Image.  Set the DBDataSource, TableName and ColumnName properties to
				allow the image contained in that column to be displayed both at runtime and
				designtime.
		b.  Only binary blob fields are valid (byte[]), and only this field type will appear in the
				ColumnName dropdown.
	5.  DBWebCalendar
		a.  Derived from Asp Calendar.  Set the DBDataSource, TableName and ColumnName properties to
				achieve read-write access to that column value using the Calendar control.
				At runtime, changing the DateValues in the Calendar will automatically write
				those changes to the dataset.
		b.  Only binary DateTime fields are valid for this control, and only this field type will
				appear in the ColumnName dropdown.
	6.  DBWebCheckBox
		a.  Derived from Asp TextBox.  Set the DBDataSource, TableName and ColumnName properties to
				achieve read-write binding to that column.
		b.  Only boolean fields are string fields are valid.  String fields are expected to contain
			values of 'true/false', 'yes/no' or 'on/off'.  Only Boolean and string fields will
				appear in the ColumnName dropdown.
	7.  DBWebMemo
		a.  Derived from Asp TextBox.  Set the DBDataSource, TableName and ColumnName properties 
				provides read-write access to a text memo field.
		b.  ValidColumnType property: the default is actTextBlobOnly, in which case only only text blob 
			fields (char[]) will appear in the column dropdown.  If set to actTextBlobAndString,
			then both Text Blob fields and string fields will appear in the ColumnName dropdown.
	8.  DBWebLabel
		a.  Derived from Asp Label.  Set the DBDataSource, TableName and ColumnName properties to
				allow the read-only access to that column.
		b.  All field types are valid except for blob fields, and only non-blob fields will appear
			in the ColumnName dropdown.
	9.  DBWebLabeledTextBox
		a.  A composite control which combines the features of an ASP Label and a DBWebTextBox.  
			Set the DBDataSource, TableName, and ColumnName properties to achieve read-write
			access to that column value.
		b.  All field types are valid except for blob fields, and only non-blob fields will appear
			in the ColumnName dropdown.
		c.  Caption property: when a ColumnName is set at designtime, the Caption is automatically
			set to that ColumnName.  You can change this to any caption you wish to see displayed
			with the column value.
		d.  CaptionPosition has 4 possible values:
			- LabelToLeft
			- LabelAbove
			- LabelToRight
			- LabelBelow
		e.  TextBoxPortion: specifies the portion as a percentage of space to be taken up by the
			TextBox.  The Caption portion will be the remainder.
	10.  DBWebListBox, DBWebDropDownList and DBWebRadioButtonGroup
		a.  Derived from Asp ListBox, Asp DropDownList, and Asp RadioButtonGroup Respectively.
		b.  Display lookup data in a listform, as described in B.3 above.  
		c.  As with other IColumnLink implementers, setting the DBDataSource, TableName and
			ColumnName cause a read-write link between the selected value and the current
			column value in the table.


D.  Working with DataView
=========================
	DataViews allow you to set filters on a DataTable using the RowFilter property, or to place the data in a specific order.  At design-time, when DataAware controls are pointing to a DataView, they are automatically updated any time there is a change to the any of the DataView's properties controlling the rows which are to be displayed.

	If you wish to change the DataView's properties at runtime, care must be taken to make sure that the change is in place prior to the rendering of any of the DBWeb controls.  For example, if you use a ListBox to set the Filter -- that is, you DataBind an asp ListBox to a table containing lookup values which will server as the filter for a second table to which you have connected a DataGrid -- you would then set the ListBox's AutoPostback property to "true", and add code in the 
Page_Load event to handle setting the RowFilter, and to ClearSessionChanges() after the RowFilter has been changed.
If AutoRefresh is false (the default), care must be taken that the cached data is not used.  The WorldTravel samples provides an example of how this is done.

	The ClearSessionChanges() method must be used with care, as it tells the DBWebDataSource that the DataSet has changed from underneath it, and that the existing row/col/changed data information is no longer valid.  All pending changes are removed.  If you were to allow this method to be called when a Navigator button had been clicked, the Navigator button would not work.  

	DataViews with a filter can be made the master table in a Master-detail relationship.  To do this, set up a master-detail relationship with two or more DataTables within a single DataSet, and then connect the DataView to the master DataTable.  When the DBWebDataSource is connected to the DataView, the DBWebControls will be able to select either the parent table (the DataView) or the detail table.

	DataView Limitations:  Inserted rows in a DataView behave differently from inserted rows in a DataTable.  First, a DataView does not allow multiple inserts of null records.  This means that you must add data to an inserted row before adding a new inserted row.  Secondly, if an inserted row is deleted, it is removed from the DataView and Undo can not be used to recall it.  Thirdly, if an inserted row has a single non-null value, and that value is set to null, the row is in some cases deleted, and cannot be recalled.  

E.  Master-Detail
=================
	When a DB WebControls is connected to a DataTable which is a detail table in a relation, its rows are automatically
limited to the rows controlled by the current parent row.

F.  Working with Multiple DBWebDataSources
==========================================
	It is possible to have DBWeb controls connected to different DBWebDataSources.  However, certain changes need to be
made to the DataSet and Tables which are used.
	1.  Each DataSet.DataSetName must be unique.  By default, these are generated as "NewDataSet".  This default name
needs to be changed to a unique value.
	2.  Each DataTable's TableName property must be unique.  This problem will not be addressed in this release.  The workaround is to view each of the TableNames in all of the DataSets used by DBwebDataSources in the application, and make sure that all have a unique name.

G.  Known Problems/Issues
=========================
	1.  When DBWebDataSource.AutoRefresh if false, and the dataset it is connected to is empty, and any of its 
fields are not nullable, the DBWebGrid fails to display inserted rows.  The work around is either to have AutoRefresh set
to true.  This problem only affects the DBWebDataGrid -- other controls work correctly.
	2.  When working with a Master-Detail table it is possible to get into a state where the detail table has no current row.  The work around for this is to hit any of the scrolling buttons associated with that table.
	3.  There is no confirmation dialog for deleting a row.  However, if you wish to undo the change, simply hit the Navigator's Undo button.
	4.  There are known issues with inserting multiple blank rows where all values are left null.
	5.  DBWeb does not support cascading deletes.  Deleting a master row containing details is disallowed in this version.  The Navigator delete button will be disabled when the current row is a master row with details, and the Linked
Delete Column will do nothing.
	6.  When OnApplyChangesRequest event is correctly set up to update changes to the server, it should not be necessary to move off the record or to post the changes -- hitting the apply button should take the current values and update the server with them.  There is a bug presently that with detail tables, it is nececssary to post the changes prior to calling apply changes.

H. Alternative Web Control Template Wizard
==========================================
	The file WebCustomControl.pas in this directory is an alternative version of the Delphi IDE "New Web Control" wizard template. To easily create controls that implement DBWeb control behavior, replace the default version of BDS\2.0\ObjRepos\DelphiDotNEt\WebCustomControl.pas with this version of the file. Then, you can enable the various DBWeb interfaces by simply uncommenting a define for them in the generated source code. See WebCustomControl.pas for more information.