NetCoreControls¶
A set of UI controls for ASP.NET Core.
Features¶
- Independent from data source
You can use any data source you prefer. Just set up a method that returns the data you want to display.
- Dynamic models allowed
There is no need to create a model to render data to a control. Just return dynamic from your data method.
- AJAX Enabled
All controls use AJAX to communicate with the server and perform their actions.
- Controls are connected
You can easily associate a submit button or a filter with more than one control, even with different controls.
- Subscribe control events or create custom ones
All controls share the same base events. They also offer some other events related to the control itself. But hey!, if that isn’t enough, you can create your one custom events!
Setup and Overview¶
You can use these controls with any web ASP.NET Core project. All controls were built natively for .NET Core and use Tag Helpers to perform all their logic.
Note
NetCoreControls only targets ASP.NET Core 1.1. If you have an ASP.NET Core 1.0 project then you can follow this guide for updating to ASP.NET Core 1.1.
Dependencies¶
You must use the jQuery javascript library starting from v2.x.
The controls also use some styles from Bootstrap, but it’s not a mandatory requirement since you can link your own styles classes.
Basic setup¶
1. Install the NetCoreControls NuGet package
Add to project.json the following dependency:
"NetCoreControls" : "1.0.0-beta1"
Or you can use the Package Manager Console:
Install-Package NetCoreControls -Pre
2. Register NetCoreControls
In your Startup.cs class, inside the ConfigureServices method, add the following line after Mvc registration:
services.AddMvc();
(...)
services.AddNetCoreControls(Configuration);
3. Reference the assembly to enable usage as TagHelpers
In your _ViewImports.cshtml file inside your Views folder, add the following line:
@addTagHelper "*, NetCoreControls"
4. Add references to CSS and Script files
Inside your <head></head> tag, insert the following:
<link href="@Url.Action("GetNccCssFile", "NetCoreControls")" rel="stylesheet">
On the bottom of your page, just above the </body> tag, insert the following:
<script type="text/javascript" src="@Url.Action("GetNccJsFile", "NetCoreControls")"></script>
Note
Although the tag that links to the stylesheet is optional, the script is mandatory and should be placed after the jQuery link.
Daily builds
To use the latest daily builds of the controls, please add the following MyGet repo to download latest binaries:
https://www.myget.org/F/netcorecontrols/api/v3/index.json
Add to project.json the following dependency:
"NetCoreControls" : "1.0.0-beta-*"
Basic Usage¶
Just use any of the available controls using the corresponding taghelper tag.
All tags are prefixed with ncc:.
All taghelpers that are attributes are prefixed with ncc-.
Basic control usage¶
To use any control, two steps are required:
- Create a control context
- Use the tag of the control
The example of a basic Grid is as follows.
1. Create a method that gets the data from a datasource such as a database (the example uses Dapper for data access):
public List<dynamic> GetProductList()
{
var sqlCommand = $@" SELECT * FROM Products";
return Task.Factory.StartNew(() =>
{
using (var connection = new SqlConnection(_connStrings.Value.LocalDb))
return connection.Query<dynamic>(sqlCommand);
}).Result.ToList();
}
}
2. On your Controller define a NccContext (e.g. ``NccGridContext``) object and set required parameters. Pass it to the View using ``Model``, ``ViewBag``, ``ViewData`` or any other method
using ByteNuts.NetCoreControls.Models.Grid;
...
var context = new NccGridContext
{
Id = "SimpleGrid",
DataAccessClass = typeof(IDataAccess).AssemblyQualifiedName,
SelectMethod = "GetProductList",
UseDependencyInjection = true,
ViewPaths = new ViewsPathsModel { ViewPath = "/Views/NccGrid/SimpleGrid.cshtml"}
};
ViewData[context.Id] = context;
3. On your View simply use the tag helper ``ncc:grid``, along with the available nested tags. Set the grid context, and use the @Model inside the control tags to access all the properties available in each list item
@using ByteNuts.NetCoreControls.Models.Grid
@{
var context = ViewData["SimpleGrid"] as NccGridContext;
}
<ncc:grid Context="@context">
<ncc:grid-columns>
<ncc:grid-columnbound DataValue="@Model.ProductID" HeaderText="Product Id"></ncc:grid-columnbound>
<ncc:grid-columnbound DataValue="@Model.ProductName" HeaderText="Product Name"></ncc:grid-columnbound>
<ncc:grid-columnbound DataValue="@Model.SupplierID" HeaderText="Supplier ID"></ncc:grid-columnbound>
<ncc:grid-columnbound DataValue="@Model.CategoryID" HeaderText="Category ID"></ncc:grid-columnbound>
<ncc:grid-columnbound DataValue="@Model.QuantityPerUnit" HeaderText="Quantity Per Unit"></ncc:grid-columnbound>
<ncc:grid-columnbound DataValue="@($"{Model.UnitPrice:0.00} €")" HeaderText="Unit Price"></ncc:grid-columnbound>
<ncc:grid-columnbound DataValue="@Model.UnitsInStock" HeaderText="Units In Stock"></ncc:grid-columnbound>
<ncc:grid-columnbound DataValue="@Model.UnitsOnOrder" HeaderText="Units On Order"></ncc:grid-columnbound>
<ncc:grid-columnbound DataValue="@Model.ReorderLevel" HeaderText="Reorder Level"></ncc:grid-columnbound>
<ncc:grid-columnbound DataValue="@(Model.Discontinued ? "Discontinued" : "Active")" HeaderText="Discontinued"></ncc:grid-columnbound>
</ncc:grid-columns>
</ncc:grid>
Warning
The grid shall be placed alone in a partial view. When an action occurs on the control, the partial view is full rendered.
Filters¶
Filters are an attribute taghelper and are global to all controls.
One single filter can be applied to multiple controls.
Filters can be applied to input, select and button html tags, just using the ncc-filter-targets as follow:
<select ncc-filter-targets="MultiGridWithFilter1,MultiGridWithFilter2" name="orderId" asp-items="@(new SelectList(ViewData["Orders"] as IEnumerable, "OrderID", "OrderID"))" >
<option value="">--- Choose an order ---</option>
</select>
Events¶
To be able to use events, the class containing these events must inherit from the control events class.
Beside inheriting, it must be referenced in the control context that is created, using the property EventHandlerClass:
e.g. EventHandlerClass = typeof(ExampleGridEvents).AssemblyQualifiedName
The event handler class must inherit from one of the following two:
- ByteNuts.NetCoreControls.Controls.NccEvents –> this class defines the shared events;
- ByteNuts.NetCoreControls.Controls.[ControlName].Events.[ControlName]Events –> this class defines control specific events.
Hint
If you inherit from the base events class NccEvents, you may only subscribe to control shared events and not to control specific events.
Advanced Setup¶
There are some more additional settings that can be used to setup controls.
Settings¶
This settings are global to the controls, and are placed on the appsettings.json file, within a section named NccSettings:
{
(...)
"Logging": {
(...)
},
"NccSettings": {
"UseDependencyInjection": "true",
"DataProtectionKey": "11111111-2222-3333-4444-555555555555"
}
}
- UseDependencyInjection (default: true) - indicates wether the data access class should be requested directly from the iOC or if it should be instantiated.
- DataProtectionKey - defines the key to be used when encrypting the context of each control. The example uses a Guid, but it can be any type of string.
Exception Handling¶
Exceptions within tag helpers are contained and isolated from the page, preventing that an error in a control blocks the rendering of a page.
Neverthless, if the error occurs on the Razor code, such as trying to read an inexisting property, these errors cannot be handled by the NccControls and prevent the page from rendering.
To prevent this from happening, you can use the RenderControl TagHelper to render the controls. So, instead of using:
@await Html.PartialAsync("/Views/NccGrid/Partials/_GridExample.cshtml")
just use:
<ncc:render-control Context="@(ViewData["GridExample"] as NccGridContext)"></ncc:render-control>
NCC Grid¶
A grid control that renders data as a table.
Context¶
The context class for the Grid control is NccGridContext.
- DataKeys - a comma separated data keys for the data. These keys are not rendered on the client, and cannot be overriden by hidden fields.
- DataKeysValues (read-only) - a read-only
List<Dictionary<string, object>>that contains all the data keys for the grid. - PageNumber (default: 1) - page number to start from.
- TotalItems (read-only) - a read-only items counter.
- AllowPaging (default: false) - a flag indicating if the grid is paginated.
- PageSize (default: 10) - if
AllowPagingis set to true, defines the size of a grid page. - PagerNavSize (default: 10) - if
AllowPagingis set to true, defines how many pages are shown in the navigation pager. - AutoGenerateEditButton (default:false) - a flag indicating if the table is editable row by row.
Tags¶
The Grid control is composed by various tags that can be coupled together.
Each one of them contain custom attributes that can be set and some may override the settings placed on context.
<ncc-grid>¶
Attributes
- Context
- DataKeys
- AllowPaging
- RenderForm
- PageSize
- AutoGenerateEditButton
- PagerNavSize
- CssClass
- BodyCssClass
- HeaderCssClass
- FooterCssClass
Allowed child tags - ncc:grid-content - ncc:grid-columns
<ncc:grid-columns>¶
Allowed parent tags
- ncc:grid
Allowed child tags
- ncc:grid-columnbound
- ncc:grid-columntemplate
<ncc:grid-columnbound>¶
Attributes
- DataValue
- DataField
- HeaderText
- ShowHeader
- Visible
- Aggregate
- CssClass
Allowed parent tags
- ncc:grid
<ncc:grid-columntemplate>¶
Attributes
- ShowHeader
- Visible
Allowed parent tags
- ncc:grid-columns
Allowed child tags
- ncc:grid-headertemplate
- ncc:grid-itemtemplate
- ncc:grid-edittemplate
Events¶
For subscribing to these events, the EventHandlerClass property of the context must be set with the reference for a class that derives from NccGridEvents.
The following are Grid specific events:
- RowDataBound
- RowCreated
- Update
- UpdateRow
- DeleteRow
Actions¶
Actions allows the user to raise any of the referred grid events, and can be associated with any HTML element.
To use an action, the following two first attributes must be set:
- ncc-grid-action - the name of the action to raise.
- ncc-grid-action-target - the id(s) of the controls that will raise the event (it can raise Update simultaneously on multiple grids).
- ncc-grid-row (optional) - if the action requires the row number which will raise the event, this attribute must be set.
Note
Within the Grid, you can use @Model.NccRowNumber property to insert the row number.
NCC Select¶
A select HTML tag that allows linking other controls and creates dependencies among the data loaded by each control.
Context¶
The context class for the Grid control is NccSelectContext.
- TextValue - a string name of a property that will be rendered as the text of the option.
- DataValue - a string name of a property that will be rendered as the value of the option.
- SelectedValue - the default value to be automatic selected.
- FirstItem - the value that the first element must contain. The value for this item is always an empty string.
Tags¶
The Select control is composed by a single tag.
Each custom attributes set on the tag will override the settings placed on context.
Events¶
For subscribing to these events, the EventHandlerClass property of the context must be set with the reference for a class that derives from NccSelectEvents.
The following are Select specific events:
- OptionBound - fires on each option before added to select
Link control¶
To link this select with other controls on page, whether they are ncc:select controls, or any other NetCoreControls, their id’s must be included in a specific attribute tag:
- ncc-link-targets - a comma separated and ordenated list of the controls that load their data according to the previous control selected.
Note
At the moment, ncc-link-targets can only be placed on NccSelect controls. Nevertheless, they can contain NccGrid id’s for example, but any action taken on the grid will not have any efect on the NccSelect controls. Please, see samples for a working example.