Adding a custom control to a page with Design Manager

The problem

How do you add a custom control to your master page (or page layout) using the Design manager? In my first attempts I continuously got ‘Unknown server tag ‘uc1:FeedbackControl’

Quick introduction

Using the new way of creating and deploying your branding with the Design Manager needs some getting used to. The idea is:

  1. You start with a plain html page
  2. SharePoint automatically converts it to a master page (or layout page)
  3. You only edit the html page. SharePoint pushes your changes to the master page
  4. Most of the SharePoint controls and web parts can be configured and added by copy + pasting snippets into your html
  5. .NET server controls can also be placed on your page by using snippets.

In fact snippets is nothing more than a special kind of mark-up to put server controls in your html page.

But how to you add a custom control?
I created my branding with the Design Manager. I also have a Visual Studio 2012 solution with custom web parts and custom user controls.
After deploying the Visual Studio solution to my server I tried to add some of my custom user controls to the master page.  All attempts I made resulted in “Unknown server tag”

Defining your control.
<!--SPM:<%@ Register Src="~/_controltemplates/15/AmToPm.Client.Intranet/FeedbackControl.ascx" TagPrefix="uc1" TagName="FeedbackControl" %>-->
Putting your control on your page.
<!--CS: Start Create Snippets From Custom ASP.NET Markup Snippet-->
<!--SPM:<uc1:FeedbackControl runat="server" id="FeedbackControl" />-->
<!--CE: End Create Snippets From Custom ASP.NET Markup Snippet-->

The solution

The trick is easy. Instead of registering your control on top of the html together with all the default SharePoint controls. You need to put the @Register statement and your code together

<!--SPM:<%@ Register Src="~/_controltemplates/15/AmToPm.Client.Intranet/FeedbackControl.ascx" TagPrefix="uc1" TagName="FeedbackControl" %>-->
<!--CS: Start Create Snippets From Custom ASP.NET Markup Snippet-->
<!--SPM:<uc1:FeedbackControl runat="server" id="FeedbackControl" />-->
<!--CE: End Create Snippets From Custom ASP.NET Markup Snippet-->

So you do NOT place the @Register-statement before the DOCTYPE declaration. Embed it directly into your html page together with your snippet.

One other tip.

I had some problems / errors with defining multiple controls with the same tag prefix. If you have multiple controls on a page give them all a different TagPrefix and you will be fine.

<!--SPM:<%@ Register Src="~/_controltemplates/15/AmToPm.Client.Intranet/FeedbackControl.ascx" TagPrefix="uc1" TagName="FeedbackControl" %>-->
<!--SPM:<%@ Register Src="~/_controltemplates/15/AmToPm.Client.Intranet/Notification.ascx" TagPrefix="uc2" TagName="Notification" %>-->
<!--SPM:<%@ Register Src="~/_controltemplates/15/AmToPm.Client.Intranet/DisplayStatus.ascx" TagPrefix="uc3" TagName="DisplayStatus" %>-->
<!--CS: Start Create Snippets From Custom ASP.NET Markup Snippet-->
<!--SPM:<uc1:FeedbackControl runat="server" id="FeedbackControl1" />-->
<!--SPM:<uc2:Notification runat="server" id="Notification1" />-->
<!--SPM:<uc3:DisplayStatus runat="server" id="DisplayStatus1" />-->
<!--CE: End Create Snippets From Custom ASP.NET Markup Snippet-->

 

8 Comments

  1. Wagner

    March 26, 2013

    That’s great Wout! But how would I insert my custom control plus some java script in the custom master page?

    • W0ut

      March 26, 2013

      JavaScript should not be a problem. No special tags are needed. You can add it directly in your master page

      You can also register custom JavaScripts by code from inside your custom usercontrol / web part
      Google for “ClientScript.RegisterClientScriptBlock()” , (or scriptManager.RegisterClientScriptBlock() if you are not working in Sharepoint)

  2. Wagner

    March 26, 2013

    Cool! Thank you W0ut!
    What about the code below? That’s the one giving me errors when I add it to the custom master page.
    <%– Themes:
    /Blue
    /Red
    /Green
    /Vivid
    /Drab –%>

  3. ĮPrime Meridian

    June 13, 2013

    how to target ascx file if Project is nested folder ?? please

  4. W0ut

    June 20, 2013

    @Meridian. See the code below. My controls are installed in the SharePoint hive in the default controltemplates folder. In the register statement you point to this path in the Src attribute:

    <!–SPM:–>

    SharePoint will automatically translate ‘~/_controltemplates’ to the correct (sharepoint installation) path on your server.

  5. Saifal Maluk

    July 17, 2014

    Hi Wout,

    I have add user control to my SharePoint 2013 html master page. the same snippet format that you have created in above, but I generating following error

    SharePoint can’t parse this file, most likely because of an incorrectly formatted SharePoint snippet. The markup at the following location is causing problems. Edit the markup manually to fix it, or replace it with a new snippet from the Snippet Gallery.

    Invalid SharePoint markup at line 145. Please repair or recreate the markup

    I have deployed my user control in 15 hive controltemplates folder and the code snippet is


    <!–SPM:–>
    <!–SPM:–>

    Please help me, what is I am missing and how the issue will resolved.

    Thanks in advance.

Comments are closed. ×

Share Your Thoughts