Deploying Composed Look – The Declarative Method – Part 2

Back in December I posted a lengthy article on how to deploy a Composed Look for SharePoint 2013. If you haven’t read that it can be found here – https://tommdaly.wordpress.com/2012/12/19/deploying-a-custom-composed-look-in-sharepoint-2013/. In that article I described the two methods declarative and imperative. Given all the recent buzz around the deprecated sandbox solutions many of our clients are very anti code for their sandbox and online farms/tenants. I’ll keep this post short and sweet but this expands upon the declarative method.

Going back to my old post, I provided this excerpt of the elements.xml I used to provision the Composed Look to the Composed Looks list. You might wonder how did I get this, well I made a .wsp via Design Manager, renamed it to .cab, and extracted the files. In there I found the elements.xml that was used to deploy the composed look. Using this I was unhappy because if you look closely below you’ll see some URLs in there. I’m not a fan of using URLs or hard coding ANYTHING. If you’ve been working with SharePoint a long time then you know that this is not always possible in their xml with data views, and provisioning. (yes there are hacks & work arounds but lets not go there)

 

So here is my new snippet of XML for the elements.xml file which is used to create the new list item. I’ve removed the URLs completed and replaced them with ~sitecollection. Alternatively you could use ~site if you just wanted the web URLs to be replaced. No matter what site you upload this to the master page, image, theme, fonts will be connected up properly and no more messy URLs. A few other fields have been cleaned up:

  • Removed HyperlinkBarUrl from <ListInstance>
  • Removed Description from <ListInstance>
  • Display Order Field simplified
  • Removed FileLeafRef Field
  • Removed ID Field – It will generate the next available, if you set this to 100 then then next available ID becomes 101 when adding another via the UI.

image

download this as file

 

I’ve found that deploying this twice it will NOT overwrite itself. So if you make a change you’ll have to delete the Composed Look via the UI and then redeploy. I don’t see any parameters which allow list rows to be overwritten http://msdn.microsoft.com/en-us/library/ms478860.aspx so this may be a limitation. It would be amazing to be able to overwrite itself for any changes.

Advertisements

SharePoint 2013 Theme Builder Tool

SharePoint 2013 Theme Builder Tool

I just wanted to post this here in case anyone stumble across it… There is a tool released by Microsoft to assist with building SharePoint 2013 Themes more specifically the theme color palettes. This will help a lot when working with the .spcolor files and building custom Composed Looks.

Theme Builder Lives On!

For those working with SharePoint 2010 themes this tools seemed to be amazing at giving me those .THMX files. Until they took it away, but they never told me it would come back as something else.

If you go to http://connect.microsoft.com/ThemeBuilder and sign in with you window live id you’ll notice a nice error message

image

Theme Builder has been reincarnated and I just found it yesterday. I’ve always kept a copy of the original Theme Builder anyway. But now here it is

Open XML Theme Builder

Deploying Master Pages & Themes via a Feature using Visual Studio 2010

Following this guide you’ll see the process that goes behind creating the feature which commonly be used to deploy branding items such as Master Pages, CSS, JavaScript, & Themes. If you plan to follow along just replace the steps with my name with whatever you wish.

Configure the Project

  1. Open Visual Studio 2010
  2. File -> New -> Project

  1. Select SharePoint -> Empty SharePoint Project
  2. Add Name: TomDaly.SharePoint.Branding (this is my standard structure)
  3. Add Location: C:\Projects\TomDaly

  1. Click OK
  2. Enter your test site for debugging purposes.
  3. Select ‘Deploy as farm solution’

  1. Click Finish

Adding the CSS / Image / JavaScript Files

Add CSS file

  1. Right Click on the Project -> Add -> SharePoint ‘Layouts’ Mapped Folder

  1. This created a folder which is mapped to the layouts

** These files in here are accessible through the web via http://YOURSITE/_layouts/TomDaly.SharePoint.Branding/

  1. Right click on Layouts\TomDaly.SharePoint.Branding folder -> Add -> New Item

  1. Select Web on the left, and Style Sheet on the right, and Name the file at the bottom.

(I typically use base.css or style.css for the foundation of my styles, but this is all up to you)

  1. Click Add

Add Images & JavaScript Folder

This would be the location for any images associated with the site css.

  1. Right Click on the Layouts\TomDaly.SharePoint.Branding folder -> Add -> New Folder

  1. Name the folder ‘images’

OPTIONAL STEP

  1. Repeat Step 1 & 2 for the JavaScript folder. (I typically call this folder ‘js’)

I usually include a JavaScript folder because most of the time I end up using jQuery somewhere on the site, this is where I store those files which I would reference on page or in the Master Page. Depending on how it’s needed.

These files would be accessible: http://YOURSITE /_layouts/TomDaly.SharePoint.Branding/js/JSFILESHERE

Setting up the Feature

  1. In your project Right click on Features -> Add Feature

This will create a feature with some default name of ‘Feature 1’, which we don’t want

  1. Select Feature1, Right Click -> Rename

  1. Rename the Feature to TomDaly.SharePoint.Branding (I typically name it to the same as the project name)

  1. Double Click on your Primary feature, in the main left hand window the properties should appear

  1. Give your feature a normal title name Title and Description, and scope it accordingly. (I usually scope my master pages to (Site) as they are normally used through the site collection

  1. Click Save

Renaming the WSP

This is really annoying to me so I always change it. When a .WSP is generated it will usually come out as Feature_Feature.wsp. I prefer just Feature.wsp.

1. Double Click on the primary Feature, the Properties should appear right below it.

2. Change ‘Deployment Path’

From: $SharePoint.Project.FileNameWithoutExtension$_$SharePoint.Feature.FileNameWithoutExtension$

To: $SharePoint.Project.FileNameWithoutExtension$

Adding the Master Page

1. Right Click on the Project -> Add -> New Item

2. In the left Installed Template column, Select SharePoint 2010

3. On the right select Module

4. At the bottom name the Module, Master Pages

5. Click Add

** You module will be added to your project **

6. Under the Master Pages Module, right click on Sample.txt and Delete It

7. Now Drag & Drag and Drop your Custom Master Page from another folder into the project, In the Master Pages Module

8. Double Click on the Elements.xml in the Master Pages Module

9. In the Elements.xml file, make the following changes to the <Module> line

Change

<Module
Name=MasterPages>

To

<Module
Name=MasterPages
Url=_catalogs/masterpage>

10. In the Elements.xml file, make the following changes to the <File> line

a. add IgnoreIfAlreadyExists=True

b. add Type=GhostableInLibrary

c. remove MasterPages/ from the
Url=MasterPages/TOMDALY.master

So essentially this line

<File
Path=MasterPages\TOMDALY.master
Url=MasterPages/TOMDALY.master />

Changes to

<File
Path=MasterPages\TOMDALY.master
Url=TOMDALY.master
IgnoreIfAlreadyExists=True
Type=GhostableInLibrary />

11. Click Save

Adding Theme

This step will incorporate a theme into your project. How to generate the .thmx is not covered here but a simple way would be to export from PowerPoint or use ThemeBuilder to generate this file.

1. Right Click on the Project -> Add -> New Item

2. On the left Click SharePoint -> 2010

3. On the Right Select “Module”

4. Add Name: Theme

5. Click Add

6. In the Theme node, Delete Sample.Txt

7. Copy in you custom .thmx file

8. Double Click on the Elements.xml in the Theme Module

9. In the Elements.xml file, make the following changes to the <Module> line

Change

<Module
Name=Theme>

To

<Module
Name=Theme
Url=_catalogs/theme>

10. In the Elements.xml file, make the following changes to the <File> line

a. add IgnoreIfAlreadyExists=True

b. add Type=GhostableInLibrary

c. remove Theme/ from the
Url=Theme/TomDaly.thmx

So essentially this line

<File
Path=Theme\TomDaly.thmx
Url=Theme/TomDaly.thmx
/>

Changes to

<File
Path=Theme\TomDaly.thmx
Url=TomDaly.thmx
IgnoreIfAlreadyExists=True
Type=GhostableInLibrary />

11. Click Save

Adding the Feature Receiver

This whole step is optional. Its sole purpose is to automatically turn on the branding on the sites and subsites, apply a theme, or apply search master pages to your site collection. NOTE: If you changed the scope then there is no guarantee that this code will work.

Please take some time to look through the code as there are different sections you might want to comment out or fill in. Say if you want to configure the Site Logo or an Alternative CSS file. If you not interested and just want a working project jump down to the END and in the summary there is a link to download the project.

1. Right Click your primary Feature, Select Add Event Receiver

** This will get added Right under your feature**

2. Double Click on the new file TomDaly.SharePoint.EventReciever.cs

5. At the very top Add the following using statements

using Microsoft.SharePoint.Utilities;

using System.Collections.ObjectModel;

7. Under the class declaration add these three string constants which contain the names of the masterpages and the theme.

So my master page name is TomDaly.master, my search master page which I don’t have a custom one for yet is minimal.master, and my Custom Theme is called TomDaly

8. Replace the public override void FeatureActivated, with

public override void FeatureActivated(SPFeatureReceiverProperties properties)

{

SPSite site = properties.Feature.Parent as SPSite;

if (site != null)

{

using (SPWeb topLevelSite = site.RootWeb)

{

//Get the relative path

string relativePath = topLevelSite.ServerRelativeUrl;

if (!relativePath.EndsWith(“/”))

{

relativePath += “/”;

}

//Get Theme collection from site and the them we want

ReadOnlyCollection<ThmxTheme> themes = ThmxTheme.GetManagedThemes(site);

ThmxTheme customTheme = null;

foreach (ThmxTheme theme in themes)

{

if (theme.Name == themeName)

{

customTheme = theme;

break;

}

}

//Apply branding to each web in the site collection

foreach (SPWeb web in site.AllWebs)

{

//Apply masterpage and logo

if (web.WebTemplate == “SRCHCENTERLITE” || web.WebTemplate == “SRCHCEN” || web.WebTemplate == “SRCHCENTERFAST”)

{

web.CustomMasterUrl = relativePath + “_catalogs/masterpage/” + searchMasterPage;

}

else

{

web.MasterUrl = relativePath + “_catalogs/masterpage/” + masterPage;

web.CustomMasterUrl = relativePath + “_catalogs/masterpage/” + masterPage;

}

web.AlternateCssUrl = “”;

web.SiteLogoUrl = “”;

web.UIVersion = 4;

web.Update();

//Also apply the theme

if (customTheme != null)

{

customTheme.ApplyTo(web, true);

web.Update();

}

}

}

}

}

9. Replace the public override void FeatureDeactivated, with

public override void FeatureDeactivating(SPFeatureReceiverProperties properties)

{

SPSite site = properties.Feature.Parent as SPSite;

if (site != null)

{

using (SPWeb topLevelSite = site.RootWeb)

{

//Get the relative path

string relativePath = topLevelSite.ServerRelativeUrl;

if (!relativePath.EndsWith(“/”))

{

relativePath += “/”;

}

//Apply branding to each web the wen the site collection

foreach (SPWeb web in site.AllWebs)

{

//Apply default masterpage and logo

if (web.WebTemplate == “SRCHCENTERLITE” || web.WebTemplate == “SRCHCEN” || web.WebTemplate == “SRCHCENTERFAST”)

{

web.CustomMasterUrl = relativePath + “_catalogs/masterpage/minimal.master”;

}

else

{

web.MasterUrl = relativePath + “_catalogs/masterpage/v4.master”;

web.CustomMasterUrl = relativePath + “_catalogs/masterpage/v4.master”;

}

web.AlternateCssUrl = “”;

web.SiteLogoUrl = “”;

web.Update();

//reset the theme back to default

ThmxTheme.SetThemeUrlForWeb(web, null, true);

web.Update();

}

}

}

}

10. Click Save

11. Hit F6, or Build -> Build Solution … to ensure that everything is correct and ok. You should receive the “Build Succeed” in the bottom left corner

Changing the Site Url for Testing

Sometimes you want to create or re-use this package and you need to change the url of the site to deploy to.

1. Click on the project and in the Properties window you’ll notice the Site URL

2. Change that to your new site destination

3. Click Save

Deployment

If you’re testing on a development box, that visual studio is on then you can simply deploy through visual studio. Otherwise you’ll have to push out your solution with the .wsp file.

Deploy from Visual Studio

1. In the Build Menu, Select Deploy

OR

Getting the .WSP for manual deployment

1. In the Build menu, Select Build to ensure no errors

2. In the Build menu, Select Package to generate the .WSP file

3. The files will be in the project folder, and by default in the BIN\DEBUG

Either way once you deploy your solution should be available in the Site Collection Features Gallery as shown here

Summary

So that’s how you setup a project for deploying branding assets. This is the typical setup I use but can change from client to client depending on their needs.

Download the entire project here.

SharePoint Saturday New York City – Slides & Demo

Amazing weekend at SPSNYC! Well about as amazing as SharePoint things can get. Thank you everyone for attending my session, I appreciate the comments and questions. I’m attaching my slides and my demo Visual Studio 2010 package which is the feature driven deployment of the theme, masterpage, css, images, and javascript files.

Do what you will to take it apart and test it out.

What you’ll need to do in order to deploy from Visual Studio is change the Site Url.

When You open the solution select the main Project -> SPSNYC.Branding.

In the Properties window, set the site url to your SharePoint 2010 test site.

That’s all for now. If you have any issues feel free to contact me.

Slides

Demo