syncfusion-aspnetcore-dropdowns

# Implementing Syncfusion ASP.NET Core Dropdowns ## DropDownList The DropDownList (`<ejs-dropdownlist>`) is a single-selection control that displays a list of predefined values. It supports local and remote data binding, real-time filtering, grouping, custom templates, virtual scrolling, popup resize, localization, and full WCAG 2.2 AA accessibility. ### Component Overview **Tag Helper:** `<ejs-dropdownlist>` **Namespace:** `Syncfusion.EJ2.DropDowns` **NuGet:** `Syncfusion.EJ2.AspNet.Core` **Key Features:** - Data binding from local arrays and remote sources (OData V4, Web API, URL Adaptor) - Value binding for primitive types and complex objects (`allowObjectBinding`) - Real-time filtering with search box (`allowFiltering`, `filterType`, `debounceDelay`) - Grouping items using `fields.groupBy` - Disabled items using `fields.disabled` - Customizable templates: `itemTemplate`, `valueTemplate`, `headerTemplate`, `footerTemplate`, `groupTemplate`, `noRecordsTemplate`, `actionFailureTemplate` - Virtual scrolling for large datasets (`enableVirtualization`) - Popup resize by user (`allowResize`) - WCAG 2.2 AA compliance, keyboard navigation, ARIA support - RTL rendering (`enableRtl`) - Localization (`locale`) - Float label support (`floatLabelType`) - State persistence (`enablePersistence`) - Clear button (`showClearButton`) ### API Reference 📄 **Full API:** [references/api.md](references/dropdownlist-api.md) - All properties with types, defaults, and descriptions - All events - Field settings (`<e-dropdownlist-fields>`) - Tag helper syntax examples for all features ### Documentation and Navigation Guide #### Getting Started 📄 **Read:** [references/getting-started.md](references/dropdownlist-getting-started.md) - NuGet package installation - TagHelper registration (`_ViewImports.cshtml`) - **⚠️ CDN vs. Local Hosting:** See Security & Trust Boundary below for SRI and local hosting alternatives - Script Manager registration - Basic DropDownList tag helper usage - Popup height/width configuration - Change event handling #### Data Binding and Value Binding 📄 **Read:** [references/data-binding.md](references/dropdownlist-data-binding.md) - Binding array of primitive data (strings, numbers) - Binding complex JSON objects with `<e-dropdownlist-fields>` - Nested/complex data with dot-notation field paths - Value binding for primitive types (pre-selecting) - Object binding with `allowObjectBinding` - Remote data: OData V4, OData, Web API, URL Adaptor - Offline mode (`DataManager offline="true"`) - `actionBegin`, `actionComplete`, `actionFailure` events #### Filtering and Grouping 📄 **Read:** [references/filtering-grouping.md](references/dropdownlist-filtering-grouping.md) - Enable filtering with `allowFiltering` - Filter types: `StartsWith`, `Contains`, `EndsWith` - Minimum character limit before remote request - Case-sensitive filtering with `ignoreCase` - Diacritics filtering with `ignoreAccent` - Debounce delay with `debounceDelay` - Filter bar placeholder with `filterBarPlaceholder` - Grouping with `fields.groupBy` - Custom group header with `groupTemplate` - Disabled items with `fields.disabled` - Sort order: `None`, `Ascending`, `Descending` #### Templates and Styling 📄 **Read:** [references/templates-styling.md](references/dropdownlist-templates-styling.md) - `itemTemplate` — customize popup list items - `valueTemplate` — customize selected value in input - `headerTemplate` — static header in popup - `footerTemplate` — static footer in popup - `groupTemplate` — custom group headers - `noRecordsTemplate` — no data state - `actionFailureTemplate` — remote fetch failure state - `floatLabelType` — float label behavior - `cssClass` — custom CSS class - CSS structures for appearance customization #### Accessibility and Localization 📄 **Read:** [references/accessibility-features.md](references/dropdownlist-accessibility-features.md) - WCAG 2.2 Level AA compliance - WAI-ARIA attributes (`aria-haspopup`, `aria-expanded`, `aria-selected`, etc.) - Full keyboard navigation shortcut reference - RTL support with `enableRtl` - Localization with `locale` and `L10n.load()` - Readonly vs disabled states - `enablePersistence` for state persistence - `isDeviceFullScreen` for mobile popup behavior #### Advanced Scenarios 📄 **Read:** [references/advanced-scenarios.md](references/dropdownlist-advanced-scenarios.md) - Virtual scrolling with `enableVirtualization` (local and remote) - Virtualization with grouping and filtering - Customizing item count in virtualization - Popup resize with `allowResize`, `resizeStart`, `resizeStop`, `resizing` events - Cascading dropdowns (parent-child dependent selection) - Remote data with filtering - Pre-selecting values (by `value`, `text`, or `index`) - `showClearButton` usage - `htmlAttributes` for extra HTML attributes - All events reference with usage examples ### Quick Start Example **Controller (`HomeController.cs`):** ```csharp public IActionResult Index() { ViewBag.data = new List<object> { new { Id = 1, Name = "Electronics" }, new { Id = 2, Name = "Furniture" }, new { Id = 3, Name = "Clothing" } }; return View(); } ``` **View (`Index.cshtml`):** ```cshtml <ejs-dropdownlist id="category" dataSource="@ViewBag.data" placeholder="Select category" change="onCategoryChange"> <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields> </ejs-dropdownlist> <script> function onCategoryChange(args) { console.log('Selected ID:', args.value); } </script> ``` ### Common Patterns #### Pattern 1: Basic Selection with Event Handling ```cshtml <ejs-dropdownlist id="category" dataSource="@ViewBag.Categories" placeholder="Select category" change="onCategoryChange"> <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields> </ejs-dropdownlist> <script> function onCategoryChange(args) { console.log('Selected ID:', args.value); } </script> ``` #### Pattern 2: Cascading Dropdowns (Secure Server-Side Proxy) **⚠️ Security Note:** Avoid client-side direct fetch to untrusted external endpoints. Use a server-side proxy that validates, authenticates, and sanitizes responses. **Controller (Server-Side Proxy):** ```csharp public IActionResult Index() { ViewBag.Countries = new List<Country> { new Country { Id = 1, Name = "USA" }, new Country { Id = 2, Name = "Canada" } }; return View(); } // ✅ SECURE: Server-side proxy validates countryId and returns only whitelisted data [HttpGet("api/cities/{countryId}")] public IActionResult GetCities(int countryId) { // Validate countryId is within acceptable range if (countryId <= 0 || countryId > 100) return BadRequest("Invalid country ID"); var cities = new List<City> { new City { Id = 1, Name = "New York", CountryId = 1 }, new City { Id = 2, Name = "Toronto", CountryId = 2 } }; // Return only safe, schema-validated data return Json(cities.Where(c => c.CountryId == countryId) .Select(c => new { c.Id, c.Name }) .ToList()); } ``` **View (Secure Client):** ```cshtml <ejs-dropdownlist id="Country" dataSource="@ViewBag.Countries" change="onCountryChange" placeholder="Select country"> <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields> </ejs-dropdownlist> <ejs-dropdownlist id="City" placeholder="Select city"> <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields> </ejs-dropdownlist> <script> function onCountryChange(args) { var cityDDL = document.getElementById('City').ej2_instances[0]; if (args.value) { // ✅ SECURE: Fetch only from same-origin API endpoint (same server) fetch("/api/cities/" + encodeURIComponent(args.value), { method: 'GET', headers: { 'Content-Type': 'application/json' }, credentials: 'same-origin' // Include CSRF tokens via cookies }) .then(response => { if (!response.ok) throw new Error('Server error: ' + response.status); return response.json(); }) .then(data => { // Validate response is an array before binding if (Array.isArray(data)) { cityDDL.dataSource = data; cityDDL.value = null; } else { console.error('Invalid data format received'); cityDDL.dataSource = []; } }) .catch(error => { console.error('Failed to load cities:', error); cityDDL.dataSource = []; }); } else { cityDDL.dataSource = []; } } </script> ``` #### Pattern 3: Remote Data with Filtering (Secure Same-Origin Proxy) **⚠️ Security Note:** Avoid `crossDomain="true"` and direct binding to external OData/WebAPI endpoints. Always proxy through your own server to control validation and access. ```cshtml <!-- ✅ SECURE: Remove crossDomain, use same-origin server proxy --> <ejs-dropdownlist id="customers" allowFiltering="true" filtering="onfiltering" query="new ej.data.Query().from('api/customers').select(['ContactName', 'CustomerID']).take(6)" placeholder="Select a customer" popupHeight="200px"> <e-dropdownlist-fields text="ContactName" value="CustomerID"></e-dropdownlist-fields> <e-data-manager url="/api/customers" adaptor="UrlAdaptor"> <!-- UrlAdaptor for same-origin JSON endpoint --> </e-data-manager> </ejs-dropdownlist> <script> function onfiltering(e) { var ddl = document.getElementById("customers").ej2_instances[0]; var query = new ej.data.Query().from('api/customers').select(['ContactName', 'CustomerID']).take(6); query = e.text !== '' ? query.where('ContactName', 'startswith', e.text, true) : query; e.updateData(ddl.dataSource, query); } </script> ``` **Controller (Server-Side Proxy):** ```csharp // ✅ SECURE: Server validates, filters, and returns safe subset of data [HttpGet("api/customers")] public IActionResult GetCustomers([FromQuery] string skip = "0", [FromQuery] string take = "6", [FromQuery] string where = "") { int skipVal = Math.Max(0, int.TryParse(skip, out var s) ? s : 0); int takeVal = Math.Min(50, int.TryParse(take, out var t) && t > 0 ? t : 6); // Example: fetch from secure internal data source var customers = _context.Customers .AsNoTracking() .Select(c => new { c.CustomerID, c.ContactName }) .Skip(skipVal) .Take(takeVal) .ToList(); return Ok(new { d = customers, count = customers.Count }); } ``` ### Key Properties and When to Use | Property | Attribute | When to Use | |----------|-----------|-------------| | `DataSource` | `dataSource` | Always required to populate items | | `Fields` | `<e-dropdownlist-fields>` | When binding complex JSON objects | | `Value` | `value` | Pre-selecting an item | | `Index` | `index` | Pre-selecting by position | | `AllowFiltering` | `allowFiltering` | For lists with many items | | `FilterType` | `filterType` | Customize search match behavior | | `DebounceDelay` | `debounceDelay` | Reduce filter frequency while typing | | `EnableVirtualization` | `enableVirtualization` | For very large datasets | | `AllowResize` | `allowResize` | Allow user to resize popup | | `ItemTemplate` | `itemTemplate` | Rich item rendering | | `ValueTemplate` | `valueTemplate` | Custom selected value display | | `GroupTemplate` | `groupTemplate` | Custom group headers | | `ShowClearButton` | `showClearButton` | Allow clearing selection | | `Enabled` | `enabled` | Conditional enable/disable | | `Readonly` | `readonly` | Display-only mode | | `EnableRtl` | `enableRtl` | RTL language support | | `Locale` | `locale` | Localized text | --- ### Next Steps - **Just starting?** → [Getting Started](references/dropdownlist-getting-started.md) - **Binding server data?** → [Data Binding](references/dropdownlist-data-binding.md) - **Need filtering or grouping?** → [Filtering and Grouping](references/dropdownlist-filtering-grouping.md) - **Customizing appearance?** → [Templates and Styling](references/dropdownlist-templates-styling.md) - **Accessibility or localization?** → [Accessibility and Localization](references/dropdownlist-accessibility-features.md)