1.800.323.3639 | Support | Training

Avtex

Adding a custom control to a SharePoint 2013 master page

| No Comments

With SharePoint 2013, Microsoft introduced the concept of an HTML-only version of a master page. The idea was to let designers focus on HTML/CSS without having to deal with the underlying server-side code.

To make that work, SharePoint takes any HTML file placed in the masterpage gallery and generates a .master file from it. Designers can use any HTML structure they want, and drop in something called “snippets” to represent pieces of functionality, such as a navigation menu or a search box.

Those snippets are actually code that is commented out, using a special set of comment markers that spell out what each part of the snippet does.

That works great as far as it goes, but it’s not always obvious what those comment markers mean. In particular, it’s not obvious how to add a custom-built control to the page.

How comment markers work

There are four main types of comment markers:

Straight comments

These are comments that are ignored by SharePoint. They’re there to help humans who are reading the code. They have two parts: a starting line and an ending line:

                <!--CS: Start demo snippet-->
                 <!--CE: End demo snippet-->

“CS” stands for “Comment Start”. “CE” stands for “Comment End”.

SharePoint Markup comments

Use these to indicate Register tags for controls. Each line is individually commented out:

                       <!--SPM:<%@Register TagPrefix="Avtex" Namespace="Avtex.Demo.Controls" Assembly="Avtex.Demo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=99999999999" %>-->

Snippets keep all the code for a control in one place, so it can be added/removed as a block. One logical but easily overlooked consequence of that is that custom Register tags are not placed at the top of the page, as they usually are in .NET; they are included within the snippet:

                <!--CS: Start demo snippet-->
                       <!--SPM:<%@Register TagPrefix="Avtex" Namespace="Avtex.Demo.Controls" Assembly="Avtex.Demo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=99999999999" %>-->
                <!--CE: End demo snippet-->

Markup comments

These are used to identify lines of .NET markup.  As with straight comments, there needs to be a beginning and an end:

                       <!--MS:<Avtex:Demo runat="server">-->
                       <!--ME:</Avtex:Demo>-->

Preview comments

This identifies sections of code that are HTML previews of what the control produces.

                       <!--PS: Start of READ-ONLY PREVIEW (do not modify) -->
                       <!--PE: End of READ-ONLY PREVIEW-->

They can be useful for examining the control’s output in a client-side editor such as Firebug. However, do not edit the preview code in the HTML file. It has no effect on the real page, and only serves to mislead people about what the control looks like.

Putting it all together: Adding a custom control

So to add a custom control to your HTML master page, just wrap your Register tag in an <!–SPM comment, and pair it with the custom control wrapped in <!–MS and <!– ME comments:

                <!--CS: Start demo snippet-->
                       <!--SPM:<%@Register TagPrefix="Avtex" Namespace="Avtex.Demo.Controls" Assembly="Avtex.Demo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=99999999999" %>-->
                       <!--MS:<Avtex:Demo runat="server">-->
                     <!--ME:</Avtex:Demo>-->
                <!--CE: End demo snippet-->

(And, of course, make sure the control has been deployed to the site and activated if it’s a feature.)

For even more detail on SharePoint markup comments, check out the MSDN article “How to convert an HTML file into a SharePoint 2013 master page“.

Let’s Talk About CX

X