umbraco workbench

This package is a new package for adding a master/detail gridview with sorting and paging support.

Details are specified by two options. One or both may be applied (as in the example picture)

1. A specific subset of the fields chosen from the sql query (left side in the details view of the screenshot). This is static content in the table.

2. Using Umbraco /Base and a RenderMacroContent callback, so any content may be rendered using xslt or a custom control (right side in the details view of the screenshot). This is dynamic content added using Ajax.

You can take a look at a live development example here

Installation notes:

1. Install the package
2. Make sure your /config/restExtensions.config file is updated - the core Umbraco package action for this particular file has a bug in some versions of Umbraco. Open the file and ensure you have this entry in the file:

<ext assembly="/bin/BP.Umb.UserControls.GridView" type="BP.Umb.UserControls.GridView.GridViewDetails" alias="bpGridViewDetails">
    <permission method="RenderDetails" allowAll="true" />
</ext>

3. If you are not going to use SqlServer as your datasource, install/create the appropriate plugin
4. (Optional: Add the db connection entry to the web.config)

<connectionStrings>
...
  <add name="UmbracoGridViewConnectionString"
     connectionString="Data Source=xx;Initial Catalog=xx;Persist Security Info=True;User ID=xx;Password=xx"
     providerName="System.Data.SqlClient"/>
...
</connectionStrings>

5. If you want to use dynamic details, implement the bpGridViewRenderDetail macro. Note that the KeyField argument from the BPGridView macro may be passed to the bpGridViewRenderDetail macro as argument entryId.
6. Insert the BPGridView in a template.
7. Modify the BP.Umb.UserControls.GridView.css stylesheet to meet your design guideline.

Data Source Plugins

The data source bound to the grid view is implemented in a plugin architecture to enable anyone to create their own data source - the only thing necessary is implementing a specific interface, building the plugin and place the dll in the Umbraco bin-folder and then setup the plugin in the bpGridView.config file.

The plugin interface

The implementation of an interface may look like this:

using System;
using System.Data;
using MySql.Data.MySqlClient;
using System.Web.UI.WebControls;

namespace BP.Umb.DataSourcePlugin
{

    public class MySqlPlugin : IDataSourcePlugin
    {
        public MySqlPlugin()
        {
        }

        // The single point of entry to our plugin
        // Accepts an IPluginContext object which holds the current context.
        public void PerformAction(IDataSourcePluginContext context)
        {
            context.DataSource = CreateDataSource(context);
        }

        // Create the data source
        private DataTable CreateDataSource(IDataSourcePluginContext context)
        {
            MySqlConnection myConnection = new MySqlConnection(context.ConnectionString);
            MySqlDataAdapter myDataAdapter = new MySqlDataAdapter(context.QueryString, myConnection);
            DataTable myDataTable = new DataTable();
            myDataAdapter.Fill(myDataTable);
            return myDataTable;
        }
    }

}

The IDataSourcePlugin is defined within the BP.Umb.DataSourcePlugin namespace in the BPGridView dll:

using System;
using System.Data;
using System.Runtime.InteropServices;
using System.Web.UI.WebControls;

namespace BP.Umb.DataSourcePlugin
{
    [GuidAttribute("3ce6edc1-be6e-4a80-aabb-3368dd813841")]
    public interface IDataSourcePlugin
    {
        void PerformAction(IDataSourcePluginContext context);
    }

    public interface IDataSourcePluginContext
    {
        string ConnectionString { get; set; }
        string QueryString { get; set; }
        DataTable DataSource { get; set; }
    }
}

The bpGridView.config

You have to register your plugin in the /config/bpGridView.config file.

The id is a unique string id, the type has the format "<classname with namespace>, <assemblyname>"

E.g. like this:

<?xml version="1.0" encoding="utf-8" ?>
<DataSourcePlugins>
  <plugin id="sqlserver" type="BP.Umb.DataSourcePlugin.SqlServerPlugin, BP.Umb.DataSourcePlugin.SqlServer" />
  <plugin id="mysql" type="BP.Umb.DataSourcePlugin.MySqlPlugin, BP.Umb.DataSourcePlugin.SqlServer" />
</DataSourcePlugins>

Macro BPGridView parameters

(* is mandatory)

PageSize:
  Number of entries pr. page .

EnableSorting:
  Enable column sorting.

EnableStaticDetails:
  Show static (sql) details.

EnableDynamicDetails:
  Show dynamic (base/ajax/macro) details.

KeyField:
  Sql query field to pass on to dynamic macro call.

OverviewFields (*):
  Sql query fields to show as columns in master table.

SelectCommand (*):
  Sql query command. Note, that due to some weird behavior with ','- characters you may have to replace all ','-characters in your query with '%'-characters. E.g. "Select foo% bar from foobar"

ConnectString:
  Connection string. If left empty a UmbracoGridViewConnectionString
  connection string must exist in the web.config.

DbId:

  Data source id, e.g. "sqlserver" or "mysql" depending on the data source plugins.

Example macro call:

<umbraco:Macro
    PageSize="20" EnableSorting="1" EnableExpansion="0" DbId="mysql" 
    OverviewFields="TEXT|ID|CREATEDATE|TRASHED|UNIQUEID" 
    SelectCommand="select * from UMBRACONODE ORDER BY id" 
    ConnectString="" 
    Alias="BPGridView" 
runat="server"></umbraco:Macro>

Let me know if you have any problems with getting it working, or if you can thing of any obvious modifications or enhancements.

Download package BPGridView