SharePoint Tip #19: Using JavaScript in Body OnLoad Event

When developing web parts or other controls that use JavaScript, it's quite common to need to call some function on the Body OnLoad event of the web page. The problem with this is that, in SharePoint, the Body element is in the master page and not in the control, so doing this is can be tricky.

Fortunately, the SharePoint team gave the developers a way to do this easily, using a special array called _spBodyOnLoadFunctionNames. The only thing you have to do is push your function's name to this array and it will get called in the OnLoad event of the window.

Example:

_spBodyOnLoadFunctionNames.push("MyFunction");

function MyFunction() {
    setTimeout('MyFunction()', 1000);
}

SharePoint 2007 Deployment: Creating and Using Features

Summary

This third post is about creating and using Features in a general sense. Creating Features for each specific element will be the subject of later posts. Check the first post SharePoint 2007 Deployment: Overview for an introduction and the series index.

Feature Scopes

A Feature can be activated or deactivated in a specific scope, and there are four different scopes:

  • Farm – The elements will be deployed at the farm level. To activate or deactivate a farm-scoped Feature, go to Central Administration, Operations section, and click on Manage Farm Features in the Global Configuration group.
  • Web Application – The elements will be deployed at the web application level. To activate or deactivate a web application-scoped Feature, go to Central Administration, Application Management section, and click on Manage Web Application Features in the SharePoint Web Application Management group.
  • Site Collection – The elements will be deployed at the site collection level. To activate or deactivate a site collection-scoped Feature, go to the root web site settings, and click on Site Collection Features in the Site Collection Administration group. You must be a site collection administrator to see this setting.
  • Web Site – The elements will be deployed at the web site level. To activate or deactivate a web site-scoped Feature, go to the web site settings, and click on Site Features in the Site Administration group. You must have ManageWeb permissions (for instance, being a site administrator) to see this setting.

Each type of element can be deployed to one or more of these scopes. When describing each element type, I will specify to which scopes they can be deployed to.

Feature Schema

To create a Feature you must create a XML file named feature.xml which contains all the general configurations for the Feature and the references to all the files that describe the Elements contained in the Feature. Below is an example of a feature.xml file that uses all possible attributes, just for demonstration purposes. Required attributes are printed in bold.

<?xml version="1.0" encoding="utf-8" ?>
<
Feature xmlns="http://schemas.microsoft.com/sharepoint/"
    Id="AB30188E-6F5D-4380-89D9-46F5D43E25F7"
    Scope="Site"
    Title="My Feature"
    Description="My Feature includes several elements."
    Version="1.0.0.0"
    Creator="André Vala"
    SolutionId="2530188E-6F5A-433B-89D9-BA98D43E25F7"
    ImageUrl="/_layouts/MyFeature/MyFeatureIcon.jpg"
    ImageUrlAltText="My Feature Icon"
    Hidden="FALSE"
    ActivateOnDefault="FALSE"
    AlwaysForceInstall="FALSE"
    AutoActivateInCentralAdmin="FALSE"
    RequireResources="TRUE"
    DefaultResourceFile="MyResourceFile"
    ReceiverAssembly="MyFeatureReceiver, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=3f5df55c01ba1c99"
    ReceiverClass="MyFeatureReceiver.MyReceiverClass">
    <ActivationDependencies>
        <ActivationDependency FeatureId="C03829C4-0E85-4DCE-90F8-B7E3F008A0C5"/>
    </ActivationDependencies>
    <ElementManifests>
        <ElementManifest Location="MyElement1.xml"/>
        <ElementManifest Location="MyElement2.xml"/>
        <ElementManifest Location="MyElement3.xml"/>
        <ElementFile Location="MyFile1.jpg"/>
        <ElementFile Location="MyFile2.jpg"/>
    </ElementManifests>
    <Properties>
        <Property Key="MyProperty" Value="MyValue" />
    </Properties>
</Feature>

Tip: To make things easier when creating these files in Visual Studio 2005 (or later), you can use the wss.xsd schema file, included with SharePoint (usually in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\XML), to enable Intellisense.

Feature Element

The <Feature> element is the root element of the feature.xml file and it has several possible attributes, although not all of them are required:

  • Id (required): Unique identifier for this feature (GUID).
  • Scope (required): Scope in which the Feature will be activated/deactivated. Can assume the values Farm, WebApplication, Site and Web (as described in the first section of this post). Keep in mind that the elements you want to include in the feature might dictate what will be its scope.
  • Title (optional): Title of the Feature as shown in the Feature list.
  • Description (optional): Description of the Feature as shown in the Feature list, below the Feature title.
  • Version (optional): Version number of the Feature.
  • Creator (optional): Name of the author of the Feature.
  • SolutionId (optional): ID of the Solution that the Feature belongs to.
  • ImageUrl (optional): URL of the image that will be used as icon in the Feature list. If this attribute is not present, SharePoint will use the default Feature icon.
  • ImageUrlAltText (optional): Alternative text used in the Feature icon.
  • Hidden (optional): Specifies if the Feature should be hidden from the Features list. The default value is FALSE.
  • ActivateOnDefault (optional): Specifies if the Feature should be automatically activated after it is installed. This attribute is only used if the Feature scope is Farm or WebApplication, otherwise it is ignored. The default value is TRUE.
  • AlwaysForceInstall (optional): Specifies if the Feature should always be installed, even if it's already installed. The default value is FALSE.
  • AutoActivateInCentralAdmin (optional): Specifies if the Feature should automatically be activated in its scope. This attribute has no meaning for Features of scope Farm. The default value is FALSE.
  • RequireResources (optional): Specifies if SharePoint should look for a culture-specific resource file for this Feature. If there is no resource file for the current culture, the Feature is hidden in the Features list (but can still be activated by object model or console command). The default value is FALSE.
  • DefaultResourceFile (optional): Defines the name of the resources files. By the default all resource files are named Resources.XX-xx.resx (where XX-xx is the culture code), but setting this attribute with the value MyResourceFile will cause SharePoint to look for filenames like MyResourceFile.XX-xx.resx
  • ReceiverAssembly (optional): Full qualified name of the assembly that contains the Custom Feature Event Receiver class. This attribute is always used with the ReceiverClass attribute.
  • ReceiverClass (optional): Name of the class that implements the Custom Feature Event Receiver. This attribute is always used with the ReceiverAssembly attribute.

Activation Dependencies

The <ActivationDependencies> element is optional and is used when you want to create a dependency between two Features. In other words, if a certain Feature A depends on some Element from a Feature B, creating an activation dependency in Feature A ensures that it won't be activated if Feature B is not activated first. This element can contain any number of <ActivationDependency> elements whose only attribute (FeatureId) is the ID of the Feature upon which this Feature is dependent.

Element Manifests

The <ElementManifests> element is also optional although it is used very often since it contains the list of Elements that belong to the Feature. This element can contain two types of child elements:

  • The <ElementManifest> element, which points to a XML file that describes one or more SharePoint Feature Elements.
  • The <ElementFile> element, which points to a generic file that is part of the Feature but is not an Element Manifest. An example of such a file can be a master page or a .webpart file.

Both elements have a Location attribute that must contain the path to the referenced file. Most of the next posts in this series describe each type of Element Manifest.

Properties Element

The <Properties> element is optional and it defines a property bag that can be accessed in Custom Feature Event Receivers. This element contains <Property> elements which have two attributes:

  • Key: Name of the property key, in the property bag.
  • Value: Value of the property, in the property bag.

This property bag can be very useful to send parameters to a Custom Feature Event Receiver whose behavior can be parameterized.

Feature Installation and Uninstallation

Although the best way to install a Feature is through a Solution, you can do it manually. Just keep in mind that you must do it in all the servers of the farm (whereas with the Solution, the multi-server deployment is automatically assured).

To install a Feature you have to create a folder in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES with the name of the Feature and copy the feature.xml and any other files (like Element Manifests) to that folder. Then you have to execute the following console command:

    stsadm -o installfeature -name MyFolderName

Where MyFolderName is the name you gave the folder that contains the Feature.

To uninstall the Feature you have to execute the opposite console command (see below) and remove the folder you created.

    stsadm -o uninstallfeature -name MyFolderName

Feature Activation and Deactivation

Similarly, besides activating and deactivating the Feature using the SharePoint UI, you can do it using console commands. To activate a Feature you have to execute the following command:

stsadm -o activatefeature -name MyFolderName -url http://MyServer/MyWebSite

Where MyFolderName is the name of the folder that contains the Feature, and http://MyServer/MyWebSite is the URL address of the web site where you want to activate the Feature.

To deactivate it, you call the opposite command, as shown below:

stsadm -o deactivatefeature -name MyFolderName -url http://MyServer/MyWebSite

SharePoint 2007 Deployment: Features and Solutions

Summary

This second post on my SharePoint Deployment Series is focused on the concepts of Feature and Solution. Check the first post SharePoint 2007 Deployment: Overview for an introduction and the series index.

What's a Feature?

A Feature is a package composed of a set of XML files that describe Windows SharePoint Services elements, which can be activated on a specific scope to help users accomplish a given task. To make it easier to understand, I usually say that you should use a Feature when you need to add one or more objects to SharePoint and want to allow users to easily enable or disable that option.

With a feature you can:

  • Add a site column
  • Add a site content type
  • Add a list template
  • Create a list instance
  • Add custom actions to SharePoint's menus
  • Install web parts, master pages, layout pages, images and other contents
  • Register event handlers
  • Associate a content type with an existing list
  • Install a custom workflow
  • Install a custom control
  • Install a custom document converter

However, a feature cannot install itself. For that, it needs a solution.

What's a Solution?

A Solution is a deployable and reusable package that can contain a set of Features, site definitions and assemblies that you can apply to a site, and can also enable or disable individually. A Solution is materialized in a solution file, which is a file with a CAB-based format with a .wsp extension.

With a solution you can:

  • Install Features
  • Install assemblies in the GAC
  • Install assemblies to the BIN folder of a web application
  • Add assembly descriptions to the web.config safe controls section
  • Set Code Access Security configurations
  • Install files in the template folder of SharePoint (usually C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE)
  • Install files in the root folder of SharePoint (usually C:\Program Files\Common Files\Microsoft Shared\web server extensions\12)
  • Install a site definition

A Solution is the only way to automatically execute a deployment of functionality to a SharePoint server farm.

SharePoint 2007 Deployment: Overview

I’m starting a new series of posts on SharePoint Deployment, since I believe it’s one of the hardest tasks on a SharePoint project. This first post will be updated every time I add a new article to this series.

SharePoint 2007 Deployment Series

Part 0: Overview (this post)
Part 1: Features and Solutions
Part 2: Creating and Using Features
Part 3: Creating and Using Solutions
Part 4: Site Column Features
Part 5: Site Content Type Features
Part 6: List Template Features
Part 7: List Instance Features
Part 8: Custom Action Features
Part 9: Module Features
Part 10: Event Registration Features
Part 11: Content Type Binding Features
Part 12: Feature Stapling (Feature Site Template Association)
Part 13: Using Resources in Features 

Who Needs Deployment?

Regarding the development environment, there are two types of SharePoint projects:

  • Single environment projects, where everything is configured and developed directly in the production environment;
  • Multiple environment projects, where all the development and configuration is done in a development environment, then possibly deployed to a testing environment, and finally deployed to the production environment.

Additionally, you can have two types of farms, in a SharePoint installment:

  • Single server farm, when there is only one SharePoint Server in the farm (although there can be additional SQL Servers);
  • Multiple server farm, when there are several SharePoint Servers, possibly with different server roles, in the farm.

For Single Server – Single Environment projects, which are the least common type, the developers don’t really need to be concerned about deployment since everything is done on the same server. But for the other types of projects (Single Server – Multiple Environment, Multiple ServerSingle Environment and Multiple Server Multiple Environment) developers will need to deploy their work to the servers.

What Does Deployment Mean, in a SharePoint Sense?

In SharePoint, deployment means the necessary actions to install your software solution in a SharePoint environment, whether that solution consists of web parts, custom web controls, event handlers, custom web pages, or just master pages.

So, imagine you have created site columns and content types directly on the SharePoint UI, customized some master pages using SharePoint Designer and installed a few custom web parts on your Development Environment, and now you need to deploy this to the Testing Environment (and later on, to the Production Environment). You can choose from a few different deployment methods:

  • Stone Age Deployment. You do it all over again in the Testing Environment, and later you will repeat the procedure in the Production Environment. It’s not hard to figure out this is a bad practice: probably you won’t be able to repeat the tasks in the exact same order as you did before, and that might result in errors or in a Testing Environment that is not a replica of the Development Environment. Also, that means the developers must have administration access in all the environments, which is not always the case.
  • Backup/Restore Deployment. You perform a farm backup on the Development Environment and restore it in the Testing Environment. Although commonly used, it’s not the best practice either: you must make sure all the assemblies, web.config modifications, and file system changes are present in the destination environment before you restore the backup. Also, you might have some problems if the environments are not in the same windows domain.
  • Content Deployment. You use SharePoint’s content deployment paths and jobs. That can be a good solution, but it has some limitations: unless you are deploying a whole site collection, you’ll need to make sure all the assemblies, web.config modifications, and file system changes are present in the destination environment before you restore the backup. Content deployment is targeted at "contents" and not at "structure", although some of the SharePoint structures are migrated with the contents. Also, both environments must be connected for automatic content deployment to work. You have the option to export a site collection to a .CAB file and import it in the destination environment using STSADM commands, but the same limitations apply.
  • Solution Deployment. You build SharePoint Features for all the objects you developed and pack them in one or more SharePoint Solutions. This is the recommended approach for structure deployment, since it allows for multiple server farm deployment, allows the deployment of assemblies, web.config modifications, files in file system folders as well as all SharePoint objects.

This series of posts will focus on the last deployment method.