AxGridView
Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012
An AxGridView component displays data from an AxDataSource in a grid view for a User Control. The AxGridView component can be used to edit existing records in a table. It can also be used to create new records.
Use the Bound Field Designer to select the bound fields displayed in the grid. To access this designer, click Edit Columns in the context menu for the AxGridView component. The designer is also accessible through the Columns collection property for the AxGridView component.
The user can click the columns in the grid to sort the data. Be aware that columns that display data that was retrieved with a display method are not sortable.
Properties
The AxGridView component has the following properties:
Accessibility
Property |
Description |
|---|---|
AccessKey |
The keyboard shortcut used by the control. Not used for Enterprise Portal. |
Caption |
The descriptive caption associated with the control. |
CaptionAlign |
The alignment of the associated caption. |
RowHeaderColumn |
The data source field corresponding to the column that is the row header. |
TabIndex |
The tab order of the control. |
UseAccessibleHeader |
Indicates that the control should use accessible header cells in its containing table control. |
Appearance
Property |
Description |
|---|---|
BackColor |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
BackImageUrl |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
BorderColor |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
BorderStyle |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
BorderWidth |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
CssClass |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
EmptyDataText |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
Font |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
ForeColor |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
GridLines |
This property is inherited from the base control. It is not specific to Enterprise Portal. |
ShowFooter |
When set to true, the footer containing the paging controls for the grid is displayed. |
ShowHeader |
When set to true, the header containing the column names is displayed. |
Behavior
Property |
Description |
|---|---|
AllowDelete |
When set to true, an X will be displayed on the selected line, allowing the record to be deleted. |
AllowEdit |
When set to true, the data in the selected line can be edited. |
AllowGroupCollapse |
When related rows in the grid are grouped, allows the groups to be collapsed. |
AllowGrouping |
When set to true, related rows in the grid are grouped based on the field specified in the GroupField property. |
AllowInsert |
When set to true, allows a new row to be inserted into the grid. |
AllowMarking |
When set to true, a checkbox is displayed next to each row. The user can mark the checkbox to indicate the row is marked. |
AllowSelection |
When set to true, allows a row to be selected in the grid. |
AllowSorting |
When set to true, allows the items in the grid be sorted by clicking on the column headers. |
AutoGenerateColumns |
When set to true, columns will be automatically added to the grid for each column in the data set linked to the grid. |
AutoGenerateDeleteButton |
When set to true, a Delete link will appear at the beginning of each row in the grid. |
AutoGenerateEditButton |
When set to true, an Edit link will appear at the beginning of each row in the grid. |
AutoGenerateSelectButton |
When set to true, a Select link will appear at the beginning of each row in the grid. |
ContextMenuName |
The name of the Web Menu in the AOT that contains the menu items to be displayed for the context menu. |
DefaultCollapsed |
When related rows in the grid are grouped, specifies that the groups are collapsed by default. |
DisplayGroupFieldName |
When set to true, the name of the field on which the row groups are based is displayed in the header for the group. The value displayed can be controlled by the GroupFieldDisplayName property. |
Enabled |
Specifies whether the grid is enabled. |
EnableModelValidation |
Specifies whether page validation will be performed after validation is done in the model. |
EnableSortingAndPagingCallbacks |
Indicates whether the client script for sorting and paging should be rendered to browser clients that can support callbacks. |
EnableTheming |
Indicates whether the control can be themed. |
EnableViewState |
Specifies whether the control automatically saves its state for use in round-trips. |
Filter |
Not currently used. |
FixedGridHeight |
When set to true, specifies that the grid should show a fixed number of rows that is equal to the page size. |
GroupField |
The field based on which the rows in the grid will be grouped. The bound field chosen must have its SortExpression property set for grouping to occur. |
GroupFieldDisplayName |
The value to display in the group header for each group. If no value is supplied, the name of the field specified in the GroupField property will be used. |
PostBackOnMarking |
Specifies that a postback occurs each time a row is marked or unmarked. |
SetCurrentRowOnSelection |
Sets the current row in the data set when the user selects a row in the grid. |
ShowContextMenu |
When set to true, a context menu will be displayed when the user right-clicks the selected row in the grid. |
ShowFilter |
When set to true, the filter control for the grid is displayed. |
ShowOnly GridFieldsInFilter |
When set to true, the filter will list only the fields that are currently displayed as grid columns. |
SkinID |
The SkinId of the control skin that provides the skin of the control |
ToolTip |
Not used for Enterprise Portal. |
UpdateOnPostBack |
Indicates whether the component is updated when a postback occurs. |
Visible |
Indicates whether the control is visible and rendered. |
Data
Property |
Description |
|---|---|
Expressions |
The expressions that are bound to properties of the control. |
DataKeyNames |
A comma separated list of key fields in the data source. |
DataMember |
The table or view from the data set that is being used for the grid. |
DataSourceID |
Specifies the AxDataSource component that will be used by the grid to access data. |
ExpansionRowProperties
Property |
Description |
|---|---|
ExpandEditiableRow |
When set to true, the row being edited will be rendered as expanded. |
ExpansionColumnIndexesHidden |
A comma separated list of integers representing which columns to hide from the expansion row. The value 1 indicates the first column. |
ExpansionTooltip |
The tooltip displayed on the Expansion row link. |
GridColumnIndexesHidden |
A comma-separated list of integers representing which columns to hide from the main grid. The value 1 indicates the first column. |
ShowExpansion |
Specifies whether an expansion is available for each row in the grid. When set to true, the expansion row link is displayed for each row in the grid. |
Layout
Property |
Description |
|---|---|
CellPadding |
The padding within cells. |
CellSpacing |
The spacing between cells. |
Height |
The height of the control. |
HorizontalAlign |
The horizontal alignment of the control. |
Width |
The width of the control. |
Microsoft Dynamics AX
Property |
Description |
|---|---|
AllowPrompting |
When set to true, a prompt will be shown to collect missing concrete types. |
BodyHeight |
Specifies the body height of the grid. Set this property when the body should have a fixed height. |
ManagedWebContentItem |
Specifies the User Control to display that allows the user to select the record type for the new record they are creating. This occurs only when the new type is part of a table hierarchy. If this property is not specified, the default control to select the new type is displayed. |
Misc
Property |
Description |
|---|---|
ID |
The programmatic name of the control. |
Columns |
The set of columns to be shown in the control. The Bound Field Designer used to select the columns is accessed through this property. |
EditIndex |
The index of the row shown in edit mode. |
SelectedIndex |
The index of the currently selected row. |
Paging
Property |
Description |
|---|---|
AllowPaging |
Specifies whether paging functionality is enabled for the grid. |
PageIndex |
Specifies the index of the current page. |
PagerSettings |
Controls the paging UI settings associated with the control. |
PageSize |
The number of rows from the data source to display per page. |
Styles
These style properties are groups that contain multiple properties.
Property |
Description |
|---|---|
AlternatingRowStyle |
The style applied to alternating rows. |
EditRowStyle |
The style applied to rows in edit mode. |
EmptyDataRowStyle |
The style applied to the row that contains the EmptyDataTemplate. |
EmptyRowCssClass |
Specifies the cascading style sheet class name to use for formatting an empty row. |
FooterStyle |
The style applied to the footer. |
HeaderStyle |
The style applied to the header. |
MarkedRowCssClass |
Specifies the cascading style sheet class name to use for formatting a marked row. |
PagerStyle |
Controls the paging UI style for the grid. |
RowStyle |
The style applied to rows. |
SelectedRowStyle |
The style applied to the selected row. |
Events
The AxGridView component has the events listed in the following table.
Event |
Description |
|---|---|
AxRowCreated |
Occurs after a new row is created. |
AxRowCreating |
Occurs just before a new row is created. |
DataBinding |
Occurs when the server control binds to a data source. |
DataBound |
Occurs after the server control binds to a data source. |
Disposed |
Occurs when a server control is released from memory, which is the last stage of the server control lifecycle when an ASP.NET page is requested. |
Init |
Occurs when the server control is initialized, which is the first step in its lifecycle. |
Load |
Occurs when the server control is loaded into the System.Web.UI.Page object. |
MarkingChanged |
Occurs after the marking has changed for a row. |
MarkingChanging |
Occurs just before the marking has changed for a row. |
PageIndexChanged |
Occurs when one of the pager buttons is clicked, but after the grid view handles the paging operation. |
PageIndexChanging |
Occurs when one of the pager buttons is clicked, but before the grid view handles the paging operation. |
PreRender |
Occurs after the System.Web.UI.Control object is loaded by prior to rendering. |
RowCancelingEdit |
Occurs when the Cancel button of a row in edit mode is clicked, but before the row exits edit mode. |
RowCommand |
Occurs when a button is clicked in the grid view control. |
RowCreated |
Occurs when a row is created in a grid view control. |
RowDataBound |
Occurs when a data row is bound to data in grid view control. |
RowDeleted |
Occurs when the Delete button of a row is clicked, but after the grid view control deletes the row. |
RowDeleting |
Occurs when the Delete button of a row is clicked, but before the grid view control deletes the row. |
RowEditing |
Occurs when the Edit button of a row is clicked, but before the grid view control enters edit mode. |
RowInserted |
Occurs after an Insert command is executed on the data source. |
RowInserting |
Occurs just before an Insert command is executed on the data source. |
RowUpdated |
Occurs when the Update button of a row is clicked, but after the grid view control updates the row. |
RowUpdating |
Occurs when the Update button of a row is clicked, but before the grid view control updates the row. |
SelectedIndexChanged |
Occurs when the Select button of a row is clicked, but after the grid view control handles the selection operation. |
SelectedIndexChanging |
Occurs when the Select button of a row is clicked, but before the grid view control handles the selection operation. |
Sorted |
Occurs when the hyperlink to sort a column is clicked, but after the grid view control handles the sorting operation. |
Sorting |
Occurs when the hyperlink to sort a column is clicked, but before the grid view control handles the sorting operation. |
Unload |
Occurs when the server control is unloaded from memory. |
Expansion Row for a Grid
If a grid has a large number of fields to display on a single row, consider using an expansion row. An expansion row allows a grid to display fields for the row in an additional line below the row. To use an expansion row, set the ShowExpansion property for the grid to true. Set the ExpansionColumnIndexesHidden and GridColumnIndexesHidden properties to indicate which fields in the grid will appear in the main row for the grid and which fields will appear in the expansion row.
For example, the following customer list grid contains five fields to display.
.gif "Original grid fields")
Grid View with Five Fields
The positions of the fields in this grid are numbered starting with the value 1. The Customer account field is in position 1, the Name field is in position 2, and so on. In this example, the Telephone field will be moved to the expansion row. The Telephone field is in position 5 in the list. To make the expansion row act as desired, fields 1,2,3,and 4 are hidden in the expansion. Field 5 is hidden in the main list. The properties for the grid are set to the following values:
ExpansionColumnIndexesHidden: 1,2,3,4
GridColumnIndexesHidden: 5
ShowExpansion: True
When these settings are applied, each row in the grid will have an expansion button displayed. This is shown in the following illustration.
.gif "Expansion row collapsed")
Grid View with Expansion Button
When the expansion button is clicked, the expansion line containing the Telephone field will be displayed. This is shown in the following illustration.
.gif "Expansion row expanded")
Grid View with Expansion Displayed
Context Menu for a Grid
An AxGridView component can have a context menu that is displayed when the user right-clicks the selected row in the grid. Set the ShowContextMenu property to true for the AxGridView. Set the ContextMenuName property for the AxGridView component to the name of the Web Menu from the AOT that contains the menu items that you want to display in the context menu. The following illustration shows the context menu displayed for a grid control.
.gif "Context Menu for a Grid")
Grid View with Context Menu
Row Grouping
The rows in an AxGridView component can be grouped based on one of the fields in each row. For example, the customer records displayed in a grid could be grouped based on the customer group number. This is shown in the following illustration.
.gif "Groups in AxGridView")
Grid View with Groups
To group the rows in an AxGridView, set the AllowGrouping property to true. Set the GroupField property to the bound field that you want to use to group the rows in the grid. The bound field chosen must have its SortExpression property set for grouping to occur. Use the other properties such as AllowGroupCollapse and DisplayGroupFieldName to control the group behavior.
Multi-selection
When you set the AllowMarking property to true, the user can mark multiple rows in the grid. You may want to know which rows the user has marked. The following example shows how to use the GetMarkedRowsSet method for the data source view to retrieve the set of marked rows. In this example, the name of each marked row is added to a list box.
This example uses the .NET Business Connector to access data. It requires access to the following namespaces:
using Microsoft.Dynamics.AX.Framework.Portal.Data;
using Microsoft.Dynamics.Framework.BusinessConnector.Session;
using Microsoft.Dynamics.Framework.BusinessConnector.Adapter;
The following code for a button retrieves the list of marked rows.
protected void Button1_Click(object sender, EventArgs e)
{
// Create a container.
IAxaptaContainerAdapter recordIds = this.AxSession.AxaptaAdapter.CreateAxaptaContainer();
// Get the marked rows.
IReadOnlySet<DataSetViewRow> rows = this.AxDataSource1.GetDataSourceView("FCMRooms").DataSetView.GetMarkedRowsSet();
// Create an enumerator to examine each marked row.
IEnumerator enumRows = rows.GetEnumerator();
DataSetViewRow row;
string description;
// Clear the list box.
ListBox1.Items.Clear();
while (enumRows.MoveNext())
{
// Get the current row.
row = (DataSetViewRow)enumRows.Current;
// Retrieve the name of the room.
description = row.GetFieldValue("RoomName").ToString();
// Add the item to the list box.
ListBox1.Items.Add(description);
}
}