In SharePoint, our model is represented like this in the out of the box UI:

Display Form	New- and Edit Forms

What we really want to achieve in this article is to manipulate the behavior of our Display- and New/Edit forms to look something like this:

Display Form Published: Icon instead of Yes/No text. Color: Lit up with the selected color in the UI.	New- and Edit Forms Color: Replaced with a custom field control

As you can see in the last two images above, the result of our development is that we’ll be using a custom control (DropDown) instead of the standard TextBox for our Color-field, and we’ll change the way the Published-field looks in the Display Form. It should give you an idea of how you can customize and alter the behavior of your BCS External List Forms.

So without further ado, let’s get started with modifying our forms!

(I assume that you already have a BCS Model in place and will not iterate the steps for creating one here…)

Modifying New/Edit forms: Custom Field Control to the rescue

When it comes to the BCS Model, you should really always edit it through the XML and not through the Visual Studio UI. Start by right-clicking your BCS Model and selecting the "Open With…" alternative:

Then choose your favorite XML editor:

When you’re in this mode, you obviously have to be careful not to mistype or misspell anything as it can result in a broken BCS Model. Awesome

To cut it short, here’s an extract for the "Creating" Method, which references a Custom Field Control called ColorField:

            <Method Name="Create">
              <Parameters>
                <Parameter Name="returnEntity1" Direction="Return">
                  <TypeDescriptor Name="ReturnEntity1" TypeName="TOZIT.Samples.BCSExtensions.BdcModel1.Entity1, BdcModel1">
                    <TypeDescriptors>
                      <TypeDescriptor Name="Identifier1" IdentifierName="Identifier1" TypeName="System.String" />
                      <TypeDescriptor Name="Published" IsCollection="false" TypeName="System.Boolean" />
                      <TypeDescriptor Name="Color" TypeName="System.String">
                        <Properties>
                          <Property Name="SPCustomFieldType" Type="System.String">ColorField</Property>
                        </Properties>
                      </TypeDescriptor>
                    </TypeDescriptors>
                  </TypeDescriptor>
                </Parameter>
                <Parameter Name="newEntity1" Direction="In">
                  <TypeDescriptor Name="NewEntity1" TypeName="TOZIT.Samples.BCSExtensions.BdcModel1.Entity1, BdcModel1">
                    <TypeDescriptors>
                      <TypeDescriptor Name="Identifier1" IdentifierName="Identifier1" TypeName="System.String" CreatorField="true" />
                      <TypeDescriptor Name="Published" IsCollection="false" TypeName="System.Boolean" CreatorField="true" />
                      <TypeDescriptor Name="Color" TypeName="System.String" CreatorField="true">
                        <Properties>
                          <Property Name="SPCustomFieldType" Type="System.String">ColorField</Property>
                        </Properties>
                      </TypeDescriptor>
                    </TypeDescriptors>
                  </TypeDescriptor>
                </Parameter>
              </Parameters>
              <MethodInstances>
                <MethodInstance Name="Create" Type="Creator" ReturnParameterName="returnEntity1" ReturnTypeDescriptorPath="ReturnEntity1" />
              </MethodInstances>
            </Method>

As you can see above I’ve referenced a property called "SPCustomFieldType" in the code (Read more on BCS Custom Properties), which in turn is referencing something called "ColorField". The ColorField is my CustomField control that is simply a DropDown-box to be represented in the UI instead of the good’ol text box.

Modifying Display Forms: jQuery to the rescue

When it comes to modifying the DispForm of the External List, I’ve had several attempts with the documented RendererDefinition in the past and not one single time it worked for me nor any of my clients. So with that experience, I’ve resorted to using jQuery to modify the rendition of the Display Form. Obviously one could use jQuery for the New- and Edit Forms as well, if you want to.

Short story, the jQuery looks like this:

// Found this through google, but can't remember the source. 
// Great script for string replacements!
String.prototype.replaceAll = function (str1, str2, ignore) {
    return this.replace(new RegExp(str1.replace(/([\/\,\!\\\^\$\{\}\[\]\(\)\.\*\+\?\|\<\>\-\&])/g, "\\$&"), (ignore ? "gi" : "g")), (typeof (str2) == "string") ? str2.replace(/\$/g, "$$$$") : str2);
};

$(document).ready(function () 
{
    // Render an icon instead of Yes/No text
    var publishedHtml = $('h3.ms-standardheader:contains("Published")').closest('tr').children(".ms-formbody").html().toString();
    publishedHtml = publishedHtml.replaceAll("Yes", "<img src='/_layouts/images/TOZIT.Samples.BCSExtensions/checked.png' />");
    publishedHtml = publishedHtml.replaceAll("No", "<img src='/_layouts/images/TOZIT.Samples.BCSExtensions/unchecked.png' />");
    $('h3.ms-standardheader:contains("Published")').closest('tr').children(".ms-formbody").html(publishedHtml);

    // Render the entire TD in the color that was chosen
    var colorHtml = $('h3.ms-standardheader:contains("Color")').closest('tr').children(".ms-formbody").html().toString();
    var colorHtmlTd = $('h3.ms-standardheader:contains("Color")').closest('tr').children(".ms-formbody").attr("style", "background-color:" + colorHtml + ";");
});

Essentially what this jQuery snippet does is that it will find the correct elements in the HTML markup that corresponds to my Fields (you see the :contains("Published") part? That’s where I find the Published-field in the markup). Then I simply alter the text that is sent to us from the server, replacing "Yes/No" with an image of a checked or unchecked checkbox. Pretty simple trick to light up the form a bit without the hassle of trying to get your RendererDefinition working…

Tip: If you want to easily inject your jQuery to the External List Forms, I’d recommend using a DelegateControl override on the AdditionalPageHead. The code for my AdditionalPageHead DelegateControl looks something like this:

        protected void Page_Load(object sender, EventArgs e)
        {
            string httpRequestUrlString = HttpContext.Current.Request.Url.AbsoluteUri;

            // Note: You should create a smarter verification for when to load the scripts than to use a hardcoded value like I've done in this sample. 
            if ((httpRequestUrlString.Contains("/Lists/Sample Entity/") || httpRequestUrlString.Contains("/Lists/Sample%20Entity/")) && httpRequestUrlString.Contains("DispForm.aspx")) // Only render scripts if it's the Display Form on the Sample Entity list
            {
                // Add a reference to jQuery if it isn't already loaded
                ScriptLink.Register(this.Page, "/_layouts/TOZIT.Samples.BCSExtensions/Scripts/jquery-1.7.2.min.js", false);
                ScriptLink.Register(this.Page, "/_layouts/TOZIT.Samples.BCSExtensions/Scripts/bcsDisplayFormScriptSample.js", false);
            }
        }

The code snippet above simply checks the current request and determines whether it’s your specific list being loaded, and then also determine if it’s the DispForm.aspx file being served. As noted in the comments, you should modify this if-statement to suit your needs, should you decide to create a DelegateControl like this.

Summary

Working with BCS is both fun and challenging at the same time. Like most SharePoint projects your requirements always change, and there’s always a need for further investigating the possibilities for how we can deliver quality solutions. In this article I’ve talked about some tips for how you can modify the NewForm and EditForm of your BCS External List by simply using a Custom Field Control. I’ve also talked about how you can deliver customized forms using jQuery as in the DispForm sample above.

As a final note I’d like to shout out to Scot Hillier who is a fellow SharePoint MVP and author of the Professional Business Connectivity Services in SharePoint 2010 book for valuable tips and awesome discussions regarding this topic.