Configuring and Branding a Visual Web Part Solution for SharePoint 2010 With Visual Studio 2010

Although I originally saw the new Visual Studio Tools for SharePoint 2010 back in August 2009, this past week was the first opportunity that I was able to get down to business with them, working with a web part solution (I don’t get to develop as much as I’d like to these days…). The beauty of these tools is that they not only (finally) give you a true “F5” approach to developing SharePoint applications, but they also build out and deploy web part solutions automatically for you. Indeed, every run of your application goes through the packaging and deployment process.

Before I get into this, I want to say that to a jaded old SharePoint developer, these tools are like manna from heaven. Not only is ease of use greatly improved, but so is speed of deployment and debugging.

However, unless you want your feature to be named “Feature1” and your solution to be named “MySolution”, and you want your assembly to be named exactly the same as your project, you’ll want to brand your solution a bit. Renaming a project and/or a component file will do a certain amount of refactoring automatically for you, but it isn’t complete and there are a few gotchas. I thought that I’d outline a few of them,and walk you through a branding process. This example uses a Visual Basic project,and there will be differences with C#, but the concepts remain the same.

1. Create your Visual Web Part, and give it a name. In this case, the name will be “Hello World” (Original, huh?)

image

2. Next, change the Web part names from “VisualWebPart1” to your name, in this case “HelloWorld” (notice the lack of spaces). When asked to perform a rename of all references, select yes. Don’t get too excited, it only changes code references.

image

3. Then, do a search and replace (Ctl-H) on the entire solution, and replace “VisualWebPart1” with your name – in our case “HelloWorld”

image

It should find and replace 5 references (for a VB.NET project at least).

4. If you want to change the name of your assembly and/or root namespace, go to project properties and do so. In our case, the Assembly name will be changed from “Hello World” to “SecondFoundation.HelloWorld”, and the root namespace will be changed from “Hello_World” to “SecondFoundation.HelloWorld”.

image

5. Next, edit the SharePointProjectItem.spdata file. This is a hidden file and you’ll need to turn on the “Show All Files” option in the solution explorer. This file controls the auto generation of several project components.

image

In the SafeControl entry, you’ll find that the Namespace attribute reflects the original name of the assembly. You’ll need to update it to reflect your change:

image

6. Next, edit your xxxx.webpart file (in our case HelloWorld.webpart). You’ll need to change the name attribute of the type entry in the <metaData> section to reflect your changes. While you’re at it, you should likely change the Title and Description properties to something meaningful, although this isn’t required.

image

7. You’ll need to edit your xxxxxxUserControl.ascx file (in our Case HelloWorldUserControl.ascx) and change the Inherits attribute from the Control entry (the last line) to reflect the namespace changes.

image

8. Optionally, edit the Elements.xml file, and change the Group property to something meaningful.

image

9. Open up the Features section in the Solution Explorer, and change the name from Feature1 to something meaningful. In our case, to continue on with my highly creative theme, we’ll call it HelloWorld.

image

10. Finally, Edit your .ascx file and add some content to allow us to see the web part on the page. I’ll leave it to you to guess what content I’m adding…..

Run your project, and add your new web part to the page that pops up. All should be well.

image

This should get you going with creating non-generic web parts. Enjoy.

Advertisements

Using a Fixed Width Page in SharePoint 2010

For the most part, I prefer dynamic width pages on an intranet. It allows users to take advantage of the screens that they have, and to work the way that they want. They do have one big drawback though in that they don’t allow consistent control of presentation. You never know for sure where a particular screen artefact will be. This can be a  real problem, particularly when it is necessary to maintain a consistent brand. The solution to this is to use a fixed width page, which basically keeps the width of the content constant, no matter what the width of the browser.

If you previously worked with SharePoint 2007, you’ll know that this was the default behaviour of the standard Publishing master pages (like BlueBand.master). Team sites, and most other sites used a variable width template. SharePoint 2010 now uses variable width for both types of templates, and I’m not sure that’s a good thing in a web content management scenario.

I recently had to set up my first fixed length centered page in 2010, and it was harder than I thought it would be. I isolated the class controlling the width of the content (#s4-workspace), explicitly set the width, and refreshed the page. it loaded correctly,but upon load,it immediately snapped back over to the left and filled the page. Obviously, there’s some javascript trickery going on here.

Luckily, thanks to Tom Wilson, the correct solution was quickly obtained. Basically, javascript is looking for that s4-workspace id, and doing what it thinks is best with it. Since we beg to differ, the solution is to first remove that id tag altogether. Then, you need to add in the appropriate styling to compensate for the lack of javascript positioning.

.SFC{
overflow:auto;
background: transparent url(''/SiteCollectionImages/Page_BG.jpg'') no-repeat fixed left top;

}
.SFC form
{
width:958px;
margin-left:auto;
margin-right:auto
}

The background image isn’t necessary, but it can be used to fill the non content region of the browser.

SharePoint 2010 Page Layouts – What’s this UIVersionedContent all about?

If you work with the publishing features of SharePoint at all, or you do much branding, you’ve undoubtedly run into the UIVersionedContent control. Here’s an example of its use:

image

So what does this thing do? Simply put, it allows the SharePoint visual upgrade feature to work. When a site collection is upgraded from SharePoint 2007 (depending on the options selected), the sites themselves may wind up looking pretty much the same as they did before the upgrade. That’s because the SharePoint team didn’t want to be breaking any customizations or forcing users in specific teams to deal with new design elements, or for those concerns to hold up any upgrades. They therefore have introduced Visual Upgrade – this allows sites (not site collections) to be upgraded one at a time.

However if my site using the 2010features is using the same master page, or page layout as a site that uses the 2007 features, how will that work? That’s where this control comes into play. The control simply contains a ContentTemplate control, which in turn contains the markup to be used. It also possesses an attribute, “UIVersion” which is set to either 3 or 4. These numbers correspond to the old WSS versioning system (WSS 3, SharePoint Foundation 4) and will use the contained markup if the version of the site matches the attribute.

You’ll normally see these controls in pairs, giving an either/or type capability,but there’s no need to restrict them to this.

It’s actually a pretty slick system,but it does add a lot of text to the page layouts. One annoying thing is that all of the V3 supporting code is there even if it’s a brand new install of 2010. This makes sense, because you can introduce a V3 content database into the mix at any time, and you never know when you might need the support. However, if you know that the master pages and page layouts you’ll be working with will only be used in by V4 content, you can feel free to go ahead and remove the V3 tags. Before you do though, make sure that you’re not editing the system default masters/layouts. Always create new ones and do your customization there.

I’ve not seen any other values for the attribute besides 3 and 4 – these are processed by the server accordingly. I’m intrigued by the development possibilities though. Ideally, this could support an environment where I can register a “version” that my site could select to use. This would be much cleaner than keeping multiple master pages for variations in branding, or to support micro sites. This also might be a better model in the WCM world for multi lingual support. I have no idea if that’s the plan, but to me it would make sense.

Using Themes and CSS with SharePoint 2010

Branding SharePoint just got a lot easier with the release of 2010. I used to have a basic rule of thumb when it came to using themes with 2007. Don’t use them. And if you must use them, don’t do further customization down the road. This is no longer true with 2010. The themes in 2010 are quite literally Office theme files (.thmx) and can be edited and created with PowerPoint.

There are really two types of branding exercises with SharePoint. The first is for public facing, typically anonymous sites with a high degree of customization and complete control over all of the visual elements. The second is for authenticated, typically intranet type sites where some customization is necessary, but where appropriate, out of the box visual elements can be used. In either case, themes are a good place to start the branding exercise, but they are particularly compelling with the latter, which is what this article is focused on.

Themes are essentially a collection of colours, and default fonts. You can apply a theme to a site by going to Site Settings, and selecting Site Theme under the Look and Feel heading.

image

As can be partially seen here, there are two other major theme features in 2010 that were not available in 2007,the ability to inherit a theme from a parent site,and the ability to push a theme down to sub sites, much like the way that master pages work.

From here you can select a theme, and if you like modify it. You can change the base colour for the 12 colour categories (the colour scales are calculated automatically), and you can set the base font face for headings and body. If you do modify these colour, you should be aware that you are not modifying the theme files themselves, which live in the theme gallery, but the derived CSS classes that are automatically generated whenever a theme is applied to a site. As such, you will find yourself working with a “custom theme”. Unfortunately, there is no way to save the custom theme off to the gallery, or locally, and that severely limits its reusability options. If anyone from Microsoft is reading this, please consider it a feature request.

The best way to edit a theme is by using PowerPoint, and it’s exceedingly easy. You can create a theme from scratch easily enough, but if you wanted to use one of the themes that ship with 2010 as a starting point, you can simply navigate to Site Settings (from the root site), and select Themes under the gallery heading. This is a simple document library, so select the theme in question, and click “Download a Copy” from the ribbon.

image

Once the file is downloaded, just double click on it to open up PowerPoint. PowerPoint will open up to a blank presentation. Click on the Design tab in the ribbon, and you will see that your theme colours are currently selected. You will edit your theme using the “Colors”, “Fonts” and “Effects” buttons.

image

Here’s where it gets a little non-intuitive. To change your colours, click the colors button and select “Create New Theme Colors”. I know… they’re not new, but to PowerPoint they are.

image

Edit away to your heart’s content, and then give the theme a good descriptive name so that you can refer to it later. You will likely use this name when saving your theme in a moment, but for now, this name will be used by PowerPoint to identify this group of colours. When you’re done selecting colours, save them, and repeat the process as necessary for fonts and effects. Once done, it’s time to save your theme. Simply use File-Save As, and select the “Office Theme (*.thmx”)” file type, and give the file a good descriptive name. Once that’s done, navigate back to the theme gallery, upload it, and it will be available for selection now under site theme.

What happens if you want your customization to go a little further? Maybe you’d like to tweak some of the CSS classes a little?   Should your start figuring out what the system classes are and start changing them? What’s the best approach?

Under no circumstances (OK, maybe a couple, but don’t) should you modify the core CSS files. There are many ways to accomplish your goal, I use several depending on the use case, but one of the easiest is to simply create a CSS Override file, and tell the system to use it. I start with a blank file called CoreOverrides.css (call it whatever you want) and I store it in the root of the style library. The next step is to tell the site to use it.

From the root site, Go into site settings, and select the Master Page link in the Look And Feel section. Then scroll down to the “Alternate CSS URL” section.

image

The description for this section is just as poorly written in 2010 as it was in 2007. It implies that by turning this on, you’re turning the internal classes off. This is not at all  true. The file that you indicate here gets loaded into the CSS stack after all other system classes have loaded, and therefore any classes defined here will have precedence over any identically named system classes. That’s why I call it Overrides.

How do you know which classes need to be modified? That’s where hacking comes in, or a lot of patience. You can study the master pages and page layouts, use view source on a rendered page, or use the IE developer tools. I use all 3, but I’m beginning to like developer tools a lot.

Load the page in question into IE, and then press the F12 key (or select Tools-Developer Tools from the menu). You will get a child browser widow pop up and from here you can navigate the entire DOM of the page. However, we want to see what CSS is being applied to a particular element, and the easiest way to do that is to select the CSS tab, and then select Find-Select Element By Click from the menu. You can then hover over any element on your page which will be outlined, and when you have the one that you want, click it , and its CSS stack will be displayed.

Once you find the class who’s behaviour you wish to change, simply copy its definition over to your overrides file, and edit away. Keep in mind though that you’re overriding a pre-existing class definition, and therefore you need to be explicit. If you want to remove a background image, you cant simply remove its definition, you must set it to “none”. Also, because some properties can be very sticky, I find the use of the !important directive to be very helpful.

Happy branding!