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

IParametersOutConsumer interface

NOTE: This API is now obsolete.

Implements the IParametersOutProvider interface to communicate its parameter list to a consumer Web Part implementing this interface. These interfaces also allow passing through other information such as a selected row.

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

The IParametersOutConsumer interface should be implemented for Web Parts that need to consume a general collection of parameters. It can be used in scenarios where the consumer part was designed with an understanding of the data being sent by the provider. Also, a Web Part that implements the IParametersOutConsumer interface has the ability to receive initialization arguments from the provider part. The IParametersOutConsumer interface can only connect with the IParametersOutProvider interface. This is a direct connection, so no transformer dialog is displayed when connecting these interfaces. Therefore, the consumer part needs to correctly map the inbound parameters from the provider part.

The IParametersOutConsumer and IParametersOutProvider interfaces also allow passing additional information such as a selected row. For example, when a user clicks on a row in a list, the row data along with the parameters can be passed through these interfaces.

The following code example shows a simple server-side IParametersOutConsumer Web Part. It can be connected to another Web Part which implements the IParametersOutProvider interface on the server. This Web Part displays a paragraph of text. The text style attributes such as font family, color, weight, and size can be set by a Web Part which implements the IParametersOutProvider interface.

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

For an overview of the steps in creating a connectable Web Part, see Creating a Connectable Web Part.

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

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

// 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 
    //IParametersOutConsumer interface.
    public class ServerSideParametersOutConsumer : WebPart, IParametersOutConsumer
    {    
        // Declare variables for keeping track of 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 set the text style of this Web Part connect it to an appropriate Parameters Out Provider Web Part.";

        // Declare variables for Web Part user interface.
        private string _connectedWebPartLabel = "Connected to Web Part";
        private string _webPartDescription;
        string _fontFamily = string.Empty;    
        string _fontColor = string.Empty;        
        string _fontWeight = string.Empty;    
        string _fontSize = string.Empty;        
        ParametersOutProviderInitEventArgs _parametersOutProviderInitEventArgs;
        bool _parametersOutReadyFlag = false;
        bool _noParametersOutFlag = false;

        // Constructor
        public ServerSideParametersOutConsumer()
        {
            // Set Web Part Description
            _webPartDescription = "This is an example of a IParametersOutConsumer Web Part. The following ";
            _webPartDescription += "text style attributes can be set when passed as parameters via a Web Part Connection: ";
            _webPartDescription += "font color, weight, size, and family. This Web Part can only be connected to ";
            _webPartDescription += "another part which implements the IParametersOutProvider interface.";
        }

        // Step #3: 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 IParametersOutConsumer 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 
                // that appears in the UI</param>
                // <param name="description">Description of the 
                // interface that 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 connect across 
                // pages by the Web Part infrastructure. 
                // The IParametersOutConsumer interface is not allowed 
                // to connect across pages.</param>
                RegisterInterface("MyParametersOutConsumerInterface",        //InterfaceName    
                    InterfaceTypes.IParametersOutConsumer,                    //InterfaceType
                    WebPart.LimitOneConnection,                                //MaxConnections
                    ConnectionRunAt.Server,                                    //RunAtOptions
                    this,                                                    //InterfaceObject
                    "",                                                        //InterfaceClientReference
                    "Consume Font Parameters From",                            //MenuLabel
                    "Consumes font parameters from another Web Part.");        //Description
            }
            catch(SecurityException se)
            {
                _registrationErrorOccurred = true;
            }
        }

        
        // Step #4: 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 #5: 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)
        {
            // Check if this is my particular Row interface
            if (interfaceName == "MyParametersOutConsumerInterface")
            {
                //Keep track of the Connection
                _connected = true;
                _connectedWebPartTitle = SPEncode.HtmlEncode(connectedPart.Title);
            }
        }

        
        // Step #6: Implement the ParametersOutProviderInit event 
        // handler.
        // The connected provider part will call this method during its 
        // PartCommunicationInit phase
        // to pass initialization information to the consumer Web Part.
        // <param name="sender">Reference to the Consumer Web 
        // Part</param>
        // <param name="parametersOutProviderInitEventArgs">The args 
        // passed by the provider Web Part</param>
        public void ParametersOutProviderInit(object sender, ParametersOutProviderInitEventArgs parametersOutProviderInitEventArgs)
        {
            // Store the provider part properties.
            _parametersOutProviderInitEventArgs = parametersOutProviderInitEventArgs;
        }

        
        // Step #7: Implement the ParametersOutReady event handler.
        // The connected provider part may call this method during its 
        // PartCommunicationMain phase
        // to pass its primary data to the consumer Web Part.
        // <param name="sender">Provider Web Part</param>
        // <param name="parametersOutReadyEventArgs">The args passed by 
        // the Provider</param>
        public void ParametersOutReady(object sender, ParametersOutReadyEventArgs parametersOutReadyEventArgs)
        {
            _parametersOutReadyFlag = true;

            // Set the text box values to the values of the Parameters.
            if(parametersOutReadyEventArgs.ParameterValues != null)
            {
                _fontFamily = parametersOutReadyEventArgs.ParameterValues[0];
                _fontColor = parametersOutReadyEventArgs.ParameterValues[1];
                _fontWeight = parametersOutReadyEventArgs.ParameterValues[2];
                _fontSize = parametersOutReadyEventArgs.ParameterValues[3];

                // Store font attributes in a State Bag for use by the 
                // NoParametersOut event handler.
                ViewState["FontFamily"] = _fontFamily;
                ViewState["FontColor"] = _fontColor;
                ViewState["FontWeight"] = _fontWeight;
                ViewState["FontSize"] = _fontSize;
            }
        }

        
        // Step #8: Implement the NoParametersOut event handler.
        // The connected provider part may call this method during its 
        // PartCommunicationMain phase
        // to indicate there is no change in the parameter values. This 
        // allows the consumer part to 
        // display its cached data instead of potentially hitting a 
        // database again or recalculating values. 
        // <param name="sender">Provider Web Part</param>
        // <param name="eventArgs">The Event Argumentsr</param>
        public void NoParametersOut(object sender, EventArgs eventArgs)
        {
            _noParametersOutFlag = true;

            // Set font attributes based on cached values.
            _fontFamily = (string)ViewState["FontFamily"];
            _fontColor = (string)ViewState["FontColor"];
            _fontWeight = (string)ViewState["FontWeight"];
            _fontSize = (string)ViewState["FontSize"];
        }

        protected override void RenderWebPart(HtmlTextWriter output)
        {
            // Check for connection interface registration error.
            if (_registrationErrorOccurred)
            {
                output.Write(_registrationErrorMsg);
                return;
            }

            // Set text style attributes.
            output.AddStyleAttribute(HtmlTextWriterStyle.FontFamily, _fontFamily);
            output.AddStyleAttribute(HtmlTextWriterStyle.Color, _fontColor);
            output.AddStyleAttribute(HtmlTextWriterStyle.FontWeight, _fontWeight);
            output.AddStyleAttribute(HtmlTextWriterStyle.FontSize, _fontSize);
            
            // Output Web Part description.
            output.RenderBeginTag(HtmlTextWriterTag.Div);
            output.Write("<br>");
            output.Write(_webPartDescription);
            output.RenderEndTag();

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

            // Check if connected.
            if(_connected)
            {
                // Render font attributes if they have been set.
                if (_fontFamily != null)
                {
                    // Specify source of font attributes.
                    output.RenderBeginTag(HtmlTextWriterTag.B);
                    if (_parametersOutReadyFlag)
                        output.Write("Provided Font Parameters <br>");
                    else if (_noParametersOutFlag)
                        output.Write("<font color=blue>Cached</font> Font Parameters <br>");
                    output.RenderEndTag();

                    // Render parameters send by provider part.
                    if (_parametersOutProviderInitEventArgs.ParameterOutProperties.Length != 0)
                    {
                        ParameterOutProperty[] ParamOutProps = _parametersOutProviderInitEventArgs.ParameterOutProperties;
                        output.Write(ParamOutProps[0].ParameterDisplayName + ": " + _fontFamily + "<br>");
                        output.Write(ParamOutProps[1].ParameterDisplayName + ": " + _fontColor + "<br>");
                        output.Write(ParamOutProps[2].ParameterDisplayName + ": " + _fontWeight + "<br>");
                        output.Write(ParamOutProps[3].ParameterDisplayName + ": " + _fontSize + "<br>");
                    }
                }

                // 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();
                output.Write("<br>");

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


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

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.