Web Part Galleries

Web Part galleries serve as a central location for storing and managing Web Parts. Because Web Parts are essential to your site, it is critical that they be managed carefully. Nonfunctioning Web Parts can keep pages from displaying. Poorly written or improperly configured Web Parts can adversely affect site functionality and availability. In addition, Web Parts from unknown third parties may pose the risk of malicious code execution. Carefully consider which Web Parts you will make available and to whom you will make them available.

The default gallery for your site collection is listed in the form of Site Name Gallery. For instance, if your site collection is named Contoso HR, your default gallery is named Contoso HR Gallery. In addition to the default gallery there are two other important galleries:

• Closed Web Parts This gallery displays the Web Parts that remain on the page, but are not visible because they have been closed. The closed Web Parts remain on their Web Part pages and are available to be opened at any time. However, they do require additional system resources, so it is wise to remove unneeded closed Web Parts.

• Server The Server gallery makes Web Parts available across site collections and is managed using the Stsadm.exe command. There may also be one or more custom galleries available.

Managing Web Parts

By browsing to Site Actions > Site Settings > Galleries > Web Parts, you can preview Web Parts, add Web Parts to the gallery, import and export Web Parts, and edit properties of Web Parts. Figure 5-11 shows where to manage your Web Parts.

Figure 5-11: To manage your Web Parts, browse to the list's Settings > Gallery Settings.

Previewing a Web Part

Many Web Parts allow you to preview how they appear on the page by clicking on the Web Part's name. Selecting the edit icon allows you to view the Web Part's properties.

New

New allows you to add a Web Part that has been deployed on the site collection to the Web Part gallery. Select the Web Part or Parts you wish to add to the gallery and click Populate Gallery. When Web Parts are added using Stsadm.exe, they must be added to the gallery using New.

Editing Web Parts

By clicking on a Web Part's Edit icon, you can preview, delete, export, view the XML code of the Web Part, and manage the properties of the Web Part.

Deleting a Web Part

To remove a Web Part from the gallery, click Delete Item. A default Web Part that is deleted from the gallery can be replaced by using New in the Web Part gallery.

Exporting a Web Part

Every Web Part has at least two resource files: a Web Part description file (.wpd or .webpart) and a Web Part assembly file (.dll). Web Part assembly files contain the logic that makes the Web Part work. Web Part description files are simply XML descriptions of the Web Part; they contain the default and personalized properties for a given Web Part. Therefore, they are small and can be e-mailed, which makes their distribution simple.

Clicking Export allows you to save Web Part description files only. For Web Parts that are included with SharePoint Products and Technologies, the description is all that is needed. For Web Parts from third parties, you must install the appropriate .dll file, as well as import the description file. To export a file, click Export and specify where the file should be saved using a meaningful file name.

Caution 

Many Web Parts require Web Part resource files, in addition to description and assembly files, for them to function properly. Also, some Web Parts reference more than one Web Part assembly file and therefore require all of the assemblies they reference to function.

Viewing a Web Part's XML

The Web Part's XML description file contains the Web Part's properties and references to all of the assemblies on which the Web Part is dependent. Blank properties indicate that the Web Part uses the default. The <assembly> property references the Web Part assembly file for the particular Web Part file.

Managing Web Part Permissions

Web Part permissions are handled in the same manner as permissions for any list or list items, which are covered in Chapter 4, "Creating Site Collections." To set permissions for an individual Web Part, click on its Edit icon. By default the Web Part gallery inherits permissions from the Site Settings > Advanced Permissions. If the Web Part gallery is still inheriting permissions and you select Manage Permissions of Parent you will be directly altering the Advanced Permissions. If the Web Part gallery has its own unique permissions, you will be altering the Web Part galleries permissions. Take care to ensure that you alter only the desired set of permissions. To manage gallery-level permissions, browse to Settings > Gallery Setting > Permissions And Management > Permissions for this gallery, as shown in Figure 5-12.

Figure 5-12: Select the object to manage and choose Remove, Edit, or Inherit from the Actions menu.

Importing Web Parts

To import a Web Part, select Upload Document from the Upload drop-down list of the Web Part gallery. Enter the path for, or browse to the file that you wish to import. If you wish to overwrite existing files, select the Overwrite Existing Files check box. After clicking OK, the Edit Item page for the Web Part is displayed. You can change the Web Part's File Name, Title, Group, and Quick Add Group values. The Quick Add Group adds the Web Part to a list of recommended Web Parts for a given Web Part zone.

Important 

Only Web Part description files are uploaded to the Web Part gallery. If the Web Part's assembly file isn't already on the server, it must be added to the /bin" target="_top">http(s)://<webapp>/bin directory or the Global Assembly Cache (GAC).

Importing Web Part Assembly Files

All Web Parts require both a Web Part description file (.dwp or .webpart) and an assembly file (.dll). Uploading Web Parts to the Web Part gallery or importing them to a page only retrieves the Web Part description file. The assembly must also be added for the Web Part to function. Web Part assemblies must be added either to the Bin directory of the site collection on which they will be used or to the global assembly cache (GAC). Web Part assemblies located in the Bin directory must be registered as Safe Controls in the Web.config file. Web Part assemblies located in the GAC must be strong-named to function.

Adding Web Parts Using Stsadm.exe

Of the several ways in which to deploy Web Parts, using Stsadm.exe is perhaps the most straightforward. Adding Web Parts with Stsadm.exe has two significant advantages. Because the Web Part deploys from a Cabinet (.cab) file, all of its resources are also deployed. In addition, deployment using Stsadm.exe is a simple two-step process.

The syntax for deploying a Web Part using Stsadm.exe is:

 stsadm.exe -o addwppack -filename <Web Part Package filename> or -name <name of Web Part Package> [-lcid <language>] [-url <url>] [-globalinstall] [-force] [-nodeploy] 

• -filename Specifies the location of the .cab file to be deployed.

• -name If the Web Part package has already been added to a site collection, it can be added to others without using the .cab file. Instead of the filename, use -name and the name of the Web Part package.

  Tip 

  Stsadm -o enumwppacks lists all of the Web Part packages on a server.

• -lcid Specifies the language code identification number.

• -url Is the URL of the site collection to which the Web Part will be added. If you do not specify a URL, the Web Part is added to all Windows SharePoint Services-enabled virtual servers on the computer.

• -globalinstall Installs the Web Part in GAC. Only strong-named assemblies can be installed in the GAC. Assemblies that are not strong-named are added to the Bin directory instead.

• -force Causes already installed Web packages with the same name to be overwritten.

• -nodeploy Prepares the Web Part pack to deploy using the stsadm -o deploywppack command.

Tip 

Web Part Packs can be deployed and retracted according to a schedule using:

 stsadm.exe -o deploywppack -name <Web Part Package name> [-url <virtual server url>] [-time <time to deploy at>] [-immediate][-local] [-lcid <language>] [-globalinstall] [-force] 

and

 stsadm.exe -o retractwppack -name <Web Part Package name> [-url <virtual server url>] [-time <time to retract at>] [-immediate][-local] [-lcid <language>] 

After the Web Part has been added using Stsadm.exe, it still must be added to the Web Part gallery using the New function.

Deleting Web Part Packages Using Stsadm.exe

A Web Part package can be removed from a virtual server using stsadm -o deletewppack, which has the syntax:

 stsadm.exe -o deletewppack -name <name of Web Part Package > [-lcid <language>] [-url <url>] 

• -name Specifies the name of the Web Part pack to be removed.

• -lcid Specifies the language code identification number.

• -url Specifies the virtual server from which the Web Part pack will be removed. If no URL is specified, it will be removed from all Windows SharePoint Services-enabled Virtual Servers on the computer.

After deleting the Web Part pack, you must manually delete its Web Part gallery entry.

Adding Web Part Assembly Files to the Bin

The process for adding a Web Part to the Bin directory is relatively straightforward and has four steps. It is much easier to do than describe and should become second nature with practice.

1. Identify the assembly name in the Web Part description file (.dwp or .webpart).

   Use Notepad to open the Web Part description file of the Web Part that you wish to import. Find the Web Part's assembly tag. Copy the portion between the <Assembly> and </Assembly> tags as shown in Figure 5-13. Keep this copy of Notepad open, because it is needed again in Step 2.

2. Add the assembly name from the Web Part file to the safe controls list in the Web.config file.

   • The Web.config file for the site collection is located in the root directory of the site collection virtual server. Using IIS Manager, find the site collection you wish to add the Web Part to under Web Sites. Right-click on the Web site's name and choose Explore as shown in Figure 5-14.

   • Open the Web.config file with Notepad. Find the <SafeControls> section of the Web.config file. Copy the first <SafeControl> entry. It is easier to adapt a copy than type the entry by hand. Simply highlight and copy, as shown in Figure 5-15.

   • Paste the copy of the <SafeControl> entry at the beginning of the list, and separate it from the list with a carriage return for easy reference, as shown in Figure 5-16.

   • Replace the value of Assembly= "…" in the Web.config file with the value between <Assembly> </Assembly> that was located in Step 1, as shown in Figure 5-17.

   • After updating the <Assembly> tag in the Web.config file, there is still some work to be done. Change the Namespace so that it matches the assembly name.

     Note 

     If you have been given a Namespace for a Web Part other than its assembly name, use it and not the assembly name.

   • Change the TypeName value to TypeName="*". Make sure that Safe has the value Safe="True". If you would like a design package such as SharePoint Designer to be able to modify the Web Part, set AllowRemoteDesigner="True".

   • Finally, check the safe control structure, for a Web Part description that contains the following.

      <Assembly>Contoso, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=fd9ce613b28c7c47</Assembly> 

     You should have a SafeControl entry that looks like:

      <SafeControl Assembly="Contoso, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=fd9ce613b28c7c47" Namespace="Contoso" TypeName="*" Safe="True" AllowRemoteDesigner="True"/> 

3. Place the Web Part's assembly file (.dll) in the Bin directory of the SharePoint collection.

   Using IIS Manager, find the Bin directory of the Site Collection's virtual server. Right-click on the Bin directory and choose Explore. Copy the Web Part assembly file to the Bin directory. As seen in Figure 5-18, verify that you are in the correct virtual server.

4. Add the Web Part to a page or the Web Part gallery

   Import the Web Part description file to a page, or add it to the Web Part gallery just as you would any other Web Part.

Figure 5-13: Copy the assembly tag in the Web Part description file.

Figure 5-14: You can open the Web.config file using IIS manager.

Figure 5-15: Copy the first Safe Control entry in the Web.config file.

Figure 5-16: Paste the copy of the Safe Control into the Web.config file.

Figure 5-17: Replace the underlined text with the highlighted text.

Figure 5-18: Copy the .dll file to the Bin directory using IIS Manager.

Web Part Maintenance View

If a Web Part is placed on a page where it does not work properly, a Web Part Page Maintenance page can be used to remove the problem Web Part. No link to this page is available under normal circumstances. However, when a page fails to load, the Maintenance Page should open automatically, or an error message should contain a link to the maintenance page. The page can also be reached by appending ?contents=1 to the URL of the broken page. For instance, for the URL http://hr.conotso.msft/default.aspx, entering http://hr.conotso.msft/default.aspx?contents=1 causes the Web Part Maintenance Page to be displayed, as seen in Figure 5-19.

Figure 5-19: The Web Part Maintenance page allows you to remove Web Parts from a broken page.

Using the Maintenance page, you can remove problem Web Parts and reset all of the personalizations on the page to shared values. If the problem is only with your personal view, you can select Switch To Personal View.

Tip 

You can deploy custom Web parts and features to the entire farm using Solutions. For more information on deploying Solutions, please visit http://msdn2.microsoft.com/en-us/library/aa544500.aspx.