SharePoint 2013 includes a number of new features to make it easier than ever before to style and publish web sites. One of those features is Design Manager; it allows you to do things like create different channels for your content – such as one set of pages for full size browsers, one for mobile devices, another for tablets, etc. You can associate different master pages with each channel. And one of the really interesting features is that you can create a page in any standard HTML editing tool, like Dreamweaver, and upload it to SharePoint and use it as a master page. SharePoint takes care of automatically creating an .aspx page that it keeps in sync with your .html file. After this conversion takes place you’re not stuck going back to some other tool to edit it; you can continue to edit the .html file in your preferred editing tool and every time you save it SharePoint syncs up the .aspx file that’s used to render your master page.
In addition we provide something called Snippets that allow you to take chunks of gooey SharePoint goodness and plug it into your master page. You simply select the type of snippet you want – like a search box, or quick navigation, etc. – and copy the auto-generated code for the feature and paste it into your master page. It’s not a complete walk in the park though – there are still some SharePoint-ism’s you need to know in order to completely convert your standard .html page into a SharePoint master page.
In this post, what I’m going to do is take the web site page you create with the Dreamweaver tutorial (http://www.adobe.com/devnet/dreamweaver/articles/first_website_pt1.html) and convert it into a SharePoint master page and home page for my site. So to begin with, here’s what the Dreamweaver site looks like when completed:
In looking at the page you can see there’s some SharePoint-specific things we will need to address:
First let’s think about it from a content perspective. The out of the box content types can address the main content, but we need something custom to account for the three story snippets at the bottom of the page. We’ll start with that, and build a new content type to support it. Since the images are intrinsically linked to the content, we’ll add site columns for them along with site columns for the text itself. The Welcome Page content type is probably a pretty good base class for this kind of page, so I created a new content type based on the Welcome Page and called it DW Layout. To support my layout I added the following columns:
The image columns are all defined as Image with formatting and constraints for publishing and the text columns are defined as Full HTML content with formatting and constraints for publishing.
At this point we’re ready to begin the first stage with Design Manager, where we’ll upload our Dreamweaver HTML page and stylesheet and get it converted to a master page.
Now, open your browser from the machine on which Dreamweaver (or your favorite HTML editing tool) is installed and navigate to your SharePoint site. Click on the Site Actions menu and select Design Manager. In the list of tasks on the left, click on #3, Upload Design Files. Click on the link to map a local drive to the SharePoint folder where your master page and style sheet will be stored. It should open up an Explorer view of the SharePoint site so you can drag and drop files directly from SharePoint into Dreamweaver. If that doesn’t work for some reason, you can always navigate to the master page library and just open the library in Explorer view.
Next copy the index.html master page from your local drive to the SharePoint library that is open in Explorer view. The Dreamweaver tutorial assumes that the style sheet is in a subfolder called styles, so create that folder and copy the style sheet into it.
Now in the browser, click on #4, Edit Master Pages in the Design Manager task list. Click on the link called Convert an HTML file to a SharePoint master page. A SharePoint file browser style dialog will open and you should see the index.html file that has been copied up to the master page gallery. Click on it to select it, then click the Insert button. The conversion should complete and then the Design Manager page will show the file in the list of master pages with a message that says conversion successful. At this point if you refresh your Explorer view of the master page library you should see a new file called index.master. This is the “pair” to the index.html file that you uploaded to the site. SharePoint will take care of updating this master file from this point forward – all you need to do is just work with the HTML file.
It’s probably worth viewing your new master page now so you can see what you have to work with. To do that, you can click on the index.html link in Design Manager. It opens the page in preview mode so you can see what your master page looks like. Out of the gate it’s interesting – here is what it looks like when the conversion is first done:
Some things to point out:
First let’s take a look at the fixes we need. We need to upload the image used for the background of the main body section and correct our link to it in the master. But we need to delete all the other images in the bottom portion of the page. In addition to that, we need to delete the all of the text on the page, because it is all content that should be associated with a single page, not the master. To get working on this, drag the HTML and CSS files back from the Explorer view of the SharePoint master page gallery and drop it in Dreamweaver. You’ll notice all the sudden that you have a lot more SharePoint “goo” in your HTML page. Get used to that – even though you’re able to use your own HTML editor now, you still need to use the SharePoint controls and tags that bring it all to life.
As we scroll through the HTML, we can find the images we are missing that should be part of the master page. They are banner.gif (from the HTML), and main.jpg (from the style sheet that sets the background for the main_image DIV); we’ll fix those first.
Back in the browser, click on the Site actions menu and then click the View Site Contents menu. Click on the Site Collection Images link to open up that document library. Now we’re going to upload our two images to that library. The library Url is /sitecollectionimages, so using Dreamweaver we’ll change the path for both images to point to that library. If you refresh the preview page, you’ll see that we’re making progress:
One thing you’ll probably notice that you didn’t see in the previous picture is the yellow DIV along the bottom of the page. That was actually in the first picture but the browser was sized too big for you to see it. Now what’s important about that yellow div is that SharePoint put that in during the conversion process, and it contains the placeholder for the main page content. So next what we are going to do is gut the content that should be part of a content page, not the master page. So we’re going to remove the text in the main section, and delete the images that aren’t rendering and text below them. We’re also going to move that placeholder DIV (minus the yellow) into the main section of the page. In addition to that, we’re going to add placeholder controls for the three areas where we have images and text. We’ll tie those together when we make our layout page.
The resulting HTML has a combination of comments, special SharePoint processing tags, and placeholders for where our content will go. Here’s what each section looks like:
The page itself is looking a little empty now, but that’s okay – it’s what we want from a master page:
Now that we have that done, we’re nearly finished with our master page. We still will want to add some menus and search box but we’ll come back to that in a bit. The next thing we’re going to do is create a layout page. A layout page is where we “connect” the data fields with their layout on the page. To do that, we go into the Site Settings…Master pages and page layouts. I click the New button in the ribbon and select Page Layout. When the New Page Layout screen comes up I get to select the content type that I want associated with this page layout. You may recall from earlier in this posting I described creating a custom content type and calling it DW Layout. So in the Associated Content Type field I just select my DW Layout content type. I give it a Url, Title and Description and that’s it – I can create my layout page. In this case I made the Url for the page DWLayoutPage.aspx, the Title is Dreamweaver Layout Page and I added a description of Layout page based on Dreamweaver tutorial site.
Now my layout page is created, but it doesn’t have any controls on it yet. We need to add the controls to the page and bind them to the custom fields in the content type that I described earlier: LeftStoryImage, LeftStoryText, etc. In addition, I also need to add ASP.NET placeholder controls that correspond to the placeholder containers I added to my master page. In this way, the data in each field is associated with a container, and that container is output into the corresponding container placeholder on the master page – that’s how our data gets rendered in the right spot in the master page.
If you look at the details above from the master page, you’ll see that I added four content placeholders: PlaceHolderMain, PlaceHolderLeft, PlaceHolderCenter, and PlaceHolderRight. I need to add those placeholders to my layout page, and then put the appropriate content type field in each one. To do this, I’m going to again drag my new layout page, DWLayoutPage.aspx, from the Explorer view of the Master Page Gallery and drop it onto Dreamweaver. By default the layout page has one placeholder control already called PlaceHolderMain, so I don’t need to add that. I add the others though using standard ASP.NET control markup like this:
<asp:Content ContentPlaceholderID="PlaceHolderLeft" runat="server">
As you can see I just gave it an ID of PlaceHolderLeft, and then I added two more, with IDs of PlaceHolderCenter and PlaceHolderRight.
In terms of the actual fields needed in our layout page, there really aren’t that many. There’s the main content field, which comes with the base class that our custom content type inherited from. That field is called simply PublishingPageContent. Since it goes in the main body of the page, I added a publishing control for it in the PlaceHolderMain section, so that section looks like this:
<asp:Content ContentPlaceholderID="PlaceHolderMain" runat="server">
<PublishingWebControls:RichHtmlField id="PageContent" FieldName="PublishingPageContent" DisableInputFieldLabel="true" runat="server"/>
Each of the other three placeholders requires two fields – an image field and a rich text field. So I add them and again use the content type field name in the FieldName attribute of the markup. Here’s an example of what the PlaceHolderLeft control looks like; Center and Right are of course very similar:
<PublishingWebControls:RichImageField FieldName="LeftStoryImage" runat="server"/>
<PublishingWebControls:RichHtmlField id="LeftTextContent" FieldName="LeftStoryText" DisableInputFieldLabel="true" runat="server"/>
At this point we’re pretty much set from a master page and layout page perspective (other than the menus and search box I mentioned above). So now we want to create a new page and tell it to use our new page layout.
To do that, we go into the Pages library. I click New on the ribbon and select DW Layout; it appears on the new menu now since it’s based on a content type that inherited from the Welcome Page content type:
I fill in the required properties and it looks something like this:
Okay – now we’re ready to try this out! To begin with, I go back to the master page gallery and I publish my master page (index.html). Until I do that, I cannot select it as the master page for the site. The next thing I do is go back into Site Settings, into the master page settings and select my master page as the master for the Site Master Page. I never set it for the System Master Page at first to make sure everything’s working. If you goof up your master page and assign it to the System Master Page you can be in terrible trouble trying to revert things back.
With that done, I can now go back to my Pages library and click on the dwhome.aspx page I just created. That brings it up in the browser, so I can edit it. As you can see, it’s starting to come together pretty well:
I’m going to go ahead now and plug in the data from my original Dreamweaver site. Since all of the text fields are rich HTML I can just copy the raw HTML from that Dreamweaver page and paste it into the field in HTML mode.
The pictures are a little more interesting. The first thing I do is upload them from my local drive into the Images folder in SharePoint. Once they’re in there I can take advantage of another new publishing feature in SharePoint 2013 called Image Renditions. It allows you to create a custom size that an image should be rendered. In this case, the images in the Dreamweaver tutorial site were all the same size – 316px wide by 130 pixels high. To mimic this behavior I go into Site Settings…Image Renditions (under the Look and Feel section). You’ll see three renditions that you get out of the box; I just clicked on the link to add a new item and created a rendition with the dimensions I described and called it Column Image. When I added the image to the page I was allowed to select which image rendition should be used to display the image on the page; I picked the Column Image rendition and that was all that was needed to have things line up just like they did in the Dreamweaver site.
When I’m done, I end up with this, which pretty much looks like my original Dreamweaver site now; here’s a picture of the original on top and the SharePoint version right below it:
It really looks pretty good; the main thing that stands out as being different is just the color and font of some of the built-in tags like H2 and H3. For now I’ll fix that up by just adjusting what’s in my style sheet for those areas; you could decide whether to approach it one-off or change it for all H2, H3, etc. tags.
After making those little CSS adjustments I now have a page that is basically a dead ringer for my original Dreamweaver site. At this point I’m going to go ahead and check in the dwhome.aspx page and make it the home page for my site. The last thing I want to do is add some of the SharePoint features to my master page that I had mentioned earlier – the top navigation and search box.
To begin, I drag my master page back from the Explorer view and into Dreamweaver. In the browser, I go to the Site actions menu and select Design Manager. I click on option #4, Edit Master Pages, then click on index.html, which is our master page for this exercise. I get my preview again, and I’m going to click on the Snippets menu in the top right corner now. That’s going to let me take advantage of this cool new feature in which we let you select from different standard SharePoint page elements, like top and vertical navigation, the site title and logo, search box, web parts, etc. To make things a little more visually “interesting” for this scenario I added a couple of new pages called Products and Careers to the site and created navigation links to them.
Back in my master page, I just added new DIV elements where I want my navigation and search box to go. I then went to the Snippets page and copied the code for the Top Navigation and Search Box then pasted into the appropriate DIV. My master page looks like this now (the snippet code is removed for brevity; you can get yours by just doing a copy and paste from your snippet page):
<div id="menu_div" style="width: 335px; position: relative; top: -4px;">
<!-- The Menus Go Here -->
<!-- Top Menu Snippet Here -->
<div id="searchbox_div" style="float: left; width: 245px; position: relative; top: -32px; left: 730px;">
<!-- search box goes here -->
<!-- Search Box Snippet Here -->
Here’s the finished product, complete with the SharePoint menus and search box:
Now that we’ve finished there are a couple of things worth pointing out. First, this is really a bad example for a master page. Why is that? Because the layout works great for a home page, but for most of your content pages it’s not really flexible enough to use. The point of this posting though was really just to take a well-known example in the Dreamweaver world and make it work in a SharePoint world by using the Dreamweaver tool and the new Design Manager features in SharePoint 2013. In that respect I think we’ve walked through it pretty well. In a perfect world we would have put more of the stuff that’s in the master page right now into the layout page. For example, if you make this master page the System Master Page you will probably find yourself not happy; here’s an idea of what your forms and settings pages look like when you do that (this is the Site Settings page):
Yikes! Trying to fix the master page back is pretty much impossible to do in the UI at this point. Fortunately you can run this little PowerShell snippet to set it back to the out of the box master page:
$w = Get-SPWeb http://yourWebApp
$w.MasterUrl = "/_catalogs/masterpage/v15.master"
For my second point I’m actually going to switch gears and switch to a different master page. Let’s take a look at my sample Contoso master page:
Looks good enough, right? Nothing fancy, but it has the basic elements of a site. But let’s make it the System Master Page and then go into the settings for a list or library:
Notice anything missing? The breadcrumb that you normally see on top of the List Information section, that allows you to click to go back to the list contents, is missing. Here’s why I point this out – if you go to the Snippets page, you will not find breadcrumb code there that can be used for this. The Snippets page has a lot of good code, but it’s not meant to cover every single control for every single situation. So how do we fix this? Well, when you can’t find what you need in the Snippets page, you’re going to need to crack open the v15.master file and find your code snippets out of there. This is what the code looks like in the v15.master that’s responsible for this breadcrumb:
<SharePoint:AjaxDelta id="DeltaPlaceHolderPageTitleInTitleArea" runat="server">
<asp:ContentPlaceHolder id="PlaceHolderPageTitleInTitleArea" runat="server">
<SharePoint:ThemedForegroundImage ThemeKey="spcommon" ImageUrl="/_layouts/15/images/spcommon.png" CssClass="ms-pageTitle-separatorImg" runat="server" />
Now if you just try to copy and paste this into your HTML master page it won’t work; that’s because this contains ASP.NET markup, and we’re working with an HTML page. SharePoint 2013 uses special tags that allow you to “wrap” your ASP.NET tags in so that it knows how to update the .master page it created that is “paired” to your HTML page. To do this, you put your ASP.NET markup in comment tags; start tags you precede with “MS:” and closing tags you precede with “ME:”. Here’s what this same code looks like with these wrappers put around them, and this is what I’ll paste into my HTML master page:
<!--MS:<SharePoint:AjaxDelta id="DeltaPlaceHolderPageTitleInTitleArea" runat="server">-->
<!--MS:<asp:ContentPlaceHolder id="PlaceHolderPageTitleInTitleArea" runat="server">-->
<!--MS:<SharePoint:SPTitleBreadcrumb runat="server" WelcomePageUsesWebTitle="false" DefaultParentLevelsDisplayed="3" ParentLevelsDisplayedInFolder="3" RenderCurrentNodeAsLink="true" SiteMapProvider="SPContentMapProvider" CentralAdminSiteMapProvider="SPXmlAdminContentMapProvider">-->
<!--MS:<SharePoint:ThemedForegroundImage ThemeKey="spcommon" ImageUrl="/_layouts/15/images/spcommon.png" CssClass="ms-pageTitle-separatorImg" runat="server" />-->
Now that I’ve pasted this into the master, we can see how this brings the breadcrumb back into the list settings page:
With that I’ll wrap up this very lengthy post. You had a chance to see how the new Design Manager features of SharePoint 2013 lets you use your favorite HTML editor to do every day content management tasks. We were able to rebuild the Dreamweaver tutorial site in SharePoint 2013 using Dreamweaver, which is a great step forward from previous versions of SharePoint. I also showed how to use features like the Snippets gallery to add SharePoint features to your master pages, and also what to do when you need a feature that you can’t find in the Snippets. In addition, this same methodology of using your favorite HTML editor can be used for another important SharePoint 2013 feature called display templates. Those are used mostly with search results, but search is so well integrated in this version of SharePoint that you will find lots of uses for them. Look on this blog site for a comprehensive run through of building a solution using query rules and result types.
The attachment to this post contains the nicely formatted Word version of this posting, along with the source elements I used to create the final SharePoint version of the Dreamweaver tutorial site.