SharePoint 2010 – WSS 2010

Hi, Jonathan Kern here <a href="http://blogs.msdn.com/sharepoint/archive/2010/04/06/customizing-ribbon-posITioning-in-sharepoint-2010-master-pages.aspx” target=”_blank”>again. Today’s post is about one of the new features in SharePoint 2010: Visual Upgrade. Visual Upgrade allows administrators to decouple UI upgrade from system upgrade. This helps make upgrading to a new version of SharePoint far less painful for your users and for your helpdesk personnel.

Much of our UI is aware of Visual Upgrade in that IT condITionally renders based on the SITe’s UI Version (2007 UI or 2010 UI). But SharePoint is built as a platform, so there are several ways in which your customizations can also be aware of Visual Upgrade.

UIVersion: The basic unIT of Visual Upgrade

Visual Upgrade is a SITe-level setting that selects which product version UI to use when displaying the SITe. For example, one SITe may use the 2007 UI while another could use the new 2010 UI. In our APIs, this setting is represented as an integer property on SPWeb called UIVersion. For this release, the two valid values for this property are 3 (meaning SharePoint 2007) and 4 (meaning SharePoint 2010).

Controls and code can pivot on this value to determine how to behave based on the SITe’s UI Version. At the very simplest, you can pivot directly on the UIVersion property. However, there are some best practices when doing so:

• Avoid using == unless you absolutely need to. Future versions of SharePoint may (and likely will) have a different value for SPWeb.UIVersion, so unless you want your customization to stop working after upgrade to a future release, you should use something like >= or < when doing a comparison wITh the property. You can, however, be assured that future versions will have a UI Version that is greater than the version before.
• If you can use a single code path for both UI Versions, do so. There is no reason to maintain two separate paths if you don’t absolutely need them.
• Try not to reinvent the wheel. See the sections below to see if one of our out-of-the-box APIs will do the job.

Visual Upgrade content containers

A common type of customization that needs to be aware of Visual Upgrade is ASP.NET markup. We provide two container controls to make IT easy to condITionally render markup based on the SITe’s UI Version. Both condITionally render their contents based on whether the value in their UIVersion attribute matches the SITe’s UI Version. More on this attribute later. The controls are slightly different though, and IT’s important to know the differences so you can use the right one for your job:

1. UIVersionedContent: During the InIT phase of the ASP.NET Page Lifecycle, if the value of the UIVersion attribute matches the current SITe’s UI Version, UIVersionedContent will add ITs child controls to the ASP.NET control hierarchy. If the UIVersion attribute does not match the SITe’s, the child controls are never added to the control hierarchy and no processing is done for them.

   <SharePoint:UIVersionedContent UIVersion=”>=4”>
   	<ContentTemplate>
   		<!-- Content -->
   	</ContentTemplate>
   </SharePoint:UIVersionedContent>
       

2. VersionedPlaceHolder: During the PreRender phase of the ASP.NET Page Lifecycle, if the value of the UIVersion attribute does not match the SITe’s UI Version, VersionedPlaceHolder will set ITs Visible property to false, thus hiding ITself and all ITs children (i.e. Render never runs).

   <SharePoint:VersionedPlaceHolder UIVersion=”>=4”>
   	<!-- Content -->
   </SharePoint:VersionedPlaceHolder>
       

There are pros and cons for each control:

The UIVersion attribute

For both of the above controls, and others to be explained below, there is a common syntax to express what UI Version(s) the controls should render in:

Please note that the last two examples are shown for completeness but are considered deprecated. You will see them used in out-of-the-box files, but our guidance going forward is to use one of the other syntaxes.

Other controls and elements that can be versioned

In addITion to the two container controls, there are several other existing controls and elements that we’ve added the UIVersion attribute to:

• ScriptLink
• CSSLink: While there is a UIVersion property available, IT is better to set Version which will handle setting UIVersion for you. If you need the more complex syntaxes shown above, you can set Version and then UIVersion.
• CSSRegistration
• CustomAction
• Feature
• Master Pages: There is a UI Version column in the Master Page Gallery that is used in SharePoint Designer and in SITes wITh the Publishing Feature enabled to filter the master pages that can be applied to those that are valid for the given SITe. For this column, the valid values are (empty) meaning that the master page is valid in all UI Versions, 3 meaning that IT is compatible wITh the 2007 UI, and 4 meaning that IT is compatible wITh the 2010 UI.

Conclusion

Now you’ve got the know-how to get your SharePoint customizations ready for Visual Upgrade. Just remember to follow the best practices listed above when pivoting against SPWeb.UIVersion directly, and use the right syntax when using the UIVersion attribute on a control.

As always, if you have questions about Visual Upgrade or the SharePoint UI or need some help getting IT to do what you want IT to, head over to the SharePoint 2010 forums on Technet. I check there often and will be able to provide guidance (if someone else doesn’t beat me to IT).

Until next post,

–Jonathan Kern

UX Developer, SharePoint Foundation

Further Reading

• SharePoint 2010 Upgrade Overview
• Plan visual upgrade (SharePoint Server 2010)
• SPWeb.UIVersion

Tags: Customization

Hi, I’m Jonathan Kern and I’m a developer on SharePoint Foundation. For SharePoint 2010, I am responsible for a variety of User Experience (UX) features such as Visual Upgrade, SITe UI (including v4.master and minimal.master), and parts of the Ribbon platform. I’m posting today to talk about how two of these features work together: the Ribbon and the Master Page.

As you’ll likely notice in SharePoint 2010, the Ribbon is specially posITioned to always be visible on the screen, even if you scroll down the page contents. This is accomplished by placing the Ribbon into ITs own container and then using client-side script to make the rest of the page contents take up the remainder of the browser’s height. You can see this in action by swITching between the “Browse” tab and the “Page” tab on the SharePoint default homepage: The top of the scrollbar on the right side of the browser window will move up and down depending on whether the Ribbon is opened or not.

One of the questions I hear most often is how to enable or disable this behavior on a custom master page. To answer this question, I need to explain more about how the system works. There are three parts of the system: The markup on the master page, the CSS styles in the stylesheet, and the ECMAScript code linked to on the page.

Master Page Markup

Let’s start wITh the markup. SharePoint 2010 compatible master pages require many components, but there are a few key components that are used by the Ribbon posITioning system. Going from top to bottom, the first component of note is the “_fV4UI” ECMAScript variable. In v4.master, IT looks like this:

<script type=”text/javascript”>
var _fV4UI = true;
</script>

This block tells the rest of the ECMAScript code in SharePoint that this master page is operating in SharePoint version 4 mode (version 4 corresponds to SharePoint 2010). This variable is used in the script that handles Ribbon posITioning which I’ll discuss later on.

Moving down the master page source code, the next interesting component is the “body” tag. In v4.master, IT looks like this:

<body scroll=”no” onload=”…” class=”v4master”>

The two important parts of the tag are the “scroll” and “class” attributes. The “scroll” attribute is used to force IE to hide the page scrollbar. Since SharePoint handles the scrollbar independently, we need to stop the browser from interfering. For other browsers, the scrollbar is hidden using CSS styles which are explained later in this post. The CSS class applied to the “body” tag is used to apply CSS styles in the corev4.css stylesheet which are part of the Ribbon posITioning system. If you are using a custom stylesheet, you may leave this out; but make sure to apply the needed CSS styles in some other way (perhaps by referencing “body” directly in your stylesheet).

The next important component on the master page is the Ribbon container. In v4.master, IT looks like this:

<div id=”s4-ribbonrow” class=”s4-pr s4-ribbonrowhidetITle”>
     …
</div>

Let’s look at this piece by piece. First, you’ll notice that the element is a div so that IT takes up the width of the browser and acts as a block-level HTML element. After that, is the ID which is a mandatory part of the system: the ECMAScript logic for Ribbon posITioning uses this ID to find the Ribbon container. If you omIT or change this ID, the Ribbon posITioning system will abort and your Ribbon will not stay docked to the top of the page. I’ll discuss the steps to enable and disable the system later on in this post. The next part of the Ribbon container element is the “class” attribute which lists the CSS classes applied to IT. The first one is just a layout class used to make the container full width and block displayed. “pr” stands for Page Row. The second CSS class is used in the Ribbon posITioning system to tell what state the Ribbon is in currently. IT is set to “s4-ribbonrowhidetITle” by default, but that is changed to the correct value once the ECMAScript code on the page inITializes.

The Ribbon control ITself lives inside the Ribbon container. Also present are the controls that appear in the top row of the ribbon (e.g. SITe Actions, breadcrumb navigation button, edIT/save button, the Personal Actions menu, etc.), the notifications area, Publishing Console, and Web Part adder. Nothing else should be placed into this container as ITs height is set using static values that will not adjust to addITional content. To add more chrome above the Ribbon, you should add a new element above the Ribbon container.

Immediately following the Ribbon container are two other important elements on the master page: the Workspace element and the Body Container. These elements look like this in v4.master:

<div id=”s4-workspace”>
                <div id=”s4-bodyContainer”>
                                …
                </div>
</div>

The Workspace container is the element that remains scrollable when the Ribbon posITioning system is enabled. Like the Ribbon container, ITs ID is mandatory as IT must be referenced from ECMAScript code during page load. Directly inside of the Workspace container is the Body Container. ITs ID is also required. Body Container is used to determine the width of the page content wIThin the client-side script. Both of these elements must be present on the master page for the Ribbon posITioning system to run. If one or both are missing, the system will abort.

There is one more interesting element on the master page: The TITle container. As you’ll notice in v4.master, opening a Ribbon tab other than Browse will hide the page tITle and top navigation and replace IT wITh the appropriate Ribbon tab. The important distinction to note here is that the “Browse tab” is not actually a tab. In realITy, IT is simply an empty Ribbon tab wITh normal HTML below IT. In v4.master, the TITle container looks like this:

<div id=”s4-tITlerow” class=”s4-pr s4-notdlg s4-tITlerowhidetITle”>
     …
</div>

Like the other containers discussed above, the TITle container must have a specific ID, in this case “s4-tITlerow.” However, unlike the other containers, if the TITle row ID is not present, the Ribbon posITioning system will still run. If you leave out the ID or remove the element completely, the system will just ignore IT and handle everything else appropriately. This means that if you leave the element but remove the ID, the TITle area will not be removed from the page when you open a Ribbon tab. The CSS classes are also worth noting: As I explained above, “s4-pr” just makes the element take up the full browser width and display as a block element; “s4-notdlg” is used to stop the element from appearing if the page is being loaded in a Modal Dialog; “s4-tITlerowhidetITle” is used by the Ribbon posITioning ECMAScript to handle the current state of the Ribbon – just like the corresponding class on the Ribbon container, IT is updated accordingly when the client-side script inITializes at page load.

CSS Styles

All of the CSS styles pertinent to the Ribbon posITioning system are in corev4.css. They are all required for the Ribbon posITioning system to function properly. The first style rule of importance is “body.v4master” which is defined as follows:

body.v4master {
                height: 100%;
                width: 100%;
                overflow: hidden;
}

This makes the body of the page take up the full width and height of the browser and hides the scrollbar for most browsers (remember that the “scroll” attribute on “body” handles this for some versions of IE).

Next is the CSS rule for the Ribbon container:

body #s4-ribbonrow {
     min-height: 43px;
     background-color: #21374c;
     overflow-y: hidden;
}

This makes the Ribbon row take up 43px of vertical space at minimum and allows groups that cannot be fIT into the browser (after scaling) to “fall off the edge” of the ribbon.

Below the Ribbon container styles are a set of styles that only apply to printing. I won’t go through each of these, but suffice to say that these styles are meant to undo some of the posITioning applied by the system so that the full page displays when printed.

Further down the stylesheet are the styles for the Workspace and Body Container elements:

body s4-workspace {
                overflow-y: scroll;
                overflow-x: auto;
                posITion: relative;
                left: 0px;
}
body #s4-bodyContainer {
                min-width: 760px;
}

First, we make the Workspace element always show a vertical scrollbar (to prevent shifting of page contents on load) and show a horizontal scrollbar only if necessary. The other two declarations in this rule are used for other layout purposes. The Body Container gets assigned a minimum width to ensure that shrinking the browser window down won’t render SharePoint unusable.

ECMAScript

The real logic of the Ribbon posITioning system is in the ECMAScript code. I won’t go through the actual code that runs, but if you are curious, you can open up inIT.debug.js in your layouts\1033 folder and look for “FixRibbonAndWorkspaceDimensions()”. The Ribbon posITioning logic is triggered in three ways: when the page loads, when the browser is resized, and when the Ribbon is minimized or maximized (for example, by double-clicking a tab tITle). Note that swITching between the “Browse” tab and other tabs is a form of minimizing and maximizing the Ribbon.

The logic generally works like this:

· First, we look for the four interesting elements on the page: the Ribbon container, the Workspace container, the Body Container, and the TITle container. If any of the first three cannot be found, the code aborts.

· We then check if the Workspace element has the CSS class “s4-nosetwidth” applied to IT. If so, IT will not set the width of any elements. This is useful if you have a fixed-width master page design.

· Next, we use static values plus some runtime information to determine the height that should be set on the Ribbon container. If the Ribbon container has ITs “visibilITy” style set to “hidden,” the system will set the Ribbon container’s height to 0px. This is the supported way to hide the Ribbon container for certain users but keep the Ribbon posITioning logic when the Ribbon is displayed.

· Now, the important calculation occurs: The system gets the browser’s viewport height (the area of the window that contains the SharePoint page) and subtracts the height of the Ribbon container and the top posITion of the Ribbon container to determine how much space is left below for the Workspace container.

· The calculated height is set to the Workspace element and then some extra logic is run to set width and scroll posITion information accordingly.

At the very end of the ECMAScript logic, a set of callback functions are run for components that need to know when the Ribbon posITioning system has run. If you need to run some code at this point, you can call SP.UI.Workspace.add_resized(handler) which will add your handler to the list.

Enabling and Disabling the System

Now that you have a better idea of how everything works, let’s run through the necessary steps to enable and disable the system for your master page.

Enabling the Ribbon PosITioning System

The easiest way to take advantage of the Ribbon posITioning system is to derive your custom master page from v4.master. All you have to do is pay attention to the components listed above so that you don’t remove something that’s important. If you end up using a custom CSS file, make sure to include all of the CSS rules shown above. The ECMAScript is included automatically by the ScriptLink control. ScriptLink is required on all SharePoint 2010 compatible master pages, so you get that for free.

If you are retrofITting an old master page to work wITh the Ribbon posITioning system, you can simply follow the steps at http://msdn.microsoft.com/en-us/library/ee539981%28office.14%29.aspx to upgrade your master page. Most of what is discussed on this post is covered briefly in that documentation.

Disabling the Ribbon PosITioning System

If you’re customizing v4.master, but wish to let the Ribbon scroll up wITh the page contents, you’ll need to do a few things:

In your master page:

1) Remove the “_fV4UI” variable from the top of the page. IT will still be emITted by the SPWebPartManager later on in the page’s markup, but IT will not be present when the on-load events for the Ribbon posITion system are usually attached. This will stop the code from running when the page loads which will improve rendering performance.

2) Remove or change the Workspace element’s ID to make the ECMAScript code abort early during window resizes and Ribbon minimize/maximize events. You can leave the element, but just change or remove the ID.

3) Remove the “scroll” attribute from the Body tag.

In your CSS stylesheet:

1) Remove or change the width, height, and overflow declarations on the “body” tag.

2) You can optionally remove the s4-workspace and s4-bodyContainer rules since they are no longer necessary.

Conclusion

I hope that the information in this post is useful to you in some way. The Ribbon posITioning system is complex, but IT is fairly easy to work wITh as an end-user or third-party developer. If you have questions about the system or need some help getting IT to do what you want IT to, head over to the SharePoint 2010 forums on Technet. I check there often and will be able to provide guidance (if someone else doesn’t beat me to IT).

Until next post,

–Jonathan Kern
UX Developer, SharePoint Foundation

Tags: Customization

For those who build custom internet facing SharePoint Web Content Management sITes, which means they are likely anonymous, one of the most frustrating things was trying to implement a custom error page in SharePoint 2007.

Thankfully this has been addressed in SharePoint 2010. Microsoft PFE Todd Carter (aka: Carl Fredrickson) recently blogged how you can create your own custom error pages… and you aren’t limITed to just the error page… you can create Login, Request Access, Confirmation, Access Denied and Sign-Out Pages too!

»Todd Carter: An Expected Error Has Occurred

Tags: Configuration, Customization

Customizing Ribbon Positioning in SharePoint 2010 Master Pages: Hi, I’m Jonathan Kern and I’m a devel… http://bit.ly/9u66i4 – #SharePoint

Tags: Customization, Development

Hi, I’m Jonathan Kern and I’m a developer on SharePoint Foundation. For SharePoint 2010, I am responsible for a variety of User Experience (UX) features such as Visual Upgrade, SITe UI (including v4.master and minimal.master), and parts of the Ribbon platform. I’m posting today to talk about how two of these features work together: the Ribbon and the Master Page.

As you’ll likely notice in SharePoint 2010, the Ribbon is specially posITioned to always be visible on the screen, even if you scroll down the page contents. This is accomplished by placing the Ribbon into ITs own container and then using client-side script to make the rest of the page contents take up the remainder of the browser’s height. You can see this in action by swITching between the “Browse” tab and the “Page” tab on the SharePoint default homepage: The top of the scrollbar on the right side of the browser window will move up and down depending on whether the Ribbon is opened or not.

One of the questions I hear most often is how to enable or disable this behavior on a custom master page. To answer this question, I need to explain more about how the system works. There are three parts of the system: The markup on the master page, the CSS styles in the stylesheet, and the ECMAScript code linked to on the page.

Master Page Markup

Let’s start wITh the markup. SharePoint 2010 compatible master pages require many components, but there are a few key components that are used by the Ribbon posITioning system. Going from top to bottom, the first component of note is the “_fV4UI” ECMAScript variable. In v4.master, IT looks like this:

<script type=”text/javascript”>
var _fV4UI = true;
</script>

This block tells the rest of the ECMAScript code in SharePoint that this master page is operating in SharePoint version 4 mode (version 4 corresponds to SharePoint 2010). This variable is used in the script that handles Ribbon posITioning which I’ll discuss later on.

Moving down the master page source code, the next interesting component is the “body” tag. In v4.master, IT looks like this:

<body scroll=”no” onload=”…” class=”v4master”>

The two important parts of the tag are the “scroll” and “class” attributes. The “scroll” attribute is used to force IE to hide the page scrollbar. Since SharePoint handles the scrollbar independently, we need to stop the browser from interfering. For other browsers, the scrollbar is hidden using CSS styles which are explained later in this post. The CSS class applied to the “body” tag is used to apply CSS styles in the corev4.css stylesheet which are part of the Ribbon posITioning system. If you are using a custom stylesheet, you may leave this out; but make sure to apply the needed CSS styles in some other way (perhaps by referencing “body” directly in your stylesheet).

The next important component on the master page is the Ribbon container. In v4.master, IT looks like this:

<div id=”s4-ribbonrow” class=”s4-pr s4-ribbonrowhidetITle”>
     …
</div>

Let’s look at this piece by piece. First, you’ll notice that the element is a div so that IT takes up the width of the browser and acts as a block-level HTML element. After that, is the ID which is a mandatory part of the system: the ECMAScript logic for Ribbon posITioning uses this ID to find the Ribbon container. If you omIT or change this ID, the Ribbon posITioning system will abort and your Ribbon will not stay docked to the top of the page. I’ll discuss the steps to enable and disable the system later on in this post. The next part of the Ribbon container element is the “class” attribute which lists the CSS classes applied to IT. The first one is just a layout class used to make the container full width and block displayed. “pr” stands for Page Row. The second CSS class is used in the Ribbon posITioning system to tell what state the Ribbon is in currently. IT is set to “s4-ribbonrowhidetITle” by default, but that is changed to the correct value once the ECMAScript code on the page inITializes.

The Ribbon control ITself lives inside the Ribbon container. Also present are the controls that appear in the top row of the ribbon (e.g. SITe Actions, breadcrumb navigation button, edIT/save button, the Personal Actions menu, etc.), the notifications area, Publishing Console, and Web Part adder. Nothing else should be placed into this container as ITs height is set using static values that will not adjust to addITional content. To add more chrome above the Ribbon, you should add a new element above the Ribbon container.

Immediately following the Ribbon container are two other important elements on the master page: the Workspace element and the Body Container. These elements look like this in v4.master:

<div id=”s4-workspace”>
                <div id=”s4-bodyContainer”>
                                …
                </div>
</div>

The Workspace container is the element that remains scrollable when the Ribbon posITioning system is enabled. Like the Ribbon container, ITs ID is mandatory as IT must be referenced from ECMAScript code during page load. Directly inside of the Workspace container is the Body Container. ITs ID is also required. Body Container is used to determine the width of the page content wIThin the client-side script. Both of these elements must be present on the master page for the Ribbon posITioning system to run. If one or both are missing, the system will abort.

There is one more interesting element on the master page: The TITle container. As you’ll notice in v4.master, opening a Ribbon tab other than Browse will hide the page tITle and top navigation and replace IT wITh the appropriate Ribbon tab. The important distinction to note here is that the “Browse tab” is not actually a tab. In realITy, IT is simply an empty Ribbon tab wITh normal HTML below IT. In v4.master, the TITle container looks like this:

<div id=”s4-tITlerow” class=”s4-pr s4-notdlg s4-tITlerowhidetITle”>
     …
</div>

Like the other containers discussed above, the TITle container must have a specific ID, in this case “s4-tITlerow.” However, unlike the other containers, if the TITle row ID is not present, the Ribbon posITioning system will still run. If you leave out the ID or remove the element completely, the system will just ignore IT and handle everything else appropriately. This means that if you leave the element but remove the ID, the TITle area will not be removed from the page when you open a Ribbon tab. The CSS classes are also worth noting: As I explained above, “s4-pr” just makes the element take up the full browser width and display as a block element; “s4-notdlg” is used to stop the element from appearing if the page is being loaded in a Modal Dialog; “s4-tITlerowhidetITle” is used by the Ribbon posITioning ECMAScript to handle the current state of the Ribbon – just like the corresponding class on the Ribbon container, IT is updated accordingly when the client-side script inITializes at page load.

CSS Styles

All of the CSS styles pertinent to the Ribbon posITioning system are in corev4.css. They are all required for the Ribbon posITioning system to function properly. The first style rule of importance is “body.v4master” which is defined as follows:

body.v4master {
                height: 100%;
                width: 100%;
                overflow: hidden;
}

This makes the body of the page take up the full width and height of the browser and hides the scrollbar for most browsers (remember that the “scroll” attribute on “body” handles this for some versions of IE).

Next is the CSS rule for the Ribbon container:

body #s4-ribbonrow {
     min-height: 43px;
     background-color: #21374c;
     overflow-y: hidden;
}

This makes the Ribbon row take up 43px of vertical space at minimum and allows groups that cannot be fIT into the browser (after scaling) to “fall off the edge” of the ribbon.

Below the Ribbon container styles are a set of styles that only apply to printing. I won’t go through each of these, but suffice to say that these styles are meant to undo some of the posITioning applied by the system so that the full page displays when printed.

Further down the stylesheet are the styles for the Workspace and Body Container elements:

body s4-workspace {
                overflow-y: scroll;
                overflow-x: auto;
                posITion: relative;
                left: 0px;
}
body #s4-bodyContainer {
                min-width: 760px;
}

First, we make the Workspace element always show a vertical scrollbar (to prevent shifting of page contents on load) and show a horizontal scrollbar only if necessary. The other two declarations in this rule are used for other layout purposes. The Body Container gets assigned a minimum width to ensure that shrinking the browser window down won’t render SharePoint unusable.

ECMAScript

The real logic of the Ribbon posITioning system is in the ECMAScript code. I won’t go through the actual code that runs, but if you are curious, you can open up inIT.debug.js in your layouts\1033 folder and look for “FixRibbonAndWorkspaceDimensions()”. The Ribbon posITioning logic is triggered in three ways: when the page loads, when the browser is resized, and when the Ribbon is minimized or maximized (for example, by double-clicking a tab tITle). Note that swITching between the “Browse” tab and other tabs is a form of minimizing and maximizing the Ribbon.

The logic generally works like this:

· First, we look for the four interesting elements on the page: the Ribbon container, the Workspace container, the Body Container, and the TITle container. If any of the first three cannot be found, the code aborts.

· We then check if the Workspace element has the CSS class “s4-nosetwidth” applied to IT. If so, IT will not set the width of any elements. This is useful if you have a fixed-width master page design.

· Next, we use static values plus some runtime information to determine the height that should be set on the Ribbon container. If the Ribbon container has ITs “visibilITy” style set to “hidden,” the system will set the Ribbon container’s height to 0px. This is the supported way to hide the Ribbon container for certain users but keep the Ribbon posITioning logic when the Ribbon is displayed.

· Now, the important calculation occurs: The system gets the browser’s viewport height (the area of the window that contains the SharePoint page) and subtracts the height of the Ribbon container and the top posITion of the Ribbon container to determine how much space is left below for the Workspace container.

· The calculated height is set to the Workspace element and then some extra logic is run to set width and scroll posITion information accordingly.

At the very end of the ECMAScript logic, a set of callback functions are run for components that need to know when the Ribbon posITioning system has run. If you need to run some code at this point, you can call SP.UI.Workspace.add_resized(handler) which will add your handler to the list.

Enabling and Disabling the System

Now that you have a better idea of how everything works, let’s run through the necessary steps to enable and disable the system for your master page.

Enabling the Ribbon PosITioning System

The easiest way to take advantage of the Ribbon posITioning system is to derive your custom master page from v4.master. All you have to do is pay attention to the components listed above so that you don’t remove something that’s important. If you end up using a custom CSS file, make sure to include all of the CSS rules shown above. The ECMAScript is included automatically by the ScriptLink control. ScriptLink is required on all SharePoint 2010 compatible master pages, so you get that for free.

If you are retrofITting an old master page to work wITh the Ribbon posITioning system, you can simply follow the steps at http://msdn.microsoft.com/en-us/library/ee539981%28office.14%29.aspx to upgrade your master page. Most of what is discussed on this post is covered briefly in that documentation.

Disabling the Ribbon PosITioning System

If you’re customizing v4.master, but wish to let the Ribbon scroll up wITh the page contents, you’ll need to do a few things:

In your master page:

1) Remove the “_fV4UI” variable from the top of the page. IT will still be emITted by the SPWebPartManager later on in the page’s markup, but IT will not be present when the on-load events for the Ribbon posITion system are usually attached. This will stop the code from running when the page loads which will improve rendering performance.

2) Remove or change the Workspace element’s ID to make the ECMAScript code abort early during window resizes and Ribbon minimize/maximize events. You can leave the element, but just change or remove the ID.

3) Remove the “scroll” attribute from the Body tag.

In your CSS stylesheet:

1) Remove or change the width, height, and overflow declarations on the “body” tag.

2) You can optionally remove the s4-workspace and s4-bodyContainer rules since they are no longer necessary.

Conclusion

I hope that the information in this post is useful to you in some way. The Ribbon posITioning system is complex, but IT is fairly easy to work wITh as an end-user or third-party developer. If you have questions about the system or need some help getting IT to do what you want IT to, head over to the SharePoint 2010 forums on Technet. I check there often and will be able to provide guidance (if someone else doesn’t beat me to IT).

Until next post,

–Jonathan Kern
UX Developer, SharePoint Foundation

Tags: Customization, Development

SharePoint web dialogs bring an exciting new UI feature: they can auto-size to the content of a hosted page. Auto-sizing works by examining the contents of your page during page load, and setting the size of the dialog accordingly. Unfortunately, this feature can be speed bump on the road to master page customization. This post will describe the master page customization process necessary to keep dialog auto-sizing working with your master pages.

The most important thing to note is that the auto-sizing feature is aware of whether the ribbon is fixed at the top of the screen. It is important to know whether your master page has the ribbon fixed at the top of the screen or not in order to customize it to work well with auto-sizing. A ribbon fixed on top of the screen looks like this, with the page content below the ribbon scrollable separately from the ribbon itself:

 Critical Path Training have a new course devoted to using SharePoint Designer 2010 written by a leading SharePoint Designer 2010 expert and SharePoint MVP Asif Rehmani.

Asif has been teaching, presenting, writing and consulting on SharePoint since 2002 spoken about SharePoint Designer 2010 at numerous major conferences including last fall’s SharePoint Conference in Las Vegas. He’s also one of the authors of WROX’s Professional Office SharePoint Designer 2007 & is currently working on a SPD 2010 book as well. Check out a sampling of Asif’s work from the stuff he’s posted to YouTube!

This class, Creating No-Code SharePoint Designer Solutions for SharePoint 2010, is being offered for a limited time at 30% off the regular pricing while SharePoint is still in a pre-release beta (note this is a limited offer until SharePoint hits the big release date we’re all anticipating). Here’s a list of our upcoming dates:

• March 8-12 : Chicago, IL
• May 3-7 : Tampa, FL
• June 28 – July 2 : Redmond, WA

We’re also offering this class in an online format. The agenda is slightly different (two modules are exclusive to the hands-on in person class), but it’s a great way to get the same class for those of you with limited travel budgets:

• March 29 – April 2
• May 24-28
• July 19-23

Interested? Register today!

Tags: Customization, Designer, Features

[This script has been updated over here] I’m pretty sure every SharePoint enthusiast has seen those great Sneak Peek videos Microsoft released some time ago. And I’m sure that lots of the new features shown were very exciting for lots of you. Since SharePoint 2010 is still quite far away in the future, let’s try to bring some of the 2010 stuff to SharePoint 2007! In the overview video, Tom Rizzo showed some new user interface functionality, pretty much all of it was heavily using asynchronous Javascript code to dynamically do updates, change layouts etc. All of this of course to prevent those nasty full page reloads. One of the features that caught my eye was the inline editing of list items or documents: without reloading the page, or opening a new page, it’s possible in SharePoint 2010 to edit meta data. Pretty cool! And I want to have it in my SharePoint sites, today.

In my previous post I showed how you can add extra functionality to the Edit Control Block (ECB), let’s take that technique and make it more flexible and customizable. Here is the result I’m looking for:

Notice that everything you see is happening completely at the client side, without any code deployed to the server, without any full page postbacks. So how do you get this working in your SharePoint sites? Just download this script file [This script has been updated over here] and open it. On top of the script you’ll find the ajaxListConfig variable which you can change to customize the script:

var ajaxListConfig = {
    columns         :new Array(“Status”, “Priority”), // columns to ajaxify
    values          :new Array(
                        new Array(“Not Started”, “In Progress”, “Completed”,
    ”Deferred”, “Waiting on someone else”), // values for Status
                        new Array(“(1) High”, “(2) Normal”, “(3) Low”) // values for Priority
                        ),
    debug           :0, // set to 1 to see log messages
    animationSpeed  :”slow” // possible values: “slow”, “normal”, “fast” or a number (milliseconds)
};

When you download the script, it’s configured for a default Task list. If you want to enable it on other list types or Document Libraries, or you’re running SharePoint in another language than English the following options need to be changed:

• 
  
  columns: in the array you need to type the names of the columns you want to ajax-enable


• 
  
  values: for every column defined in the columns option, you need to provide an array of values

Optionally you can set the debug option to 1, so a log window is being displayed in case something goes wrong. The animationSpeed option allows you to set the speed of the fancy fade in and out effects for the updated values. When all options are set, follow these steps:

1. 
   
   Navigate to the page where you would like to use it (e.g. http://yoursite//Lists/Tasks/AllItems.aspx for the Task list).


2. 
   
   Click Site Actions, Edit Page (top right).


3. 
   
   Click Add a Web Part.


4. 
   
   Select the Content Editor Web Part in the Miscellaneous section and click Add.


5. 
   
   Optionally drag the Content Editor Web Part to the bottom of the screen (otherwise a small space will be displayed on top of the page).


6. 
   
   Click open the tool pane in the web part.


7. 
   
   Click Source Editor … in the properties task pane.


8. 
   
   Copy and paste the modified script in the Text Entry dialog and click Save.


9. 
   
   Click Exit Edit Mode (top right) and verify the result.

Remember when the script doesn’t work as expected, set the debug option to 1 and you’ll see the log messages appearing at the bottom right of the screen. Btw, thanks my Twitter buddies who tested the script! (feel free to follow @jantielens).

[This script has been updated over here]

Tags: Customization

In my previous post I introduced a small script to extend the Edit Control Block (ECB) of list items and documents. The added menu items in the ECB allow users to update certain metadata fields for that item or document. The cool thing is that everything is happening in the background with the help of jQuery, even the actual updating of the data. The result: no postbacks or full page loads, pure AJAX goodness just like showcased in the SharePoint 2010 sneak peek videos. Today I’m releasing a new and improved version of the script, based on your feedback. Here are the changes:

Column names can have a display name and an internal name

In the previous version of the script you’d had to specify the names of the columns you’d like to ajaxify based on the internal name (which escapes spaces etc). In the new version of the script you can specify the display name as well. For example this is a possible configuration for a Task list:

columns: ["Status", "Priority", "% Complete#PercentComplete", "Description#Body"]

For the Status and Priority columns, no internal names are specified since they are the same as the display names. But notice that the next two columns have a # sign in them. The part preceding the # sign is the display name, the part after the # sign is the internal name from SharePoint.

Column values can have a display name and an internal name.

This works exactly as the column names, so if there is a # sign, the first part will be the display value, the second part will be the internal value. For example this is the array of values for the % Complete column of a task list:

["100%#1.00000000000000", "75%#0.750000000000000", "50%#0.500000000000000", "25%#0.250000000000000", "0%#0"]

Internally percentages are stored as values between 0 and 1. But we’d like show them as real percentages to the user of course: e.g. 100% will be displayed, while 1.00000000000 will be stored in SharePoint.

Multiple lists and document libraries can be configured in the same script.

Now you can also use the script if there is more than one list view web part on a page: in the lists option of the ajaxListConfig variable, multiple lists can be defined based on their name.

var ajaxListConfig = {
    lists:
        [
            {   name: "Tasks",
                columns: [ ... ],
                values: [ ... ] },
            {   name: “Issues”,
                columns: [ ... ],
                values: [ ... ] },
        ],
    debug: 0, // set to 1 to see log messages
    animationSpeed: “fast” // possible values: “slow”, “normal”, “fast” or a number (milliseconds)
};

User entered values are now supported.

In the previous version, the user could only use the predefined values for a column (which makes lots of sense for Choice columns). In the new version, if the values option of a list configuration is equal to null (instead of an array of values), dialog is displayed in which the user can fill out a new value. For example in the Task list below, the Update Description menu item is displayed, but there is submenu to display the possible values.

When the user clicks on the Update Description menu item, a dialog is displayed to allow the user to modify the value. Once again there are no postbacks. To display the dialog I’m using the Imprompty jQuery extension (included in my script). Notice that there is no Rich Text editing (yet), so HTML tags will be stripped out. Also there is no support for editing Person fields etc.

Finally …

… some small bug fixes and performance enhancements are done. To use the script, configure it to your needs (when you download it, it’s configured for a default Task and Issue list), then follow these steps:

1. Navigate to the page where you would like to use it (e.g. http://yoursite//Lists/Tasks/AllItems.aspx for the Task list).


2. Click Site Actions, Edit Page (top right).


3. Click Add a Web Part.


4. Select the Content Editor Web Part in the Miscellaneous section and click Add.


5. Optionally drag the Content Editor Web Part to the bottom of the screen (otherwise a small space will be displayed on top of the page).


6. Click open the tool pane in the web part.


7. Click Source Editor … in the properties task pane.


8. Copy and paste the modified script in the Text Entry dialog and click Save.


9. Click Exit Edit Mode (top right) and verify the result.

Tags: Customization