UI Toolkit
Rock has a collection of fantastic UI controls that will help you develop blocks much quicker than if you has to write everything from scratch.
The Rock Grid makes it a breeze to quickly display your entity lists.
Set the Grid's Actions.IsAddEnabled to true to enable the Add icon on the grid toolbar. Add your custom handler to the grid's Actions.AddClick hander as shown in the example below.
This generates a native XLSX file. If the grid's Caption property is set it will be used for the filename. There is a property on the grid ShowActionExcelExport that allows the developer to disable the display of the icon.
Set the Grid's Actions.IsExcelExportEnabled to false to prevent the default Export to Excel functionality.
Tap into the grid's drag-and-drop reordering capabilities by binding your custom reorder handler to the grid's GridReorder event handler. Since the Rock.Data.Service has a Reorder() method, any entity service class that inherits from Service<t> can easily have its items reordered.
protected override void OnInit( EventArgs e )
{
// ...
gMyGrid.GridReorder += gMyGrid_GridReorder;
gMyGrid.Actions.IsAddEnabled = true;
gMyGrid.Actions.AddClick += gMyGrid_Add;
}
void gMyGrid_GridReorder( object sender, GridReorderEventArgs e )
{
// ...
Service.Reorder( mylist, e.OldIndex, e.NewIndex, CurrentPersonId );
BindGrids();
}
void gMyGrid_Add( object sender, EventArgs e )
{
ShowEdit( 0 ); // a method that builds a form for your entity/item
}In addition to the three classes (grid-table, table-bordered, and table-striped; see Bootstrap Base CSS Tables) used to style the Grid, there are two other classes (table-full and table-light) which are used based on the grid's (DisplayType). Setting the DisplayType property of the grid to "Light" will create a simplified grid without a heavy header or footer.
<Rock:Grid ID="gMarketingCampaignAudiencesPrimary" runat="server" DisplayType="Light">
<Columns>
<asp:BoundField DataField="Name" HeaderText="Primary Audience" />
<Rock:DeleteField OnClick="gMarketingCampaignAudiences_Delete" />
</Columns>
</Rock:Grid>
The Rock Grid uses bootbox which uses Twitter Bootstrap Modals for things like delete confirmation, etc. Therefore theme makers will be able to style the modals to suite their needs.
The GridFilter provides a standard mechanism for filtering your grid and for retaining the values a user sets in the filter. By default your grid should 'show everything' and then use filters to reduce the amount of data on the grid. You should also store the user's filter settings for re-use later.
An excerpt from the Financial.ascx block.
<Rock:GridFilter ID="rFilter" runat="server"
OnApplyFilterClick="rFilter_ApplyFilterClick" OnDisplayFilterValue="rFilter_DisplayFilterValue">
<Rock:DateTimePicker ID="dtStartDate" runat="server" SourceTypeName="Rock.Model.FinancialTransaction, Rock"
PropertyName="TransactionDateTime" LabelText="From Date" />
<Rock:DateTimePicker ID="dtEndDate" runat="server" SourceTypeName="Rock.Model.FinancialTransaction, Rock"
PropertyName="TransactionDateTime" LabelText="To Date" />
<Rock:LabeledTextBox ID="txtFromAmount" runat="server" LabelText="From Amount"></Rock:LabeledTextBox>
<Rock:LabeledTextBox ID="txtToAmount" runat="server" LabelText="To Amount"></Rock:LabeledTextBox>
<Rock:LabeledTextBox ID="txtTransactionCode" runat="server" LabelText="Transaction Code"></Rock:LabeledTextBox>
<Rock:LabeledDropDownList ID="ddlFundType" runat="server" LabelText="Fund Type" />
<Rock:LabeledDropDownList ID="ddlCurrencyType" runat="server" LabelText="Currency Type" />
<Rock:LabeledDropDownList ID="ddlCreditCardType" runat="server" LabelText="Credit Card Type" />
<Rock:LabeledDropDownList ID="ddlSourceType" runat="server" LabelText="Source Type" />
</Rock:GridFilter>
The OnApplyFilterClick handler will fire once the user clicks the Apply button in the filter. In your handler you may want to save certain settings as user's preferences and re-bind your grid using the filters.
By calling the filter's SaveUserPreference(string key, string value) method with the value of each field, Rock will store the user's preferences for re-use next time they use the filter/grid on this page.
protected void rFilter_ApplyFilterClick( object sender, EventArgs e )
{
rFilter.SaveUserPreference( "From Date", dtStartDate.Text );
rFilter.SaveUserPreference( "To Date", dtEndDate.Text );
rFilter.SaveUserPreference( "From Amount", txtFromAmount.Text );
rFilter.SaveUserPreference( "To Amount", txtToAmount.Text );
// ...
rFilter.SaveUserPreference( "Source", ddlSourceType.SelectedValue != All.Id.ToString() ?
ddlSourceType.SelectedValue : string.Empty );
BindGrid();
}The next time the user views the grid on that page, the filter grid will display the user's previously stored preferences.
Normally the filter will automatically display previously stored filter preferences, however in certain cases the value that is stored is a primary key (i.e., not suitable for displaying). In this case you should can handle the GridFilter's DisplayFilterValue event.
For example, suppose we've got a dropdown list of SourceTypes in our filter which are actually items of a particular Defined Type. To display the name of the selected item in the dropdown list we must convert the stored key value to the proper name as shown in this code snippet from the Financial.ascx.cs block. The event argument's Key will be the string you provided when you called SaveUserPreference.
protected void rFilter_DisplayFilterValue( object sender, Rock.Web.UI.Controls.GridFilter.DisplayFilterValueArgs e )
{
switch ( e.Key )
{
// Handle each user preference as needed
// ...
case "Source":
int definedValueId = 0;
if ( int.TryParse( e.Value, out definedValueId ) )
{
var definedValue = DefinedValueCache.Read( definedValueId );
if ( definedValue != null )
{
e.Value = definedValue.Name;
}
}
break;
}
}Notice how the e.Value is parsed and used to fetch the corresponding DefinedValue from the cache. If it was found, the e.Value is set to its Name property. This will be a common approach when using Defined Types in any grid filters you create.
When the user has a chance to filter based on a yes/no (boolean) property, it's recommended that you allow them to use a radio-button-list to make their choice with a three option list:
With this approach the user can easily choose to see "all" (yes or no), or only the "yes" or only the "no" items. In this case, you may also choose to use a drop-down-list. Normally a drop-down-list hides what other choices a user may make but in this case they are fairly intuitive and expected.