DVXP TEdit.NET 3.0

TEdit.NET Configuration File Reference

The XML configuration file specifies the tables and columns shown in a TEdit.NET control. A configuration file is assigned by the ConfigFilePath property of the control. 
<tableeditor xmlns="http://dvxp.com/schemas/DXTableEditor/Config">
    <settings 
              connectionStringKey="WebConfigKeyName"
              quotePrefix="[" 
              quoteSuffix="]" >
    </settings>
    <table name="tablename | SELECT-statement"
              alias="Display name"
              orderBy="SQL sort expression" 
              where="SQL filter expression"
              allowAdd="true|false"
              allowEdit="true|false" 
              allowDelete= "true|false"
              retrieveAutoIncrementId= "true|false">
        <column name="column name" 
                     alias="Display name" 
                     lookupquery="SELECT Key, Desc FROM LookupTable" 
                     format= "{0:format-specifier}" 
                     default="default value for new rows" 
                     allowNull="true|false"
                     rows="number of lines in edit text box"
                     columns="number of columns in edit text box"
                     visibleInGrid="true|false"
                     visibleInEditPanel="true|false"
                     htmlEncode="true|false"
                     order="0|1|..."
                     textTrue="Boolean True display text"
                     cellWidth="grid column width"
                     cssClass="CssClassName"
                     cssStyle="style:value;..."
                     isPassword="true|false" >
       </column> 
       <selectButton 
                   commandType="select|edit|checkbox"
                   text="button caption | <img src='...'>" 
                   headerText= "header caption | <img 
                   src='...'>"
                   commandName="name"
                   location="left|right" >
     </selectButton> 
   </table>
   <TEditLicense> ... </TEditLicense>
</tableeditor>

<tableeditor> Element

Each configuration file must start with the tableeditor element, including the xmlns="http://dvxp.com/schemas/DXTableEditor/Config" attribute. This namespace attribute defines the XML schema that is used to validate the contents of the file and to provide IntelliSense help in the Visual Studio.NET XML editor.

<settings> Element

The optional settings element can contain a reference to the database connection string.
Attribute Description
connectionStringKey Defines what database to use. This attribute contains the name of an appsetting key in web.config where the connection string to the database is stored. You can provide either a SqlCient or an OleDb connection string. It is also possible to specify a connection string at runtime. Use the ConnectionString property of the TableEditor Control for this. Note that this property should be set in the Init event of the page, as opposed to the Load event.
quotePrefix
quoteSuffix		 Some table and column names may contain characters such as spaces, commas, and semicolons. Therefore, TEdit.NET always encloses table and column names with the quotePrefix and qouteSuffix characters. For SQL Server and MSAccess databases, the default values of '[' and ']' can be used. Other databases and OLE DB drivers may require other quote-characters.
Note: For Oracle databases, both the prefix and the suffix is a double quote character (written as &quot; in XML). TEdit.NET automatically uses this setting for the current Microsoft and Oracle OLE DB drivers (msdaora and OraOLEDB.Oracle). In case you need to specify or override this setting explicitly, can do it like so:
<settings connectionStringKey="MyOracleConnKey" quotePrefix="&quot;" quoteSuffix="&quot;"></settings>

<table> Element

A configuration file must contain one or more table elements. When more than one table is defined, the DXTableEditor will show a drop down list from which each table can be selected.
Attribute Description
name Contains either the name of a table in the database, or a complete SQL SELECT statement.
alias A friendly display name that is used in the tables dropdown selection list that is shown when multipe tables are defined in the configuration file.
orderBy An SQL order by clause (with the order by text itself omitted) used to provide an initial sort on the table
where An SQL where clause (without the where text itself) used to filter the table
allowAdd Specifies if the user is allowed to add new rows to the table
allowEdit Specifies if the user is allowed to edit existing rows
allowDelete Specifies if the user is allowed to delete rows
retrieveAutoIncrementId Specifies if the table editor should try to retrieve the value of newly added records in order to select newly added rows in the grid. The table editor uses the SQL Server and MSAccess 2000 specific SELECT @@identity command for this by default, it can be necessary to disable this behavior when using another database server.

Note: Also see the ProvideAutoIncrementIdCommand event, that allows to replace the SELECT @@identity command by another query.

<column> Element

Each table element can optionally contain one or more column elements. The column element allows for customizing the default processing rules and display properties of individual columns in the table. When no column element is present for a table column, the table editor will display it by default.
Attribute Description
name The database name of the column, or the name specified in the table SELECT statement.
alias A friendly display name that replaces the columns database name in the grid column heading and in the caption label of the edit control of the column.
lookupquery If this column is a foreign key (a field that refers to a row in another table), a lookup query can be specified to replace the foreign key value with a friendly description of the row that is referred by it. The lookup query is typically a SQL SELECT statement, and it must return two columns. The first column in the SELECT statement should contain the primary key values of the related table. The second column should return the text that is presented to the user. In the grid, this text is displayed in the table cell and in edit mode this text is used to populate a combo box with all rows returned from the lookup query.
Note: Also see the ProvideLookupCommand event, that allows to provide the lookup query (or stored procedure) at run-time.
format A .net format specification that is used to format the column value. The format specification has the format {0:format}, and works analogous to the VB/C# statement String.Format("{0:formatspecification}", value). See the MSDN online help for format specification help.
Note: Also see the FieldFormat event, that allows to customize the formatting of a value for a field at runtime.
default A default value for newly added rows.

Note: Also relevant is the BeforeRowUpdate event. This event can be used to set a default value in any field of newly added rows.
allowNull Indicates if SQL NULL values are allowed for this column. This setting is especially relevant for columns that have a lookupquery: the allowNull attribute determines if the lookup combo box contains an (Unspecified) item in its dropdown list that allows the user to set the column value to NULL.
rows The number of rows in the edit text box for this column. If not specified it defaults to 1 (a standard text box). If set to a value higher than 2, a multi-line text box is created with a vertical scroll bar (useful for text/memo fields).
If not specified it defaults to 1 if the data type of the field in the database is not a memo field or large-text field. Otherwise, it defaults to the value specified in the MaxTextBoxRows property.
columns The width (number of characters) in the edit text box for this column. If not specified it defaults to lowest of two values: the value specified in the MaxTextBoxColumns property and maximum length of the field specified in the database.
visibleInGrid Indicates if this column should be visible in the grid/table-view. If not specified, it defaults to true.
visibleInEditPanel Indicates if this column should be visible in the edit-view. If not specified, it defaults to true.

Note: See the FieldFormat and CreateEditControl events, that both allow to provide a custom display value for a field at runtime. When formatting a field for display in an edit-control, the IsGridView property of the FieldFormat event is set to false.

Note: See the FieldParse event, that allows you to manually validate and parse a value entered the user. This can be useful for parsing numeric and date values in formats that the .net runtime does not support by default.

Note: The CreateEditControl, SetEditControlValue and GetEditControlValue events can be used to replace or customize the default edit controls created by the TableEditor (typically text boxes or drop down lists). For example, you can replace a standard textbox field with either an ASP.NET calendar control for date fields or with a third party RichTextBox (such as the one from RichTextBox.com) for memo fields.

Note: Also relevant is the BeforeRowUpdate event. This event can be used to set a default value in any field of newly added or updated rows. This is event is especially useful when the visibleInEditPanel attribute for this column is set to false; in that case the FieldFormat event is never fired and no edit control is created for the column. Note that the BeforeRowUpdate event can also be used to validate the user input.
htmlEncode Specifies if the field should be HTML encoded when rendered in the grid-view. If not specified, it defaults to true so that all text in the field is displayed as plain-text in the browser.
If the database column contains HTML-formatted text, or if you have written a handler for the FieldFormat event that generates HTML, htmlEncode should be set to false.
order Defines the display order of this column in the grid and edit views, relative to the other columns in the table. Columns with lower orders are displayed first. Columns for which no order is set come after the columns for which there is.
textTrue
textFalse		 These properties define how the boolean values true and false are displayed. If not specified, they default to the values set in the control's properties TextTrue and TextFalse.
cellWidth Defines a value for the width attribute for the td table cell element that renders the field in the grid view of the table editor. Use any valid CSS unit, such as '10px' or '50%'.

Note: Similar functionality is provided by the more powerful cssStyle attribute (e.g. cssStyle="width: 100px")
cssClass Defines a value for the class attribute for the td table cell element that renders the field in the grid view of the table editor. Use any class name you have defined in the CSS style sheet of the current page.
cssStyle Defines a value for the style attribute for the td table cell element that renders the field in the grid view of the table editor.
Example: to create a right-aligned the column in bold, use cssStyle="text-align: right; font-weight: bold".
isPassword Instructs TEdit.NET to generate a password-type textbox for this column. Note that for maximum security the password is never sent to the browser. This means that TEdit.NET will display an empty text-box for existing passwords. In order to change the password, just type in the new value. In order to keep the existing password, just leave the password box empty.

<selectButton> Element

Attribute Description
commandType The commandType attribute can contain one of the following values:

select
This type generates a grid column containing link-buttons that can be used to select the current row. These buttons are especially useful in master-detail scenario's, where the user needs to be able to select a row in the master table in order to view the corresponding details.
For each select button, the table editor will create an extra column in the grid. Whenever a 'select' button is clicked, the RowSelected and RowDeselected events are fired, as appropriate.

edit
This type corresponds to the Edit link button that is displayed in the first column of each row. Clicking the Edit button sets the current row in edit mode. You can define the grid column in which the 'edit' button is displayed by creating an edit-type selectButton element and place this in the desired order relative to the other select and checkbox selectButton elements.

checkbox
This type corresponds to the row selection checkboxes that are displayed when the  IsRowSelectColumnVisible property of the TEdit control is true.
As with the Edit button, the order of the checkbox-type selectButton element defines the grid column for the row selection checkboxes.
commandName This value is only relevant for selectButtons with commandType 'select'.
The commandName is an optional tag that is assigned to the select button. When the button is clicked, this value is passed in the RowSelectedEventArgs of the RowSelected Event. This is useful when more than one selectButton is present.
location Specify left or right, to locate the button at the left or right hand side of the grid.
text The text displayed by the button (HTML is allowed, for example to create image buttons as in the note below, provided reserved characters are XML-encoded).
Note: You can also display images in select buttons. Just enter the appropriate HTML in the text attribute, but remember to XML-encode the < symbol as &lt;. For example, to create an edit button that displays an image instead of the default Edit text, use the following selectButton declaration:

<selectButton text="&lt;img border=0 src='images/edit.gif'>"
  commandType="edit" location="left" headerText="Edit">
</selectButton>
In order to fully customize the appearance of this text on a row-by-row basis, handle the SelectButtonFormat event or the SelectCheckBoxFormat event.
headerText The text displayed in the buttons column header

<TEditLicense> Element

The last element in the configuration file contains the license code that is sent to licensed users of the TEdit.NET control. When a valid TEditLicense element is present in the configuration, the control will no longer display the text banner 'Unlicensed Evaluation Version'.
Note: A more convenient method of installing the license is by adding an appSetting that points to a configuration file containing a valid license. This appSetting can be added to the web.config file of your web site, so that is no longer required to include a TEditLicense element in the configuration file of each table editor in the site. When the appSetting is added to the machine.config file, the license is available to all table editors in all web sites on the machine.
The appSetting name is TEdit.LicenseFile and it's value attribute must contain the fully qualified path to a configuration file containing the license. For example: 
<appSettings>
  <add key="TEdit.LicenseFile" value="c:\mylicenses\TEditLicense.xml" />
</appSettings>

Using parameters

Through the use of parameters, TEdit.NET can be used to build end-user applications where data must be selected or hidden depending on the current user or other application context.

The configuration file can contain parameters that must enclosed between tilde (~) characters. At runtime, TEdit.NET replaces these placeholders with values supplied in the Parameters collection property. Parameters are entered in the form ~ParameterName~ or ~ParameterName,DefaultValue~ . Parameters can be placed anywhere throughout the configuration file.  TEdit.NET stores the parameter values in the form's view state, therefore parameter values do not have to be set on every page request, but only at the initial request (when Page.IsPostBack is false), or when the parameters are changed in the application. Also see the parameters sample online. After new parameter values have been assigned, the control's Rebind() method must be called. See the Page_Load and Button Click Events in the sample.