[The documentation needs some work in terms of formatting and images.. will get to it when I have time] 

Month Filter Web Part


Overview

The Month Filter Web Part is a web part designed for SharePoint 2010. In short, the web part is a date selection filter that serves as a connection provider for other web parts on a SharePoint page. Figure 1 shows how the web part appears on a SharePoint web part page, while Figure 2 shows the web part with its dropdown list expanded.

The web part lists a series of descending months which dynamically update in relation to the current date. This is accomplished by configuring the web part properties to automatically increment at preset offset values. For example, the starting month (i.e first month in the list) can be configured to always start with a month that is one month greater than the current month. The default (i.e. date first shown in the text area of the dropdown list) may be set in the same way using a DefaultOffset property. As time passes, the list of available dates will advance in coordination so that the dates shown are always ‘up to date’. The total number of months shown in the list may also be changed; the default is twelve months.

The web part serves as a filter by being a connection provider to other web parts on a SharePoint web part page. The control provides a dropdown list of dates from which a user may make a date selection. After a selection has been made, the page peforms a postback to refresh the content of the page. Web parts that are connected to the Month Filter Web Part will consume the selected date for their specific purposes. The connection type is compatible with the SharePoint Server Reporting Server (SSRS) 2008 Report Viewer web part and any other web parts that can accept connections based on the ITransformableFilterValues interface.

 

The web part may be edited to affect nearly every aspect of its appearance. First, the label shown with the text “Select a date:” may be modified, the date format displayed in the dropdown list may be changed, and the styles (i.e. inline css styles) may be modified for the container, the label text and the dropdown list.

In addition to setting the default date shown using the configured offset value, the default date may also be set using a QueryString parameter. When the page initially loads it will check the QueryString for a predefined parameter name and set the date initially displayed in the dropdown list to the date value.

 


Deployment

When the solution is compiled it results in a .wsp file in the bin folder (either debug or release depending). The .wsp file is a solution file that is used to deploy the solution into a SharePoint web farm. The web part may not be compiled as a sandboxed solution because it acts as a connection provider.  

The solution contains one SharePoint feature which when activated on a site collection will install the Month Filter Web Part to the site collection. The web part is scoped as “site” which means that its scoped at the site collection level. Once activated on a site collection, the web part may be added to web part pages on the root site as well as any sub-sites within the site collection.

Here is the solution manifest file:

<Solution xmlns="http://schemas.microsoft.com/sharepoint/" SolutionId="2f92bca3-223e-48f0-b69d-3d4db23f24ce" SharePointProductVersion="14.0">
<Assemblies> 
   <Assembly Location="MonthFilterWebPart2010.dll" DeploymentTarget="GlobalAssemblyCache">
     <SafeControls> 
       <SafeControl Assembly="MonthFilterWebPart2010, Version=1.0.0.0, Culture=neutral, PublicKeyToken=82aa8b0a0dd8962c" Namespace="CSI" TypeName="*" />
     </SafeControls>
   </Assembly>
</Assemblies>
<FeatureManifests>
   <FeatureManifest Location="MonthFilterWebPart2010_MonthFilter\Feature.xml" />
</FeatureManifests>
</Solution> 

 

The web part compiles into a dll that will be registered in the GAC on the SharePoint server, for that reason the web part must also be registered as a safe control as seen above.

As stated, the solution contains one feature. Below is the feature manifest file. As you will see, the feature is scoped as “Site” which means it is scoped at the Site Collection level.

 

<Feature xmlns="http://schemas.microsoft.com/sharepoint/" Id="14140ba9-1998-4a5a-99e4-47be7e2dcd39" Scope="Site" Title="MonthFilterWebPart2010 Feature1">
<ElementManifests>
   <ElementManifest Location="MonthFilter\Elements.xml" />
   <ElementFile Location="MonthFilter\MonthFilter.webpart" />
</ElementManifests>
</Feature>

 

Note: If the version is incremented and the solution is then redeployed, the web part must be manually removed the the Web Parts Collection prior to activating the new solution. Failing to do so will prevent the new web part from installing into the Web Parts collection.
 


Code Overview

The web part was developed using Microsoft Visual Studio 2010 (Version 10.0.40219.1 SP1Rel) targeting the Microsoft .NET Framework 4 (Version 4.0.30319 SP1Rel) and using the C# language.

The web part is primarily comprised of two classes that provide the custom logic for the web part. The first class, MonthFilterWebPart is what makes up the actual web part. A UML class diagram is shown in Figure 1. The web part is a non-visual web part meaning it renders its elements from code rather than from a view such as an ASP.NET control.

The MonthFilterWebPart inherits from the base class System.Web.UI.WebControls.WebParts.WebPart rather than the SharePoint web part base class which is the recommended approach. To allow the web part to serve as a connection provider, it also inherits from the Microsoft.SharePoint.WebPartPages.ITransformableFilterValues interface. This interface allows a connection to other web parts on the page such as the SSRS 2008 Report Viewer web part.

MonthFilterEditor is the second custom class whose purpose is to provide a property panel when the web part is put into edit mode. Both classes use the CSI namespace which is consistent with all code in the solution. The MonthFilterEditor UML class diagram is show in Figure 2.

 


 

How it Works

The web part follows a specific lifecycle as do all web parts. The following illuminates the logic that happens as the web part is rendered through all phases of its lifecycle in the order in which they occur.

Constructor

The default constructor handles assigning default values to the underlying properties within the web part. Each private variable is assigned to a constant which holds the default values. These values may later be replaced with new values as the web part renders based on viewstate and property values saved by the SharePoint system.

OnLoad

The OnLoad event handler is the first method where custom logic overrides a base method of the WebPart class. Note that this method is called first when the page initially loads, however, the CreateChildControls method is the first one called on subsequent page postbacks.

The logic here is primarly intended to set the default selected date for the page. This happens within OnLoad so that if there are any web part connection consumers, they may access the selected date value which would occur prior to the actual loading of the child controls (such as the actual dropdown list).

During OnLoad, the logic determines if this is the first time the page has loaded. If this is the initial load, it attempts to set the default date value by first checking if there is a parameter in the URL QueryString which specified a default value. If a date parameter is found in the QueryString, the code will attempt to parse the parameter value into a DateTime variable and then use that value as the initial (default) value shown in the dropdown list.

There are several properties that are used when attempting to calculate the default date from the QueryString parameter:

UrlParameterName: Is the name of the parameter in the QueryString that represents the default date value. The parameter name may be edited through the web part edit panel. The default parameter name is “date”.

UrlDateFormat: Is the date format expected in the value position of the QueryString parameter. The format uses standard .Net date formatting options. The default is “MMM yyyy” which equates to a three character month and a four digit year (e.g. MAY 2011).

The system will attempt to do an exact parse on the parameter value using the UrlDateFormat provided. If this fails to result in a valid datetime variable, it will then attempt a general parse. Its important to know that the general parse may result in an unwanted date. For example, should a date value of MAR 10 be provided, a general parse would result in 3/10/n with n being the current year. This would be incorrect if the intention was to set the default to 3/1/10.

If a date parameter is not found in the QueryString, the default value will be set using the offset properties as configured through the web part edit panel. The following properties are used when attempting to calculate the default date using offset values:

DefaultOffset: The default date may be calculated using an offset value in relation to the current date. As an example, if an offset value of one is provided, the default would be calculated by taking the current date and adding one month to that. An offset value of zero would use the current month, while a negative offset value would resolve to a month in the past.

The default offset value is -1 which means that the default month shown will always revert to the previous month.

AdvanceDays: The default month can be advanced to the next month (early) after the given number of days within the current month have expired. The default is 31 so advancing would occur normally in this case. Setting a value of 20 days would mean that after the 20th day of the month, the default month would advance ahead one month early ahead of when it would normally advance at the end of the current month.

When the page is a postback, the dropdown list will have already been created because in that scenario the CreateChildControls method is called first and the selected date is populated using data from the page’s viewstate. In this case, the default date is set to the selected value in the list.

 

Connection Provider

The web part is designed to serve as a connection provider. This means that other web parts on the page may act as a conection consumer and use the date value offered by this web part for various purposes, such as setting a parameter value or using the value as a filter.

The web part, MonthFilterWebPart.cs, inherits from the Microsoft.SharePoint.WebPartPages.ITransformableFilterValues interface. This particular interface is what allows the web part to function as a web part connection provider. The value offered through a connection is the date selected in the dropdown list.

Note that in the case of the initial page load, the connection data is being queried prior to CreateChildControls, so the dropdown list hasn’t been created at this time. This further describes the reasoning behind setting the date value that will be offered through a connection in the OnLoad method of the class rather than waiting on CreateChildControls to set the initial date value.

The following properties make up the ITransformableFilterValues interface, or play a role in providing connection information.

ParameterName: (ITransformableFilterValues interface ) When a web part connection is made either from or to this web part, the web part name is used when identifying the connection field. The value used here is “Date”.

ParameterValues: (ITransformableFilterValues interface) This is the property through which the data connection data is provided. Although the return type is a ReadOnlyCollection, only the first index within the collection will be populated with a single date value.

AllowAllValue: (ITransformableFilterValues interface ) The web part sets this property to True to mean that all values are allowed as connection data.

AllowEmptyValue: (ITransformableFilterValues interface ) The web part sets this property to False to mean that empty values are not allowed as connection data.

AllowMultipleValues: (ITransformableFilterValues interface) The web part sets this property to False to mean that only a single value is offered as connection data. This property is necessary because the interface provides a return type of ReadOnlyCollection when offering connection data through the ParamterValues property. This property enforces the return to one value despite the possibility of returning multiple values per the return type.

ConnectionProviderDateFormat: Specifies the format that should be used when the date value is provided through the date connection format. Uses the same date format settings used by .Net. For example, MMM-dd-yyyy. The default format used by this web part is MMM yyyy.

The connection provider data format may be edited through the web part edit panel.

 

CreateChildControls    

When the page loads initially, this method will follow the OnLoad event. When doing a postback, this method will be called prior to the OnLoad event.

This method will create child controls for the web part and add them to the web part's control collection prior to actually rendering the web part. Here we create a DIV element which acts as a container control. The DIV element holds a SPAN element, commonly referred to as Label Text. It also holds the dropdown list which allows a user to make a date selection. Below is much simplified markup of how these elements fit together:

 

<div id="[guid]_monthFilter_div" class="monthFilter_div">
  <span id="[guid]_monthFilter_span" class="monthFilter_span">
    Select a date:
  </span>
  <select
    name="[guid]$monthFilter_select"
    id="[guid]_monthFilter_select"
    class="monthFilter_select" style="">
      ..<options/>..
  </select>
</div>

 

Note that each control is assigned both an ID and a matching class name. The class names do not map to a specific style, however, they do provide an opportunity for additional styling if needed. In addition, the web part provides three properties that are used to further affect the style of the three main elements that make up the UI. The styles for these controls are not assigned until the render methods that follow. This is necessary because of the timing of events in relation to changes made through the web part edit panel.

When the page is initially loading, the LoadListBox will be called to set the date values within the dropdown list. On subsequent postbacks, the contents of the control will be loaded through viewstate and the call to LoadListBox will not be necessary.

 

LoadListBox

This method populates the date values that go into the dropdown list. This method is only called during the intial load of the page because it will be populated through viewstate for subsequent postbacks.

The dates that are loaded are dynamic based on the current date in relation to the StartOffset property. The following properties are used in loading of the dropdown list.

StartOffset: This public, shared property on the web part allows the start offset to be updateable through the web part editor. The start offset calculates the first month listed in the dropdown in relation to the current month. This value may be a positive value to start in the future, zero to start with the current month, or negative to start with a month in the past.

The offset month is not necessarily the default month shown in the dropdown. The default month is controlled by the DefaultOffset property instead.

NumberOfMonthsToDisplay: Indicates how many date entries should be shown in the dropdown list. The default value is 12 which means the list would show the past twelve months beginning with the date defined by the StartOffset property. In the code, this is done using a loop that decreases the month number by one for each iteration.

DisplayDateFormat: Specifies the format that should be used when displaying the data values in the dropdown list. Uses the same date format settings used by .Net. For example, MMM-dd-yyyy. The default format used by this web part is MMM yyyy.

AdvanceDays: The start month can be advanced to the next month (early) after the given number of days within the current month have expired. The default is 31 so advancing would occur normally in this case. Setting a value of 20 days would mean that after the 20th day of the month, the start month would advance ahead one month - early ahead of when it would normally advance at the end of the current month.

When date values are added to the dropdown list, the day of the month is always set to one, thus assuming the first day of the month regardless of the true current date. Also, the value used when adding to the list is the date value formatted to a ShortDateString format. This means that despite the formatting used for display, a full date is stored in the value property of the list item.

 

Click Postback Events (_list_SelectedIndexChanged)

This method is called on postback after a user makes a date selection from the dropdown list. Click postback events are only called on postback due to an action by the user so this method is not called when the page is initially loaded.

Within this method, we set the _selectedValue variable so that it may be used to set the UI as well as provide the selected value to any webpart connections. This merely acts as in insurance policy as the _selectedValue should already have been correctly set in the OnLoad method which occurs in advance of this method.

 

OnPreRender

Several UI based (cosmetic) properties of the web part are not applied until the OnPreRender method. Child controls are created and added to the web part in the CreateChildControls method. Styling those controls is not done until now because of the timing in relation to when changes are applied after making updates in the web part edit panel.

A SPAN element is used as a label preceeding the dropdown list of dates. By default, the label will read, “Select a date:”. The following property may be used to modify the text that is displayed.

LabelText: Represents the text that will preceed the dropdown list of dates. The default value is “Select a date:”. The value may be changed through the web part edit panel. When the label is rendered, it will automatically insert a space after the last character if one is not manually provided by the user.

There are three style properties that may be used to modify the appearance of the elements within the web part. These are DivStyle, SpanStyle and ListStyle. Styles are applied directly to the elements through code using the following convention, [element].Style.Value = “[style string]”. The style therefore can be any inline style chained together with semicolons.

The styles are applied to the main elements that make up the web part user interface. Here is a diagram that helps identify the elements and their corresponding style properties.

The style properties are further defined below:

DivStyle: The style applied to the div container that holds the UI controls for this web part. The default style is “padding:5px 3px 0px;font-weight:bold;” which attempts to match the style used by out-of-the-box SharePoint 2007 filter web parts.

SpanStyle: The style applied to the span label text UI control for this web part.

ListStyle: The style applied to the list UI controls for this web part.

 

RenderControl

Overridden to give the control an opportunity to trap and report rendering errors on the UI. In addition, version information is printed to the UI when the web part is in edit mode. The following code snippet shows how the web part version information is added to the web page.

 


Custom Web Part Editor

 The web part uses a custom web part editor (see the MonthFilterEditor section) for configuring some of the properties found on the web part. The following properties make use of the custom web part editor. These properties are shown in Figure 3 in the Filter Settings section.

Label Text

Display Date Format

Connection Provider Date Format

Start Offset

Default Offset

Number of Months Shown

The use of a custom web part editor is not needed merely based on the complexity of the property types nor the need for an intricate update panel. It is rather the desire to place the most common filter properties at the top of the edit panel rather than having them embedded in a collapsible region below. The use of a custom editor allows us to place the properties at the top, outside of the collapsible regions of the editor panel. The properties chosen for prime placement are those that are more commonly used by the average user when configuring the web part.

To implement the custom web part editor, the web part class inherits from the IWebEditable interface. This interface overrides the CreateEditorParts() method which takes the opportunity to add the custom editor the the editors collection for the web part. Below shows the code used in this case. Its important that a unique ID be assigned to the editor as shown below (highlighted with green font).

 

public override EditorPartCollection CreateEditorParts()
{
        //Declarations
        List<EditorPart> editorParts;
        EditorPart editorPart;
        EditorPartCollection baseParts;
 
        //Create base editor part collection which we'll use as a return.
        editorParts = new List<EditorPart>();
        baseParts = base.CreateEditorParts();

        //Add the filter editor.
        editorPart = new MonthFilterEditor();
        editorParts.Add(editorPart);
        editorPart.ID = this.ID + "_monthFilterEditor";

        //Return editor collection.
        return new EditorPartCollection(baseParts, editorParts);
}

 

 

The remaining properties that don’t make use of the custom editor, but rather rely on the default editor instead. These properties are shown as they appear in the editor panel in Figure 3 under the Advanced Filter. The properties are listed here:

Container Style

Label Text Style

List Style

Advance to next month after given number of Days:

Default QueryString Parameter Name

Default QueryString Date Format

 

The remaining properties make use of the default editor by simply assigning the appropriate attributes to each property within the web part class. The following is an example of the attributes put into place for these remaining properties.

 

[Personalizable(PersonalizationScope.Shared),
WebBrowsable(true),
WebDescription("Sets the style used with the div container that holds the UI controls on this web part."),
WebDisplayName("Container Style"),
Category("Advanced Filter"),
DefaultValueAttribute(DIV_STYLE)]

WebDescription is the text displayed as a tooltip when the label is hovered with the mouse. WebDisplayName is the label name used on the editor panel. Category is the collapsible group within which the properties will be positioned on the editor panel.

 

MonthFilterEditor

This class provides a custom web part editor to be used in coordination with the MonthFilterWebPart. The custom editor provides a more customized experience and more robust control set when editing the properties associated with this web part.

The MonthFilterEditor inherits from the EditorPart class which is in the System.Web.UI.WebControls.WebParts namespace. There are three methods that are important to override, they are as follows:

 

CreateChildControls

Child controls are created dynamically and added to the web part editor. These controls result in elements being rendered in the top most portion of the web part editor, outside of any of the categorized, collapsible regions. This can be seen in Figure 3.

          

SyncChanges

This method pulls the values stored behind the public properties of the web part into this web part editor. It populates the visual controls on this web part editor with those values.

 

ApplyChanges

This method is called when the user applies changes or save the changes made through the editor. The values a applied to the web part.

Last edited May 11, 2011 at 12:16 PM by samuelsethhildebr, version 6

Comments

No comments yet.