Specify Options

• Jan 26, 2021
• 5 minutes to read

Methods that you can use in Razor syntax mirror client-side widget options. Note the character casing difference illustrated in the table below:

Widget Option	Control Method
dataSource	DataSource
tooltip	Tooltip
showColumnHeaders	ShowColumnHeaders

Fluent API syntax allows you to chain method calls. In Visual Studio, IntelliSense provides the available method names, their accepted values, and short descriptions.

Simple Options

To specify an option, call the corresponding control method and pass the option’s value.

Razor C#

@(Html.DevExtreme().Button()
    .ID("submitButton") // sets the control container's "ID" attribute
    .Text("submit") // sets the button text
    .Width(100) // sets the button width
)

Razor VB

@(Html.DevExtreme().Button() _
    .ID("submitButton") _
    .Text("submit") _
    .Width(100)
)

You can also use an Option method that accepts an option name and value as parameters to specify control options.

Razor C#

@(Html.DevExtreme().Button()
    .Option("text", "submit")
    .Option("width", 100)

    // or

    //.Text("submit")
    //.Width(100)
)

Razor VB

@(Html.DevExtreme().Button() _
    .Option("text", "submit") _
    .Option("width", 100)
)

To specify options that accept a predefined set of values, use .NET enums. Refer to a particular option’s description to find out if it accepts an enum.

Razor C#

@(Html.DevExtreme().DateBox()
    .Type(DateBoxType.DateTime) // uses the DateBoxType .NET enum to set the type
)

Razor VB

@(Html.DevExtreme().DateBox() _
    .Type(DateBoxType.DateTime)
)

new JS() Expression

The new JS() expression allows you to embed JavaScript expressions into Razor syntax and thus have a control depend on client-side settings. For example, you can assign a JavaScript variable or expression to a control’s option. The following code defines a JavaScript variable named myText and then assigns its value to the Button’s Text option:

Razor C#

<script>
    var myText = "Submit";
</script>

@(Html.DevExtreme().Button()
    .Text(new JS("myText"))
)

Razor VB

<script>
    var myText = "Submit";
</script>

@(Html.DevExtreme().Button() _
    .Text(new JS("myText"))
)

It is essential to use new JS() when you nest a control within a template and the control configuration should depend on template parameters. See Bind a Nested Control to Template Parameters and Multi-Nested Controls for more information.

A common use-case is DataGrid’s Master-Detail Display where you should pass a master row key to the inner grid. Refer to Pass Additional Load Parameters.

ID Option

You should specify the ID option to access a control’s JavaScript API at runtime (for example, to call methods).

The ID option’s value should meet basic HTML5 requirements. Make sure that the specified value is unique, especially if the page uses controls in partial views or templates.

Controls in Partial Views

A Razor file can include multiple instances of the same partial view with DevExtreme controls. In such cases, ensure the ID attributes of rendered controls are unique. To specify unique IDs, use a model property.

The following example demonstrates how to pass a model to a partial view and use a model property to specify a button’s ID attribute:

Razor C#

@Html.Partial("_MyPartial", new { ID = 1 })

@Html.Partial("_MyPartial", new { ID = 2 })

Razor VB

@Html.Partial("_MyPartial", New With {.ID = 1})

@Html.Partial("_MyPartial", New With {.ID = 2})

Shared/_MyPartial.cshtml

@(Html.DevExtreme().Button()
    .ID("button" + Model.ID)
)

Shared/_MyPartial.vbhtml

@(Html.DevExtreme().Button() _
    .ID("button" + Model.ID)
)

If you use a hard-coded ID, several partial view instances render controls with the same ID.

Nested Controls in Templates

If you specify the ID option for a control used within an ItemTemplate or a CellTemplate template (see nested templates), use the new JS() expression to specify a unique ID for this control.

Razor C#

@(Html.DevExtreme().List()
    .DataSource(DataSource)
    .ItemTemplate(@<text>
        @(Html.DevExtreme().Button()
            .ID(new JS("'list_button_' + ID"))
        )
    </text>)
)

Razor VB

@Code
    Html.DevExtreme().List() _
        .DataSource(DataSource) _
        .ItemTemplate(Sub()
            @<text>
                @(Html.DevExtreme().Button() _
                    .ID(new JS("'list_button_' + ID"))
                )
            </text>
        End Sub) _
        .Render()
End Code

The List control is bound to the following data source:

C#

object[] DataSource = new[] {
    new { ID = 1, Name = "John" },
    new { ID = 2, Name = "Jane" }
};

VB

Dim DataSource = {
    New With {.ID = 1, .Name = "John"},
    New With {.ID = 2, .Name = "Jane"}
}

Nested Options and Collections

You can use lambda expressions to configure nested options. A lambda parameter starts a new chain of methods that specify the nested options.

Razor C#

@(Html.DevExtreme().Chart()
    .Legend(l => l // configures the chart legend (l - lambda parameter)
        .Visible(false) // hides the legend in the chart
    )
    .Tooltip(t => t // configures the tooltip (t - lambda parameter)
        .Enabled(true) // enables the tooltip
        .Font(f => f // configures the tooltip's text (f - lambda parameter)
            .Color("blue") // paints the tooltip's text in blue
        )
    )
)

Razor VB

@(Html.DevExtreme().Chart() _
    .Legend(Sub(l) l _
        .Visible(False)
    ) _
    .Tooltip(Sub(t) t _
        .Enabled(True) _
        .Font(Sub(f) f _
            .Color("blue")
        )
    )
)

You can also use lambda expressions to configure options that represent item collections. In this case, the lambda parameter performs the role of an item factory, and its Add() method adds a new item to the collection.

Razor C#

@(Html.DevExtreme().DataGrid()
    .Columns(columns => { // specifies a collection of columns
        columns.Add() // adds the "CustomerID" column
            .DataField("CustomerID");
        columns.Add() // adds the "OrderDate" column
            .DataField("OrderDate")
            .DataType(GridColumnDataType.Date);
    })
)

Razor VB

@(Html.DevExtreme().DataGrid() _
    .Columns(Sub(columns)
        columns.Add() _
            .DataField("CustomerID")
        columns.Add() _
            .DataField("OrderDate") _
            .DataType(GridColumnDataType.Date)
    End Sub)
)

Custom Options

When you need to attach extra data to a control, you can create a custom option using the Option method.

The following code example uses the TabPanelItemBuilder.Option method to create a new tabExtras option for tab items. To specify the option value, the new JS() expression is used.

Razor C#

@(Html.DevExtreme().TabPanel()
    .Items(items => {
        items.Add()
            // the following methods set the standard options
            .Title("Orders")
            .Text("Order History")
            // the following method sets the extra option
            .Option("tabExtras", new {
                masterKey = new JS("key")
            })
    })
)

Razor VB

@(Html.DevExtreme().TabPanel() _
    .Items(Sub(items)
        items.Add() _
            .Title("Orders") _
            .Text("Order History") _
            .Option("tabExtras", New With {
                .masterKey = New JS("key")
            })
    End Sub)
)

The extra option can be used to provide data (for example, masterKey) to nested controls. See the example code in the Multi-Nested Controls article.

You can also find this code in Demo: Advanced Master-Detail View.