Wednesday, 27 July 2011

9.SharePoint 2007 Deployment: Module Features

Package Structure

As I mentioned previously in the post SharePoint 2007 Deployment: Creating and Using Features, to build a feature you need to create the following files:
  • The feature manifest file (which must be named feature.xml)
  • One or more element manifest files
The feature manifest file contains the generic information about the feature package, and the element manifest files contain the information about each specific type of element that makes up the feature. Since I already explained all the possible contents of the feature manifest file in the above mentioned post, I will focus this one the element manifest that allows the provisioning of files (modules) in a SharePoint site.
You can then place these two files inside a Solution following the instructions in the post SharePoint 2007 Deployment: Creating Solutions, to provide an easy way to deploy the feature (or upgrade it).

Modules

Modules are collections of files that must be provisioned in a SharePoint web site. This type of feature element can be used to:
  • Add pages to a web site
  • Add web parts to a web site's web part gallery
  • Add web parts to a web part page
  • Add documents to a document library
  • Add style sheets to the a web sites style library
According to the documentation, WSS 3.0 supports provisioning a maximum of 1000 files through module feature elements (whether using a single module element with 1000 files, or 1000 module elements each with a single file).

Allowed Scopes

The scopes to which a feature can be deployed, are dictated by the types of elements included in it. A feature with module elements can be deployed to Site Collection and Web Site scopes, since they represent files that are to be placed in web sites.

Feature Manifest

I will only present a simple feature manifest, since the additional options were presented in the above mentioned post.
<?xml version="1.0" encoding="utf-8" ?>
<Feature
  xmlns="http://schemas.microsoft.com/sharepoint/"
  Title="My Module Feature"
  Id="17E94729-EF3E-4f43-9385-88E1201F91E0"
  Description="This feature adds files to the web site."
  Version="1.0.0.0"
  Scope="Web"
  Hidden="FALSE"
  DefaultResourceFile="core">
    <ElementManifests>
        <ElementManifest Location="Modules.xml" />
        <ElementFile Location="default.aspx" />
        <ElementFile Location="MyMasterPage.master" />
        <ElementFile Location="MyDocument.docx" />
        <ElementFile Location="MyWebPart\MyWebPart.webpart" />
        <ElementFile Location="MyStyles.css" />
    </ElementManifests>
</Feature>
Notes about this feature manifest:
  • The title of the feature is My Module Feature.
  • It will be deployed as a Web Site feature, since it's Scope value is Web.
  • It references a single element manifest file: Modules.xml.
  • It references several element file files. You must reference separately, using these elements, each file you wish to include in the module.

Element Manifest

The element manifest file can have any name you wish (in this example it's called Module.xml), but it's root element must be <Elements>. Inside this root element, you can place any number of feature element descriptions. In this example I will present the use of the <Module> element which is used to deploy Files to SharePoint web sites.
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    
    <!-- Page Module -->
    <Module Name="Pages" Url="" Path="">
        <File Url="default.aspx" 
              NavBarHome="True" 
              IgnoreIfAlreadyExists="TRUE" 
              Type="Ghostable">

            <!-- Places Web Part on Page -->
            <AllUsersWebPart WebPartZoneID="Left" WebPartOrder="1">
                <![CDATA[
                  <webParts>
                    <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
                      <metaData>
                        <type name="MyWebPart, 
                                    MyWebPart.MyWebPart, 
                                    Version=1.0.0.0, 
                                    Culture=neutral, 
                                    PublicKeyToken=1255988569cf0248" />
                        <importErrorMessage>
                            Cannot import My Web Part.
                        </importErrorMessage>
                      </metaData>
                      <data>
                        <properties>
                          <property name="Title" type="string">
                            My Web Part
                          </property>
                        </properties>
                      </data>
                    </webPart>
                  </webParts>
                ]]>
            </AllUsersWebPart>
            
            <!-- Places a List View for a Discussion Board -->
            <View List="Lists/Discussions" 
                  BaseViewID="4" 
                  Name="Discussions" 
                  WebPartZoneID="Left" 
                  WebPartOrder="2"/>

            <!-- Places a List View for a Document Library -->
            <View List="MyDocuments" 
                  BaseViewID="10" 
                  Name="My Documents" 
                  WebPartZoneID="Left" 
                  WebPartOrder="3"/>

            <!-- Customizes Navigation -->
            <NavBarPage Name="$Resources:core,nav_Home;" 
                        ID="1002" 
                        Position="Start" />
        </File>
    </Module>
    
    <!-- Master Page Module -->
    <Module Name="Master Pages" List="116" Url="_catalogs/masterpage">
        <File Url="MyMasterPage.master" Type="GhostableInLibrary" />
    </Module>

    <!-- Document Module -->
    <Module Name="Documents" List="101" Url="MyDocuments">
        <File Url="MyDocument.docx" Type="GhostableInLibrary" />
    </Module>

    <!-- Web Part Module -->
    <Module Name="WebParts" List="113" Url="_catalogs/wp">
        <File Path="MyWebPart\MyWebPart.webpart"
              Url="MyWebPart.webpart"
              Type="GhostableInLibrary" />
    </Module>

    <!-- Style Sheet Module -->
    <Module Name="Stylesheets" List="101" Url="Style Library">
        <File Url="MyStyles.css" Type="GhostableInLibrary" />
    </Module>
</Elements>

The example above provisions five different files in a SharePoint web site:
  • An ASPX web page (web part page) to the root of the web site. This web page contains:
    • A MyWebPart Web Part (on web part zone Left)
    • A List View Web Part that shows a view of a discussion board list
    • A List View Web Part that shows a view of a document library
  • A Master Page to the Master Page Gallery of the web site
  • A document to a Document Library of the web site
  • A web part to the Web Part Gallery of the web site
  • A style sheet to the Style Library of the web site
The Module Element
The <Module> element is used to specify a Module. There can be any number of modules in a single element manifest. Here is a summary of the possible attributes of this element:
  • IncludeFolders - (optional) I could figure out what this attribute is for...
  • List - (optional) Type of list where the files included in this module should be provisioned (check the possible values on my post about List Template Features).
  • Name - (required) Name of the module (file set).
  • Path - (optional) Specifies the physical path of the files, inside the feature folder (C:\Program Files\...\12\TEMPLATE\FEATURES\[feature]). By default, SharePoint assumes the files are in the same folder as the element manifest file. You can also specify the path on each <File> element (see below).
  • RootWebOnly - (optional) Boolean value. If TRUE it specifies that the files in this module will only be provisioned on the root web site of a site collection.
  • SetupPath - (optional) Specifies the physical path to a folder, inside SharePoint's setup folder (C:\Program Files\...\12\TEMPLATE), that contains the files included in the module.
  • Url - (optional) Specifies the virtual path of the folder in which to place the files of the module. This attribute is also used to provision a folder inside a list. If the Path is not specified, the value of this attribute will be used for the physical path also.
The File Element
The <File> element is used to specify a file inside a module. There can be any number of <File> elements inside a <Module> element. See below a list of the possible attributes of this element:
  • IgnoreIfAlreadyExists - (optional) Boolean value. If TRUE it specifies that the file should be provisioned even if it already exists on the destination URL.
  • Name - (optional) Specifies the virtual path for the file.
  • NavBarHome - (optional) Boolean value. If TRUE it specifies that the file will be the destination of the Home link, used in the web site's navigation. This attribute is only used for web pages.
  • Path - (optional) Physical path to the file, inside the feature folder (C:\Program Files\...\12\TEMPLATE\FEATURES\[feature]). This attribute is used if you need to specify a different path for each file inside the module. Otherwise, you can use the Path attribute on the Module element.
  • Type - (optional) Specifies if the file is to be stored in a Document Library (in this case the value should be GhostableInLibrary) or outside of a list (in this case the value should be Ghostable).
  • Url - (required) Specifies the virtual path for the file. If Name is specified, then the value of this attribute is ignored. However, if Path is not specified, the value of this attribute will be used for the physical path.
The AllUsersWebPart Element
The <AllUsersWebPart> element is used when you want to add a generic web part (non-List View web part) to a web part page. It can only be used inside a <File> element that provisions a web part page file. It has only two attributes:
  • WebPartOrder - (required) Specifies the vertical position of the web part inside a web part zone.
  • WebPartZoneID - (required) Specifies the name of the web part zone.
Inside this element, you can place a CDATA element with the web part's XML description, either using the DWP file schema (also called V2) or the WEBPART file schema (also called V3).
The View Element
The <View> element is used when you want to add a List View Web Part to a web part page. It can only be used inside a <File> element that provisions a web part page file. It has a lot of possible attributes, but I will only list the most common:
  • List - (optional) Specifies either the template type of the list (an integer value) or the URL of a list provisioned in the web site (a string value). On most cases, you should use the URL, since there might be two lists of the same type on the web site.
  • BaseViewID - (optional) Specifies the ID of the list view to be used.
  • Name - (optional) Specifies the name of the view.
  • WebPartOrder - (required) Specifies the vertical position of the web part inside a web part zone.
  • WebPartZoneID - (required) Specifies the name of the web part zone.
The NavBarPage Element
The <NavBarPage> element is used to define how the navigation items should be created so that other pages link to this one. It can only be used inside a <File> element that provisions a web page file. It has three attributes:
  • ID - (required) Specifies the ID for the page. This ID will be used by other pages when defining the relative position of the navigation items.
  • Name - (required) Specifies the text that is displayed in the navigation area of other pages that link to this one.
  • Position - (optional) Specifies the position of the navigation item on the navigation area of other pages that link to this one. This attribute can have the following possible values:
    • Start - Add the node to the start of the top navigation area.
    • End - Add the node to the end of the top navigation area.
    • Number between 1001 and 2000 - Add the node after another NavBarPage element whose ID matches the number.
The Property Element
The <Property> element is used only inside the <File> element, to define the value of one or more properties of that file, once it is provisioned. It's mostly used to set properties of web part files or document files. It has only two attributes:
  • Name - (required) Name of the property to be set.
  • Value - (required) Value to set the property with.

Additional Notes

The files included in a module feature element are provisioned in the web site where the feature is activated. However, when the feature is deactivated, the files that belong to the module element are not removed.
You can learn a lot about modules by looking inside the onet.xml files included in each site template (look in C:\Program Files\...\12\TEMPLATE\SiteTemplates). These files include a <Modules> element which shares the same schema as the Module Features.
Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)