.NET FOLLOWER

    How to create/open a Modal Dialog Window (along with the passing parameters into it) is shown in the post SharePoint: How to pass parameters into a Modal Dialog Window and then access them. This post, in turn, will be devoted to closing the Modal Dialog Window.

Modal Dialog Window is based on IFrame element

As you probably know, Modal Dialog Windows are implemented through IFrame elements. So, when saying “open a web page in a Modal Dialog Window” we mean to load another Html document into an IFrame element of the current Html document. Let’s call the page, which hosts the IFrame element, a Parent-page and the page loaded into the IFrame – a Child-page. From the Child-page the IFrame element containing it can be reached by means of the window.frameElement DOM-object.

Methods to close Modal Dialog Window

To close a Modal Dialog Window we can employ the methods shown below. Note that the methods become accessible through the window.frameElement after the dialog has been opened/created, in other words, SP Dialog framework extends the window.frameElement object by adding these custom methods.

• SP.UI.ModalDialog.commonModalDialogClose(DialogResult dialogResult, Object returnVal)
• window.frameElement.commonModalDialogClose(DialogResult dialogResult, Object returnVal)
• window.frameElement.commitPopup(Object returnVal)
• window.frameElement.cancelPopUp()
• Summary

SP.UI.ModalDialog.commonModalDialogClose

This method allows to close the current (the most recently opened) Modal Dialog Window, passing a desirable DialogResult and a return value into the dialogReturnValueCallback method. This method is mostly intended to be called from the Parent-page. Below is a sample of possible use. Let’s assume that within the Parent-page we have two JavaScript functions, OpenChildDialog and CloseChildDialog, and a Html link, which opens the dialog and sets up the delayed closing of it. The functions:

function OpenChildDialog() {
  var opt = {
    url : 'childPage.aspx',
 
    dialogReturnValueCallback:
      function (res, retVal) {
        alert(retVal);
      }
  };
  SP.UI.ModalDialog.showModalDialog(opt);
}
function CloseChildDialog() {
  //SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK, 'Closed with OK result');
  SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.cancel,'Cancelled'); 
}

The link:

<a href="#" onclick="OpenChildDialog(); setTimeout(function(){ CloseChildDialog(); }, 10000); return false;">
Open dialog
</a>

So, clicking on the link you open the dialog, which will be closed automatically in 10 seconds unless you close it manually before.

window.frameElement.commonModalDialogClose

Technically, it’s the same commonModalDialogClose function, but accessible through the window.frameElement object. Unlike the previous one the given function is intended to be called from within the Child-page (opened in the dialog). The main advantage of the window.frameElement.commonModalDialogClose is that it can be invoked from within a SharePoint-independent page, which knows nothing about SP Dialog framework and its js-files. Before showing an example, let’s take a look at the SP.UI.DialogResult enumeration, which is situated in the SP.UI.Dialog.js file:

SP.UI.DialogResult.prototype = {
    invalid: -1, 
    cancel : 0, 
    OK     : 1
}

Use of SP.UI.DialogResult inside the SharePoint-independent page will cause getting of ‘SP’ is undefined error message. So, we have to use the real values of SP.UI.DialogResult as the enumeration apparently will be undefined. So, below is an example of use. Let’s assume that to open the dialog we use the same OpenChildDialog method listed above and, somewhere within the Child-page, we have two Html links to close the dialog with OK or cancel as the result. The links:

<a href="#" onclick="window.frameElement.commonModalDialogClose(1 /*OK*/, 'Closed with OK result'); return false;">
Commit
</a>
<a href="#" onclick="window.frameElement.commonModalDialogClose(0 /*cancel*/, 'Cancelled'); return false;">
Cancel
</a>

window.frameElement.commitPopup

The given function closes the dialog and passes SP.UI.DialogResult.OK as the result. It also allows to pass a return value into the dialogReturnValueCallback method. Like the previous one, window.frameElement.commitPopup is intended to be called from within the Child-page, which may be SharePoint-independent. Traditionally, an example implies that the dialog is opened by the OpenChildDialog method and contains a Html link:

<a href="#" onclick="window.frameElement.commitPopup('Closed with OK result'); return false;">
Commit
</a>

Another good example of use of window.frameElement.commitPopup is demonstrated in the article – SharePoint: SPLongOperation inside a Modal Dialog Window.

window.frameElement.cancelPopUp

The window.frameElement.cancelPopUp closes the dialog as well. However, as opposite to commitPopup, it returns the SP.UI.DialogResult.cancel as the dialog result and doesn’t allow to pass a return value. It should be called from within the Child-page, which may be SharePoint-independent. The opened dialog can be closed, for example, by the Html link, which is placed within the Child-page and defined as the following:

<a href="#" onclick="window.frameElement.cancelPopUp(); return false;">
Cancel
</a>

Summary

Let’s take a look at a summary table below. The SharePointless column indicates whether the appropriate function can be used from within a SharePoint-independent page. The Intended to be placed within column shows where the appropriate function should be put in, in either Parent– or Child-pages. Note that there are no strict rules where the functions must be used, all of them, in some conditions, can be used on any pages.

ValidatorValidate

The easiest way to trigger a validator on the client-side is to use the ValidatorValidate method provided by ASP.NET as a part of a Validation client-side API. You don’t need to include any js-files so as the all required scripts will be included automatically when you add a validator to your page. The typical use is something like this

var validator = document.getElementById('ctl00_PlaceHolderMain_info_textbox').Validators[0]; // Page_Validators[0];

ValidatorValidate(validator); // fire validation
ValidatorUpdateIsValid(); // update the global Page_IsValid flag

The ValidatorValidate makes the passed validator examine the input element bound to it and updates the validator‘s display (shows or hides its error message). I also recommend to call the ValidatorUpdateIsValid method, which updates the global variable Page_IsValid and by that may prevent the Html-form submit when the validator failed.

Below is a simple JavaScript function I use to force validation of a specified input. The function gets the input by the passed id, then goes through the all validators linked to the input and activates each of them. Finally, it updates the global Page_IsValid flag.

function ForceInputValidation(inputId) {
    var targetedControl = document.getElementById(inputId);    
    
    if (typeof(targetedControl.Validators) != "undefined") {        
        var i;
        for (i = 0; i < targetedControl.Validators.length; i++)
            ValidatorValidate(targetedControl.Validators[i]);
    }

    ValidatorUpdateIsValid();
}

ASP.Net places the initialization of validators at the end of the web page, so, it makes sense to handle the input‘s Validators-collection after the page has been loaded entirely. The following example demonstrates how to fire validation of the specified input right after the page has been loaded. jQuery is a best helper in that.

$(document).ready(function () {    
    ForceInputValidation('ctl00_PlaceHolderMain_info_textbox');
});

ValidatorEnable

As some blogs and forums recommend, you can also use another built-in function – ValidatorEnable, the code of which is shown below:

function ValidatorEnable(validator, enable) {
    validator.enabled = (enable != false);
    ValidatorValidate(validator);
    ValidatorUpdateIsValid();
}
// ...
// the typical use to fire validation is
var validator = document.getElementById('ctl00_PlaceHolderMain_info_textbox').Validators[0]; // Page_Validators[0];
ValidatorEnable(validator, true);

The ValidatorEnable calls sequentially the same ValidatorValidate and ValidatorUpdateIsValid functions we use above. Thus to activate one validator you can use, with no difference, either ValidatorEnable or combination of ValidatorValidate and ValidatorUpdateIsValid. But activating several validators (like in ForceInputValidation function) I advise employing the pair of the ValidatorValidate and ValidatorUpdateIsValid functions. That is because the ValidatorUpdateIsValid loops through all validators on the page. So, for best performance we should fire the all required validators and then call ValidatorUpdateIsValid once.

ps here is good source of information about the client-side validation.

Passing parameters into a Modal Dialog Window

Opening a web page in a Modal Dialog Window we can pass parameters to it through the args property of dialog options. A typical JavaScript might look like

function OpenDialog() {
  var opt = {
    url     : 'somePage.aspx',
    autoSize: true,
 
    /* additional parameters */
    args: { arg1: 'The second argument is ', arg2: 12345 },
 
    dialogReturnValueCallback:
      function (res, retVal) {
        if (res === SP.UI.DialogResult.OK) { /* do something */ }
        else { /* do something else */ }
      }
  };
  SP.UI.ModalDialog.showModalDialog(opt);
}

Now let’s take a look how these parameters can be accessed from within the Parent-page and the page opened in the dialog.

Accessing the arguments from within the page opened in the dialog

In general case, when opening a SharePoint-based page, the passed arguments could be reached using a script similar to the following:

function DoSomethingWithArgs() {
  var passedArgs = SP.UI.ModalDialog.get_childDialog().get_args(); /* get access to the passed parameters */
  alert(passedArgs.arg1 + passedArgs.arg2);
}

The key method here is SP.UI.ModalDialog.get_childDialog, which allows to get the current dialog, or, to be more precise, the current SP.UI.Dialog object. The retrieved object, in turn, exposes the get_args method to access the passed parameters.

A possible use of the DoSomethingWithArgs function from the sample above is

<a href="#"
  onclick="ExecuteOrDelayUntilScriptLoaded(DoSomethingWithArgs, 'sp.ui.dialog.js'); return false;">
Show me the passed arguments
</a>

In case the web page opened in the dialog knows nothing about SharePoint and doesn’t include appropriate SharePoint JavaScript files, use the following version of the code:

function DoSomethingWithArgs() {
  var passedArgs = window.frameElement.dialogArgs; /* get access to the passed parameters */
  alert(passedArgs.arg1 + passedArgs.arg2);
}

Where the dialogArgs as a property of the window.frameElement object is provided by SP Dialog framework and returns the passed arguments.

Assuming the SharePoint‘s ExecuteOrDelayUntilScriptLoaded function isn’t available as well, the possible use of the DoSomethingWithArgs is quite straightforward:

<a href="#" onclick="DoSomethingWithArgs(); return false;">
Show me the passed arguments
</a>

All other conditions being equal, I recommend the approach with the window.frameElement object as it works always and doesn’t require the page in the dialog to be bound to SharePoint somehow.

Accessing the passed arguments from within the Parent-page

The Parent-page is a place where we define parameters and pass them to the dialog. So, the most direct way is to store the required values into some variable(s) to access them later. Another way is to rely on Dialog framework and use the code already mentioned in the previous section, namely

//...
var passedArgs = SP.UI.ModalDialog.get_childDialog().get_args();
//...

The more interesting case, however, is to access the passed arguments inside the dialogReturnValueCallback function. The listing below contains an example of one of such dialogReturnValueCallback definitions:

function OpenDialog() {
  var opt = {
    url     : 'somePage.aspx',
    autoSize: true,

    /* additional parameters */
    args: { arg1: 'The second argument is ', arg2: 12345 }, 

    dialogReturnValueCallback:
      function (res, retVal) {
        if (res === SP.UI.DialogResult.OK) {                    
          var passedArgs = this.get_args(); /* get access to the passed parameters */
          alert(passedArgs.arg1 + passedArgs.arg2);
        }
      }
  };
  SP.UI.ModalDialog.showModalDialog(opt);
}

The dialogReturnValueCallback function will be called in the context of the SP.UI.Dialog object associated with the current Modal Dialog Window. Therefore, inside the function the passed arguments can be accessed using this-keyword.

A possible use of the OpenDialog is shown below:

<a href="#" 
  onclick="ExecuteOrDelayUntilScriptLoaded(OpenDialog, 'sp.ui.dialog.js'); return false;">
Open Modal Dialog Window
</a>

ps There is a quite detailed article about dealing with Dialogs in SharePoint 2010. So, read to learn more about Dialog framework.

    In SharePoint 2010 by default a list item is opened in a Modal Dialog Window. The dialog adjusts its size depending on the size of the contained content and provides users with buttons to maximize and close itself. So, I was asked to maximize the dialog when opening some list items.

Creating and Initializing of a Modal Dialog Window

The JavaScript responsible for the dialog rendering is in the SP.UI.Dialog.js file (usually located in C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS). Clicking on a link-title, for example, in a list view leads to creating and displaying a new Modal Dialog Window in a manner similar to the following:

var options = SP.UI.$create_DialogOptions();

options.url           = 'display-page corresponding to the current list item';
options.title         = 'list item title';
options.allowMaximize = true;
options.showClose     = true;

// possible option, but it's not used in the place in question
//options.showMaximized = true;

var modalDialog = SP.UI.ModalDialog.showModalDialog(options);

The commented line demonstrates one of the possible settings, showMaximized, which apparently does exactly what we need. So, it would be a good solution if we had control under creation of the dialog. Unfortunately, we don’t have. Modifying scripts in SharePoint system js-files runs counter to all known “best practices”, therefore I don’t even consider it. Another possible way is override the client-side OnClick-events of the link-title fields everywhere (in list views, web parts and so on) so that your own script would create and display the dialog in a required manner. Obviously, it’s a very time-consuming solution. Moreover, every time when creating a list view, web part or something else you always have to keep in mind the possible need to rewrite their OnClick-events. In my opinion the only acceptable approach is allow a web page itself to maximize the dialog window it’s placed in.

Script to Maximize a Modal Dialog Window

For that, first of all, we need to have a JavaScript to maximize the current dialog. As SP.UI.Dialog.js doesn’t provide a function/method intended for use outside, we have to consume undocumented internal functions. A suitable script is described in the blog post – “How to maximize a Modal Dialog in JavaScript?“. With slight changes the JavaScript looks like the following

function _maximizeWindow() {
    var currentDialog = SP.UI.ModalDialog.get_childDialog();
    if (currentDialog != null && !currentDialog.$S_0)
        currentDialog.$z();    
    }
    ExecuteOrDelayUntilScriptLoaded(_maximizeWindow, 'sp.ui.dialog.js');

_maximizeWindow gets the current dialog window instance and tries to maximize it if it hasn’t been done before. ExecuteOrDelayUntilScriptLoaded, in turn, is applied to ensure the _maximizeWindow is called after the sp.ui.dialog.js has been completely loaded.

Script Applying

Having the script, we can insert it into the end of a web page to be maximized. It could be done through SharePoint Designer or by modifying a physical aspx-file defined as a display/new/edit form for a list or a content type. However, I decided to add the script dynamically in a page’s code-behind. So, the resultant code is shown below:

using System;
using System.Web.UI;
using Microsoft.SharePoint;

//...

public class DisplayListItem : Page
{
    protected override void OnLoad(EventArgs e)
    {
        base.OnLoad(e);
        if(!IsPostBack)
            AddMaximizeWindowScript();
    }

    //...

    protected virtual void AddMaximizeWindowScript()
    {
        if (SPContext.Current.IsPopUI)
        {
            const string scriptKey = "MaxWinwScript";
            if (!ClientScript.IsClientScriptBlockRegistered(GetType(), scriptKey))
            {
                const string jsScript =
                    @"function _maximizeWindow() {
                        var currentDialog = SP.UI.ModalDialog.get_childDialog();
                        if (currentDialog != null && !currentDialog.$S_0)
                            currentDialog.$z();    
                        }
                        ExecuteOrDelayUntilScriptLoaded(_maximizeWindow, 'sp.ui.dialog.js');";

                ClientScript.RegisterClientScriptBlock(GetType(), scriptKey, jsScript, true);
            }
        }
    }
    
    //...
}

You may ask why I use RegisterClientScriptBlock instead of RegisterStartupScript or window.onload, or jQuery‘s $(document).ready (the latest two arise on client side). The reason is that initially the dialog window is created with the autoSize option. So, it’s very reasonable to maximize the window as soon as possible to prevent the content’s size calculating, which apparently happens after the page has been loaded entirely.

    I was asked to develop a control based on the ItemPicker control, which, in addition to ability of choosing an external data item through BDC, brings it to client side without page postback. There was the following supposed sequence of actions:

1. An user chooses a data item in the Picker Dialog;
2. The identifier of the selected item is sent to the server through an Ajax-like technology;
3. Using the received identifier, the server fetches the proper data out through BDC and sends it back to the client. By “the proper data” I mean the values of either all fields available in the selected data item or only fields defined in control declaration;
4. On the client side, the received data is parsed and displayed in UI;

Additionally, the control should be free of bindings to SPField as it should be capable to reside within an independent aspx-page locating in the _layout folder.

*Note: for better understanding of BDC infrastructure, please read the following blog posts: SharePoint: Brief introduction to Business Data Catalog and SharePoint: Understanding BusinessData Column.

So, I developed the required control and made it as reusable as possible. Let’s call the control MyItemPicker (it’s so unusual, isn’t? :)). For sake of simplicity I decided to use the ASP.Net client callbacks applied through the ICallbackEventHandler interface. The ASP.Net client callbacks can be considered as a wrapper on XMLHTTP object. Also the MyItemPicker comprises and uses the standard ItemPicker.

Ok, let’s start with declaration of the control within page:

<MYCC:MyItemPicker id="myItemPicker" runat="server" LobSystemInstanceName="Products" 
EntityName="Product" PrimaryColumnName="Name" ClientCallback="MyClientCallback" 
ClientCallbackError="MyClientCallbackError" CallbackBDCFieldFilter="Price,Producer" />

The significant properties here are

• LobSystemInstanceName is the name of the Lob System Instance, through which data is provided to pick;
• EntityName is the type name of data items populating the picker;
• PrimaryColumnName is the name of the data item field, the value of which is used as a display value;
• ClientCallback is the name of the JavaScript function, which has to be present within the page. In case of success, the given function accepts and processes the server response containing fetched data;
• ClientCallbackError is the name of the JavaScript function, which can be within the page and is called, when server fails to fulfill request. This property is optional;
• CallbackBDCFieldFilter is the comma-separated string containing names of data item fields that should be included in server response. For example, if a BDC Entity has four fields – ID, Name, Price and Producer, you might want to have on client side only two of them – Price and Producer. If the CallbackBDCFieldFilter property is empty or not presented in the declaration, server response contains the values of all available fields of BDC Entity;

The sample of the JavaScript functions, which should be indicated in the ClientCallback and ClientCallbackError properties, is shown below. Note the functions’ signatures.

<script type="text/javascript">

    function MyClientCallback(result, context) {

        alert("Result: " + result);
        
        if (result != null && typeof result != "undefined" && result.length != 0) {
            var res = eval("(" + result + ")");

            alert('Price: '    + res.Price);
            alert('Producer: ' + res.Producer);
            
            // update UI with received data
        }        
    }

    function MyClientCallbackError(result, context) {
        alert('Error: ' + result);            
    }

</script>

The server response looks like

{ 'Price' : '10.00', 
  'Producer' : 'Microsoft Corporation' }

Thus, the response is formatted in the manner to be easily turned into JavaScript object by means of the eval function.

So, it’s time to examine the source code of the MyItemPicker itself.

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Portal.WebControls;
using System.Web.UI;
using Microsoft.Office.Server.ApplicationRegistry.Infrastructure;
using Microsoft.Office.Server.ApplicationRegistry.MetadataModel;
using Microsoft.Office.Server.ApplicationRegistry.Runtime;
using System.Data;

namespace MyControls
{
    public class MyItemPicker : Control, ICallbackEventHandler
    {
        #region fields & properties
        protected ItemPicker _picker                    = null;
        protected string     _callbackRequestedEntityId = string.Empty;

        public string LobSystemInstanceName  { get; set; }
        public string EntityName             { get; set; }
        public string PrimaryColumnName      { get; set; }

        public string ClientCallback         { get; set; }
        public string ClientCallbackError    { get; set; }

        public string CallbackBDCFieldFilter { get; set; }
        #endregion

        #region public methods
        // Implementation of the ICallbackEventHandler interface
        // Generates response that will be sent to client
        public string GetCallbackResult()
        {
            return GetJSResult();
        }
        // Implementation of the ICallbackEventHandler interface
        // Retrieves and preserves identifier of selected data item sent from client
        public void RaiseCallbackEvent(string eventArgument)
        {
            _callbackRequestedEntityId = eventArgument;
        }
        #endregion

        #region internal methods
        protected override void OnInit(EventArgs e)
        {
            base.OnInit(e);
            EnsureChildControls();            
        }

        protected override void CreateChildControls()
        {            
            base.CreateChildControls();

            if (_picker == null)
            {
                _picker = new ItemPicker();                
                _picker.MultiSelect = false;
                _picker.ID = ID + "_ItemPicker";
                try
                {
                    this.SetExtendedDataOnPicker(_picker);
                }
                catch (Exception exception)
                {
                    _picker.ErrorMessage = exception.Message;
                    _picker.Enabled = false;
                }

                this.Controls.Add(_picker);
            }            
        }

	/// <summary>
        /// Initilizes main item picker's properties
        /// </summary>        
        protected virtual void SetExtendedDataOnPicker(ItemPicker picker)
        {            
            ItemPickerExtendedData data = new ItemPickerExtendedData();

            BDCMetaRequest request = new BDCMetaRequest(LobSystemInstanceName, EntityName);
            data.SystemInstanceId  = request.FoundLobSystemInstance.Id;
            data.EntityId          = request.FoundEntity.Id;

            List<uint> list = new List<uint>();
            FieldCollection fields = request.FoundEntity.GetSpecificFinderView().Fields;
            foreach (Field field in fields)
                if (string.Equals(field.Name, PrimaryColumnName, StringComparison.OrdinalIgnoreCase))                
                    data.PrimaryColumnId = field.TypeDescriptor.Id;
                else
                    list.Add(field.TypeDescriptor.Id);

            data.SecondaryColumnsIds = list.ToArray();
            picker.ExtendedData = data;
        }

        protected override void OnPreRender(EventArgs e)
        {
            base.OnPreRender(e);
            AddJSCallbackFunctions();
            AddAdditionalJSFunctions();
        }

        /// <summary>
        /// Generates and adds auxiliary JavaScript functions to the page
        /// </summary> 
        protected void AddAdditionalJSFunctions()
        {
            if (_picker != null)
            {
                _picker.LoadPostData(null, null); // this line is required to force CreateChildControls() and to have HiddenEntityKey created
                Control upLevelDiv = FindControlRecursive(_picker, "upLevelDiv");
                if (upLevelDiv != null)
                {
                    string clearFuncName = "ClearItemPicker_" + ID;
                    string clearFunc =
                        "function " + clearFuncName + "() {" +
                            "var upLevelDiv = document.getElementById('" + upLevelDiv.ClientID + "');" +
                            "if (upLevelDiv != null) {" +
                                "upLevelDiv.innerHTML = '';" +
                                "updateControlValue('" + _picker.ClientID + "');" +
                                "}" +
                            "}";
                    Page.ClientScript.RegisterClientScriptBlock(GetType(), clearFuncName, clearFunc, true);
                }
                
                Control hiddenEntityDisplayTextControl = FindControlRecursive(_picker, "HiddenEntityDisplayText");
                if (hiddenEntityDisplayTextControl != null)
                {
                    string getDisplayTextFuncName = "GetDisplayText_" + ID;
                    string getDisplayTextFunc =
                        "function " + getDisplayTextFuncName + "() {" +
                            "var hiddenEntityDisplayTextControl = document.getElementById('" + hiddenEntityDisplayTextControl.ClientID + "');" +
                            "return hiddenEntityDisplayTextControl != null ? hiddenEntityDisplayTextControl.value : '';" +
                        "}";
                    Page.ClientScript.RegisterClientScriptBlock(GetType(), getDisplayTextFuncName, getDisplayTextFunc, true);
                }
            }            
        }

        /// <summary>
        /// Generates and adds the picker's AfterCallbackClientScript to the page
        /// </summary> 
        protected void AddJSCallbackFunctions()
        {
            if (_picker != null)
            {
                string callbackFunc = null;
                if (!string.IsNullOrEmpty(ClientCallback) && !string.IsNullOrEmpty(ClientCallbackError))
                    callbackFunc = Page.ClientScript.GetCallbackEventReference(this, "arg", ClientCallback, "context", ClientCallbackError, true);
                else
                {
                    if (!string.IsNullOrEmpty(ClientCallback))
                        callbackFunc = Page.ClientScript.GetCallbackEventReference(this, "arg", ClientCallback, "context", true);
                }
                if (!string.IsNullOrEmpty(callbackFunc))
                {
                    _picker.LoadPostData(null, null); // this line is required to force CreateChildControls() and to have HiddenEntityKey created

                    Control pickerEntityKeyHidden = FindControlRecursive(_picker, "HiddenEntityKey");
                    if (pickerEntityKeyHidden != null)
                    {
                        string clientFuncName = "GetBdcFieldValuesAsync_" + ID;
                        string clientFunc =
                            "function " + clientFuncName + "(context)" +
                            "{" +
                                "var pickerEntityKeyHidden = document.getElementById('" + pickerEntityKeyHidden.ClientID + "');" +
                                "if (pickerEntityKeyHidden != null)" +
                                "{" +
                                    "var arg = pickerEntityKeyHidden.value;" +
                                    callbackFunc + ";" +
                                "}" +
                            "}";
                        Page.ClientScript.RegisterClientScriptBlock(GetType(), clientFuncName, clientFunc, true);
                        _picker.AfterCallbackClientScript = clientFuncName + "('" + ID + "');";
                    }
                }
            }
        }

        /// <summary>
        /// Makes request to external data source and returns json-result
        /// </summary>         
        protected string GetJSResult()
        {
            string res = string.Empty;

            try
            {
                if (!string.IsNullOrEmpty(_callbackRequestedEntityId))
                {
                    Dictionary<string, byte> bdcFieldFilter = GetBDCFieldFilter(CallbackBDCFieldFilter);
                    
                    BDCRequestById request = new BDCRequestById(LobSystemInstanceName, EntityName, _callbackRequestedEntityId);

                    StringBuilder sb = new StringBuilder();
                    sb.Append("{");
                    foreach (Field field in request.FoundEntityInstance.ViewDefinition.Fields)
                    {
                        if (bdcFieldFilter.Count == 0 || bdcFieldFilter.ContainsKey(field.Name))
                        {
                            if (sb.Length > 1)
                                sb.Append(", ").AppendLine();
                            sb.Append("'").Append(field.Name).Append("' : ");
                            sb.Append("'").Append(Convert.ToString(request.FoundEntityInstance.GetFormatted(field))).Append("'");
                        }
                    }
                    sb.Append("}");                    

                    res = sb.ToString();
                }
            }
            catch (Exception ex)
            {
                // write error to log
            }

            return res;
        }

        /// <summary>
        /// Parses the user defined list of bdc fields, the values of which should be retrieved
        /// </summary>        
        protected static Dictionary<string, byte> GetBDCFieldFilter(string commaSeparatedBdcFields)
        {
            Dictionary<string, byte> res = new Dictionary<string, byte>(StringComparer.OrdinalIgnoreCase);

            if (!string.IsNullOrEmpty(commaSeparatedBdcFields))
            {
                string[] bdcFields = commaSeparatedBdcFields.Split(new string[] { "," }, StringSplitOptions.RemoveEmptyEntries);
                foreach (string field in bdcFields)
                    res.Add(field, 0);
            }

            return res;
        }
        #endregion
    }
}

You probably noticed that the functions AddJSCallbackFunctions and AddAdditionalJSFunctions generate and add some JavaScript functions to the page. The exact names of these JavaScript functions depend on the id attribute defined in control declaration. For example, if control id is “myItemPicker“, the functions’ name will be GetBdcFieldValuesAsync_myItemPicker, ClearItemPicker_myItemPicker and GetDisplayText_myItemPicker.

Let’s take a look at the functions. The main function is GetBdcFieldValuesAsync_myItemPicker, which extracts the encoded id of selected item from ItemPicker and then makes the Ajax-like client callback to the server. The rest two functions are auxiliary, they are not used by MyItemPicker directly, but they are very useful for developing an interaction between user and MyItemPicker. As their names imply, the ClearItemPicker_myItemPicker clears the ItemPicker, and the GetDisplayText_myItemPicker returns the text displayed to user in ItemPicker. The listing below demonstrates the functions within page:

<script type="text/javascript">

    function GetBdcFieldValuesAsync_myItemPicker(context) {
        var pickerEntityKeyHidden = document.getElementById('myItemPicker_ItemPicker_HiddenEntityKey');
        if (pickerEntityKeyHidden != null) {
            var arg = pickerEntityKeyHidden.value;
            WebForm_DoCallback('myItemPicker', arg, ClientCallback, context, ClientCallbackError, true);
        }
    }

    function ClearItemPicker_myItemPicker() {
        var upLevelDiv = document.getElementById('myItemPicker_ItemPicker_upLevelDiv');
        if (upLevelDiv != null) {
            upLevelDiv.innerHTML = '';
            updateControlValue('myItemPicker_ItemPicker');
        }
    }

    function GetDisplayText_myItemPicker() {
        var hiddenEntityDisplayTextControl = document.getElementById('myItemPicker_ItemPicker_HiddenEntityDisplayText');
        return hiddenEntityDisplayTextControl != null ? hiddenEntityDisplayTextControl.value : '';
    }
</script>

The SetExtendedDataOnPicker and GetJSResult methods of MyItemPicker employ the classes BDCMetaRequest and BDCRequestById that are described in my post SharePoint: How to get value from BDC.

The FindControlRecursive method is mentioned in another my post.