Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

IParametersInProvider Interface

NOTE: This API is now obsolete.

Allows a provider Web Part to communicate its parameter list to other consumer Web Parts.

Namespace:  Microsoft.SharePoint.WebPartPages.Communication
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)
[ObsoleteAttribute("Use System.Web.UI.WebControls.WebParts.IWebPartParameters instead")]
public interface IParametersInProvider

The IParametersInProvider interface should be used with parts that need to pass a general collection of parameters. It can be used in scenarios where the provider part needs to dynamically change its user interface based on initialization arguments passed by the consumer part. These initialization arguments can also specify which parameters are required from the provider.

The IParametersInProvider can only be connected to the IParametersInConsumer interface. Connecting the IParametersInProvider interface to the IParametersInConsumer interface is a direct connection, so no transformer dialog is displayed. To use the passed values appropriately, the consuming part may need to be designed with an understanding of the data being sent by the provider.

The following code example shows a simple server-side IParametersInProvider Web Part. It can be connected to other Web Parts which implement the IParametersInConsumer interface on the server. This example dynamically displays a series of text boxes based on the initialization arguments provided by the consumer Web Part. It also creates validation controls for the required parameters. When it is connected to the IParametersInConsumer sample Web Part, text boxes for font size, color, weight, and family are displayed in the provider part. When the form is submitted, this Web Part passes the parameters to the other connected Web Part if all of the required fields have been entered.

There are 8 steps specific to making this a connectable Web Part. These steps are numbered and commented in the following sample code.

// Common .NET required namespaces
using System;
using System.ComponentModel;
using System.Web.UI;

// WebPart required namespaces
using Microsoft.SharePoint.WebPartPages;
using System.Xml.Serialization;
using System.Web.UI.WebControls;

// Namespace required for ArrayLists
using System.Collections;

// Code Access Security namespaces
using System.Security;
using Microsoft.SharePoint.Utilities;

// Step #1: Reference the Communication namespace.
using Microsoft.SharePoint.WebPartPages.Communication;


namespace ConnectionCodeSamples
{
    // Step #2: Inherit from the WebPart base class and implement the 
    // IParametersInProvider interface.
    public class ServerSideParametersInProvider : WebPart, IParametersInProvider
    {    
        // Step #3: Declare the IParametersInProvider Events
        // Because this class implements the IParametersInProvider 
        // interface, it must 
        // declare the interface members ParametersInReady and 
        // NoParametersIn.  
 
        public event ParametersInReadyEventHandler ParametersInReady;
        public event NoParametersInEventHandler NoParametersIn;    

        // Declare variable for keeping track of the connection state.
        private bool _connected = false;
        private string _connectedWebPartTitle = string.Empty;
        private string _registrationErrorMsg = "An error has occurred trying to register your connection interfaces.";
        private bool _registrationErrorOccurred = false;
        private string _notConnectedMsg = "NOT CONNECTED. To use this Web Part connect it to a ParametersIn Consumer Web Part.";

        // Declare variables for Web Part user interface.
        private string _connectedWebPartLabel = "Connected to Web Part";    
        private Button _parametersReadyButton;
        private bool _parametersReadyButtonClicked = false;
        private Button _noParametersInButton;
        private bool _noParametersInButtonClicked = false;
        private TextBox[] _fontAttributeTextBox;
        private string _fieldListKey = "ProviderFieldList"; //Key for ViewState StateBag
        private string _requiredFieldsKey = "RequiredFields";  //Key for ViewState StateBag
        private string _requiredFieldText = "Required Field";
        private string _requiredInputNotice = "*Required input";

        // Declare variables for Text Box information.
        private string[] _fieldList;
        private string[] _fieldDisplayList;
        private bool[] _requiredFieldFlag;

        // Step #4: Override the EnsureInterfaces method and call 
        // RegisterInterface method.
        // The EnsureInterfaces method is called by the Web Part 
        // infrastructure during the ASP.NET PreRender event 
        // and allows the part to register all of its connection 
        // interfaces.

        public override void EnsureInterfaces()
        {
            // If your Web Part is installed in the bin directory and 
            // the Code Access Security (CAS) setting doesn't 
            // allow Web Part Connections, an exception will be thrown. 
            // To allow your Web Part to behave 
            // well and continue working, a try/catch block should be 
            // used when attempting to register interfaces.
            // Web Part Connections will only work if the level 
            // attribute of the <trust> tag in the 
            // web.config file is set to WSS_Minimal, WSS_Medium, or 
            // Full. By default a new SharePoint site
            // is installed with the trust level set to WSS_Minimal.  
            try
            {
                // Register the IParametersInProvider interface.
                // <param name="interfaceName">Friendly name of the 
                // interface that is being implemented.</param>
                // <param name="interfaceType">Specifies which 
                // interface is being implemented.</param>
                // <param name="maxConnections">Defines how many times 
                // this interface can be connected.</param>
                // <param name="runAtOptions">Determines where the 
                // interface can run.</param>
                // <param name="interfaceObject">Reference to the 
                // object that is implementing this interface.</param>
                // <param name="interfaceClientReference">Name used to 
                // reference the interface on the client.  
                // This is a server side example so the value is set to 
                // empty string.</param>
                // <param name="menuLabel">Label for the interface 
                // which appears in the UI</param>
                // <param name="description">Description of the 
                // interface which appears in the UI</param>
                // <param name="allowCrossPageConnection">Specifies if 
                // the interface can connect to a Web Part
                // on a different page.  This is an optional parameter 
                // with a default of false. Note that only some 
                // server side interfaces are allowed to go cross page 
                // by the Web Part Infrastructure. 
                // The IParametersInProvider interface is allowed to go 
                // cross page.</param>
                RegisterInterface("MyParametersInProviderInterface",        //InterfaceName    
                    InterfaceTypes.IParametersInProvider,                   //InterfaceType
                    WebPart.LimitOneConnection,                             //MaxConnections
                    ConnectionRunAt.Server,                                 //RunAtOptions
                    this,                                                   //InterfaceObject
                    "",                                                     //InterfaceClientReference
                    "Provide Parameters To",                                //MenuLabel
                    "Provides a font parameters to a consumer Web Part.",   //Description
                    true);                                                  //allowCrossPageConnection
            }
            catch(SecurityException se)
            {
                _registrationErrorOccurred = true;
            }
        }


        // Step #5: Override the CanRunAt method.
        // The CanRunAt method is called by the Web Part infrastructure
        // during the ASP.NET PreRender event
        // to determine where the Web Part can run based on its current 
        // configuration.

        public override ConnectionRunAt CanRunAt()
        {
            //This Web Part can run on the server
            return ConnectionRunAt.Server;
        }

        // Step #6: Override the PartCommunicationConnect method.
        // The PartCommunicationConnect method is called by the Web 
        // Part infrastructure to notify the Web Part that it
        // is connected during the ASP.NET PreRender event. Relevant 
        // information is passed to the part such as 
        // the interface it is connected over, the Web Part it is being 
        // connected to, and where the part will be running, 
        // either client or server side. 
        // <param name="interfaceName">Friendly name of the interface 
        // that is being connected</param>
        // <param name="connectedPart">Reference to the other Web Part 
        // that is being connected to</param>
        // <param name="connectedInterfaceName">Friendly name of the 
        // interface on the other Web Part</param>
        // <param name="runAt">Where the interface should 
        // execute</param>

        public override void PartCommunicationConnect(
            string interfaceName,
            WebPart connectedPart,
            string connectedInterfaceName,
            ConnectionRunAt runAt)
        {
            //Keep track of whether connected or not
            if (interfaceName == "MyParametersInProviderInterface")
            {
                //Keep track of the Connection
                _connected = true;
                _connectedWebPartTitle = SPEncode.HtmlEncode(connectedPart.Title);
            }
        }
        // Step #7: Implement the PartCommunicationMain() method.
        // The PartCommunicationMain method is called by the Web Part 
        // infrastructure on the client during the ASP.NET PreRender
        // event to allow the part to pass its primary data to the 
        // other connected parts.
        // It is important to always fire either the ParametersInReady 
        // or the NoParametersIn event. Some parts
        // may not behave properly if they are left waiting for this 
        // information.
        // ParametersInReady should be fired to send the parameters.
        // NoParametersIn should be fired to indicate that there is no 
        // change in the parameters.
        public override void PartCommunicationMain()
        {
            // Ensure that all of the Web Part's controls are created.
            EnsureChildControls();

            //Check if connected
            if(_connected)
            {
                // If there is a listener, fire the ParametersInReady 
                // event.
                if(ParametersInReady != null)
                {
                    // Create the ParametersInReadyEventArgs object for 
                    // the ParametersInReady event.
                    ParametersInReadyEventArgs parametersInReadyEventArgs = new ParametersInReadyEventArgs();

                    if(_parametersReadyButtonClicked) //ParametersInReady Button was clicked
                    {
                        // If there is a listener, fire the ParametersInReady event.
                        if(ParametersInReady != null)
                        {
                            // Set the parameter values to the text
                            // box values.
                            if (_fieldList != null)
                            {
                                parametersInReadyEventArgs.ParameterValues = new string[_fieldList.Length];

                                for (int index = 0; index < _fieldList.Length; index++)
                                {
                                    parametersInReadyEventArgs.ParameterValues[index] = _fontAttributeTextBox[index].Text;
                                }

                                // Fire the ParametersInReady event.
                                ParametersInReady(this, parametersInReadyEventArgs);
                            }
                            else //_fieldList is null
                            {
                                // If there is a listener, fire the NoParametersIn event.
                                if(NoParametersIn != null)
                                {
                                    // Fire the event.
                                    NoParametersIn(this, new EventArgs());
                                }
                            }
                            _parametersReadyButtonClicked = false;
                        }
                    }
                    else if(_noParametersInButtonClicked) //NoParametersIn Button was clicked
                    {
                        // If there is a listener, fire the NoParametersIn event.
                        if(NoParametersIn != null)
                        {
                            // Fire the NoParametersIn event.
                            NoParametersIn(this, new EventArgs());

                            _noParametersInButtonClicked = false;
                        }
                    }
                }
            }
        }

        // Step #8: Implement the ParametersInConsumerInit event 
        // handler.
        // The connected consumer part will call this method during its 
        // PartCommunicationInit phase
        // to pass initialization information to the provider Web Part. 
        // The parameters names from the
        // consumer Web Part are passed in. In this example, these 
        // values are used to dynamically 
        // generate the input text boxes in the provider Web Part.
        // <param name="sender">Consumer Web Part</param>
        // <param name="parametersInConsumerInitEventArgs">The args passed by the Consumer</param>

        public void ParametersInConsumerInit(object sender, ParametersInConsumerInitEventArgs parametersInConsumerInitEventArgs)
        {
            // Initialize field lists.
            ParameterInProperty[] paramProps = parametersInConsumerInitEventArgs.ParameterInProperties;

            if (paramProps != null)
            {
                _fieldList = new string[paramProps.Length];
                _fieldDisplayList = new string[paramProps.Length];
                _requiredFieldFlag = new bool[paramProps.Length];

                // Populate field lists.
                for (int index = 0; index < paramProps.Length; index++)
                {
                    _fieldList[index] = paramProps[index].ParameterName;
                    _fieldDisplayList[index] = paramProps[index].ParameterDisplayName;
                    _requiredFieldFlag[index] = paramProps[index].Required;
                }
            }
        }
        
        protected override void RenderWebPart(HtmlTextWriter output)
        {
            // Check for connection interface registration error.
            if (_registrationErrorOccurred)
            {
                output.Write(_registrationErrorMsg);
                return;
            }

            // Check if connected.
            if(_connected)
            {
                // Line break.
                output.RenderBeginTag(HtmlTextWriterTag.Br);
                output.RenderEndTag();

                // Generate input text boxes.
                string fieldName;
                output.RenderBeginTag(HtmlTextWriterTag.Table);
                int vIndex = 0;    //Validation control index
                for (int index = 0; index < _fieldDisplayList.Length; index++)
                {
                    fieldName = _fieldDisplayList[index];
                    
                    output.RenderBeginTag(HtmlTextWriterTag.Tr);
                    output.RenderBeginTag(HtmlTextWriterTag.Td);
                    output.RenderBeginTag(HtmlTextWriterTag.B);

                    // Insert asterisk for required fields.
                    if (_requiredFieldFlag[index])
                        output.Write("<font color=red>*</font>");
                    else
                        output.Write("&nbsp;&nbsp;");
                        output.Write(fieldName + ": ");
                        output.RenderEndTag(); //End </B>
                        output.RenderEndTag(); //End </TD>

                        output.RenderBeginTag(HtmlTextWriterTag.Td);
                        _fontAttributeTextBox[index].RenderControl(output); // Render the text box.

                    output.RenderEndTag(); //End </TD>
                    output.RenderEndTag(); //End </TR>
                }
                output.RenderEndTag(); //End <Table>
                
                // Render buttons.
                _parametersReadyButton.RenderControl(output);
                _noParametersInButton.RenderControl(output);

                // Line break.
                output.RenderBeginTag(HtmlTextWriterTag.Br);
                output.RenderEndTag();

                // Render connected Web Part title.
                output.Write(_connectedWebPartLabel + ": ");
                output.RenderBeginTag(HtmlTextWriterTag.I);
                output.Write(_connectedWebPartTitle);
                output.RenderEndTag();

                // Required footnote.
                output.Write("<br><font color=red>" + _requiredInputNotice + "</font>");

            }
            else
            {
                // The Web Part isn't connected.
                output.Write(_notConnectedMsg);
            }

        }

        // Create Web Part user interface controls.
        protected override void CreateChildControls()
        {
            // Create the ParametersInReady button.
            _parametersReadyButton = new Button();
            _parametersReadyButton.ID = "ParametersInReadyButton";
            _parametersReadyButton.Text = "Fire ParametersInReady";
            Controls.Add(_parametersReadyButton);

            // Create the NoParametersIn button.
            _noParametersInButton = new Button();
            _noParametersInButton.ID = "NoParametersInButton";
            _noParametersInButton.Text = "Fire NoParametersIn";
            Controls.Add(_noParametersInButton);

            // Hook up button clicks.
            _parametersReadyButtonClicked = false; // Initialize to false -- user hasn't clicked yet
            _parametersReadyButton.Click += new EventHandler(ParametersInReadyButtonClicked); // listen for Button's click event

            _noParametersInButtonClicked = false; // Initialize to false -- user hasn't clicked yet
            _noParametersInButton.Click += new EventHandler(NoParametersInButtonClicked); // listen for Button's click event

            // Create Input Field text boxes.
            // The field names provided by the consumer Web Part needed to be stored in a StateBag because 
            // the page doesn't have the _fieldList in time after the 
            // first postback to create the text box 
            // controls and restore their viewstate.
            string providerFieldList = (string)ViewState[_fieldListKey];
            string requiredFieldList = (string)ViewState[_requiredFieldsKey];
            int fieldCount;
            if (providerFieldList == null && _fieldList != null)
            {
                // First postback of the page.
                // Generate controls from the field list provided by 
                // the consumer Web Part.
                string[] FieldList = _fieldList;
                bool[] requiredField = _requiredFieldFlag;
                fieldCount = FieldList.Length;
            
                _fontAttributeTextBox = new TextBox[fieldCount];
                int vIndex = 0;  //Validation control index
                for (int index = 0; index < fieldCount; index++)
                {
                    _fontAttributeTextBox[index] = new TextBox();
                    _fontAttributeTextBox[index].ID = FieldList[index];
                    Controls.Add(_fontAttributeTextBox[index]);
                                   
                    // Populate ViewState providerFieldList item to 
                    // keep track of field names.
                    if (index < fieldCount - 1)
                    {
                        ViewState[_fieldListKey] += FieldList[index].ToString() + ";";
                        ViewState[_requiredFieldsKey] += requiredField[index].ToString() + ";";
                    }
                    else
                    {
                        ViewState[_fieldListKey] += FieldList[index].ToString();
                        ViewState[_requiredFieldsKey] += requiredField[index].ToString();
                    }
                }
            }
            else if (providerFieldList != null)
            {
                // On subsequent postback of page, retrieve field names 
                // from StateBag providerFieldList.
                // Need to parse the providerFieldList information to 
                // get the individual fields.
                string[] FieldList = providerFieldList.Split(new Char[] {';'});
                string[] requiredField = requiredFieldList.Split(new Char[] {';'});
                fieldCount = FieldList.Length;

                _fontAttributeTextBox = new TextBox[fieldCount];
                int vIndex = 0;
                for (int index = 0; index < fieldCount; index++)
                {
                    _fontAttributeTextBox[index] = new TextBox();
                    _fontAttributeTextBox[index].ID = FieldList[index];
                    Controls.Add(_fontAttributeTextBox[index]);

                 }
            }
        }

        // The ParametersInReadyButton OnClick event handler.
        // <param name="sender">The Button object</param>
        // <param name="e">The Event Arguments</param>
        private void ParametersInReadyButtonClicked(object sender, EventArgs e)
        {
            _parametersReadyButtonClicked = true; //user clicked button, set to true
        }

        // The NoParametersInButton OnClick event handler.
        // <param name="sender">The Button object</param>
        // <param name="e">The Event Arguments</param>
        private void NoParametersInButtonClicked(object sender, EventArgs e)
        {
           _noParametersInButtonClicked = true; //user clicked button, set to true
        }
    }
}

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.