Creating custom themes and templates using code

You can create your own themes if you need to have greater creative control over your website design. This section covers the basic pieces required to build your own theme.

Whenever possible, we highly recommend using one of the out-of-the-box master pages we provide for your website. Doing so helps us to better support your site and it will make upgrading your site simpler. However, if you need to create a custom master page, you have a choice: either start with a copy of an existing master page and adjust or remove items as needed; or start with a new page and build it piece-by-piece to add the required items. Either way, start by adding your .master file to the ~/Templates/MasterPages folder so that it shows up in the master page drop-down list in Manage websites.

This section describes the required and optional portions of a custom master page.

The following section describes the required template elements that are necessary for your website to display correctly. To see an example of how to fully implement each of these elements, search of the relevant IDs (or other provided strings) within one of the sample templates located in the ~/Templates/MasterPages folder.

The following is an example of the basic structure of a custom template:

<%@ Master Language="C#" Inherits="Asi.Web.UI.UltraWaveMasterPageBase" %>
<!-- import and register statements go here -->
 
<script language="C#" runat="server">
    <!-- C# scripts go here -->
</script>
<html id="MainHtml">
    <head id="Head1" runat="server">
        <!-- head content goes here -->
    </head>
    <body id="MainBody">
        <form id="TemplateForm" method="post" runat="server">
            <header>
                <!-- header content goes here -->
            </header>
            <div id=”bd”>
                <!-- content goes here -->
            </div>
            <footer>
                <!-- footer content goes here -->
            </footer>
        </form>
   </body>
</html>

All UltraWave-based templates must inherit from UltraWaveMasterPageBase by including the following line at the top of the .master file:

<%@ Master Language="C#" Inherits="Asi.Web.UI.UltraWaveMasterPageBase" %>

Content placeholders define where certain types of content should be placed in the page. Placeholders are used to define header metadata, the main content area, and the JavaScript that loads at the bottom of the page. The following content placeholders are required for all templates:

  • TemplateHead – Inserts iMIS metadata into the page. Include this placeholder within the <head> tags of your template.
    • <asp:ContentPlaceHolder ID="TemplateHead" runat="server" />
  • SideBarPlaceHolder – Displayed most often on the left- or right-hand side of the page and is used to display controls, such as the community navigation control. It also might contain the sub-navigation control if you choose to implement it (see Displaying left navigation). 
    • <asp:ContentPlaceHolder ID="SideBarPlaceHolder" runat="server">
  • TemplateUserMesages – Displays error, warning, information, or success messages at the top of the page. Make sure to add this within an update panel so that the messages are displayed properly on post back.
    • <asp:ContentPlaceHolder ID="TemplateUserMessages" runat="server">

  • TemplateBody – Displays the main content of the page.
    • <asp:ContentPlaceHolder ID="TemplateBody" runat="server">
  • TemplateScripts – Loads JavaScript from Page.RegisterStartupScript.
    • <asp:contentplaceholder id ="TemplateScripts" runat="server"></asp:contentplaceholder>

Four unique navigation controls are available that can be used to display different navigation styles. Choose the navigation controls that best fit your needs.

  • NavigationList – Displays a simple list-style navigation that is limited to a single level. In the iMIS templates, it is used to display the Auxiliary and Footer navigation. 
    • <asiweb:NavigationList ID="Auxiliary" runat="server" NavigationPaneCode="4" 
AnonymousOnly="<%# IsAnonymous %>"/>
    • NavigationPaneCode identifies the navigation area to display. In this example, it is the auxiliary navigation. This code is defined in navigation areas.
    • AnonymousOnly works in conjunction with the IsAnonymous property in the scripts section to determine when to hide anonymous-only links.
  • PageNavR – Displays the primary navigation. A register statement is required at the top of your template from this control.
    • The register statement:
      • <%@ Register TagPrefix="asi" TagName="PageNavR"
 Src="~/AsiCommon/Controls/Navigation/PageNavR.ascx" %>
    • The control:
      • <asi:PageNavR ID="Primary" runat="server" NavigationPaneCode="1"
 StartFromRootNode="true" SelectDefaultNode="true" />
      • NavigationPaneCode – Currently only "1" is supported for this control.
      • StartFromRootNode – Currently only "true" is supported for this control.
      • SelectDefaultNode – Currently only "true" is supported for this control.
  • SubNavigation – Displays second-level navigation. See Displaying left navigation.
  • Breadcrumb – Displays the breadcrumb trail of the current page. This control is hidden dynamically if the website is not configured to display breadcrumbs.
    • <asiweb:SiteMapPath ID="BreadCrumb" runat="server"
 SiteMapProvider="AsiSiteMapProvider">
    <NodeTemplate>
        <asp:HyperLink ID="NodeLink" runat="server" NavigateUrl='<%# Eval("Url")
 %>' Text='<%# Eval("NavigationHierarchy.Navigation.BreadCrumbName") %>'
 CssClass="BreadCrumbLink"></asp:HyperLink>
    </NodeTemplate>
    <CurrentNodeTemplate>
        <asp:Label ID="CurrentNodeLabel" runat="server" Text='<%#
 Eval("NavigationHierarchy.Navigation.BreadCrumbName") %>'></asp:Label>
    </CurrentNodeTemplate>
</asiweb:SiteMapPath>
    • NodeTemplate – The template used to display links in the breadcrumb.
    • CurrentNodeTemplate - The template used to display the navigation name of the current page.
  • RadScriptManager – Combines multiple Telerik scripts into a single HTTP request.
    • <telerik:RadScriptManager ID="ScriptManager1" runat="server" EnableCdn="false"
 EnablePageMethods="true" EnablePartialRendering="true"
 EnableScriptGlobalization="true" EnableHistory="true"
 EnableSecureHistoryState="false" AsyncPostBackTimeout="3600" />
  • UpdateProgress – Displays a visual indicator of loading progress.
    • <asp:UpdateProgress ID="TemplateFillLoadingPanel" runat="server" Visible="true">
    <ProgressTemplate>
        <div class="NotPrinted ProgressDiv" id="FillProgressDiv">
            Loading 
            <asp:Image ID="ProgressImage2" runat="server"
 OnLoad="ProgressImage2Load" AlternateText="Loading" />                          
        </div>  
    </ProgressTemplate>
</asp:UpdateProgress>

    In addition, define the ProgressImage2Load method in your template’s C# scripts, as in the following:

    protected void ProgressImage2Load(object sender, EventArgs e)
    {
        Image image = sender as Image;
        if (image != null)
            image.ImageUrl = Asi.Web.Utilities.GetTildeExpansion() +
 "/images/ImageLibrary/loading.gif";
    }
  • Sign In/Sign Out Link – Displays a link to allow the user to sign in or out of the website.
    • <asp:LoginStatus ID="LoginStatus1" runat="server" LoginText="Sign In"
 LogoutText="Sign Out" AccessKey="l" OnLoggedOut="LoginStatus1_OnLoggedOut"
 OnPreRender="LoginStatus1_OnPreRender" />

    In addition, define the methods for OnLoggedOut and OnPreRender, as in the following:

    protected void LoginStatus1_OnLoggedOut(object sender, EventArgs e)
    {
        Asi.Web.Security.RevokeAppContext(HttpContext.Current);
        if (Page is Asi.Web.UI.DisplayPageBase &&
 ((Asi.Web.UI.DisplayPageBase)Page).iMISWebsite != null)
            Response.Redirect(((Asi.Web.UI.DisplayPageBase)Page).iMISWebsite.WebsiteLink,
 true);
        else
            Response.Redirect(FormsAuthentication.LoginUrl, true);
    }
    protected void LoginStatus1_OnPreRender(object sender, EventArgs e)
    {             
        // Make Sure that Logoff and Log On Text is set properly 
        if (!AppContext.CurrentIdentity.IsAuthenticated)
            LoginStatus1.LogoutText = ResourceManager.GetPhrase("Security.SignOut",
 "Sign Out");
    }
  • Universal Search field – Allows the user to search the entire website for content, a product, an event, and other indexed items.
    • <asiweb:SimpleSearchField ID="SearchField" runat="server"
 AdvancedLinkVisible="false" PromptText="Keyword Search" />
    • PromptText – The text that appears in the search field before the user begins using the search field.
    • AdvancedLinkVisible – Currently only "false" is supported for this control.
  • Easy Edit toggle – Displays a button to allow staff and Content Authority Group members to turn Easy Edit on and off.
    • <asp:ContentPlaceHolder ID="AuxiliaryNavigationSupplementalContent" runat="server" />
  • Keep Alive – Increases performance by helping the client keep a single session running. 
    • <asp:Image ID="KeepAliveTarget" runat="server"
 ImageUrl="~/AsiCommon/Images/3x3.gif" AlternateText=" " />
<asiweb:KeepAliveExtender ID="KeepAliveControl" runat="server"
 TargetControlID="KeepAliveTarget" />
  • On Behalf Of – Displays the visual control and indicator that allows users with On Behalf Of rights to set or clear the On Behalf Of target.
    • <asi:ProxyPanel id="panProxy" runat="server"
 TargetContactProfileShortcut="~/Party.aspx" ></asi:ProxyPanel>
    • TargetContactProfileShortcut – The shortcut or URL for the link on the contact’s name. If not included, this property defaults to ~/Party.aspx.
  • Button Bar – Displays action buttons (for example, save, submit, or cancel) when there is a form on the page.
    • <asiweb:CommandButtonBar ID="ButtonBar" runat="server" TargetControlID="ContentDiv" />

    Also works in conjunction with a placeholder, which can be used to add additional content next to the buttons.

    <asp:ContentPlaceHolder ID="TemplateButtonBar" runat="server">

The following section describes some of the optional template elements. To see an example of how to fully implement each of these, search the relevant IDs (or other provided strings) within one of the sample templates located in the ~/Templates/MasterPages folder.

Add the following optional controls to increase the accessibility of your website:

  • Skip Links – Helps screen readers and tab-only users skip over repetitive content, such as the header.
    • <a href="#contentstart" class="screen-reader-text show-on-focus">
Skip to main content</a>
  • href - Make sure this links to the ID of your main content area or to an anchor at the top of the content area. For example:
    • <a id="contentstart" tabindex="-1"></a>
    In our example templates, we also include a skip link around the breadcrumb. If you choose to do this, be sure to hide the link dynamically if the breadcrumb is hidden.

  • Maintain Focus on Post Back – Sometimes when the page refreshes, screen readers and tab users lose their focus on the page and have to navigate back to their desired location. By including an optional control to remember the last-focused element, you can fix this behavior.
    • <input type="hidden" id="lastClickedElementId" runat="server"/>

Content Template Areas are a very powerful tool for your template because they enable you to insert RiSE-built content into your template wherever you need it. The content can be controlled separately in each website, making it useful for logos, links to your organization’s social networking pages, and footer copyright statements.

Do the following to add one or more Content Template Areas:

  1. Declare the Content Template Areas in an EnsureContentAreas() method in your template.
    2. override protected void EnsureContentAreas()
{
    PageContentAreas = new List<ContentTemplateArea>(
        new[] { HeaderLogo });
}

    Include the IDs of all content areas for your website in a comma-separated list within the array.

  2. For each content area you want to add, place a ContentTemplateArea control in your template where you want the content to display.
    3. <asiweb:ContentTemplateArea ID="HeaderLogo" TemplateAreaName="HeaderLogo"
 HonorContentRecordLayout="true" runat="server" />
    • TemplateAreaName – The name used to identify this content area.
    • HonorContentRecordLayout – Determines whether to include the grid layout used in your content definition.
  3. Define the content to be displayed within the ContentTemplateArea:
    1. In your website configuration, define a location for all of your template content:
      1. Go to Site Builder > Manage websites.
      2. Select a website.
      3. (Look and feel tab) Select a Folder containing template content. Create your content within this folder.
    2. Go to Page Builder > Manage content and create or edit a content record.
    3. (Properties tab) Enable This content is part of the site’s template design.
    4. Enter the same name you used for the ContentTemplateArea control’s TemplateAreaName.

You can also define content areas that display only on the home page or only on interior pages. Do the following:

  1. In EnsureContentAreas(), identify the content areas as either HomepageContentAreas or InteriorContentAreas.
    2. override protected void EnsureContentAreas()
{
    HomepageContentAreas = new List<ContentTemplateArea>(
        new[] { HomepageContentArea1 });
    InteriorContentAreas = new List<ContentTemplateArea>(
        new[] { InteriorContentArea1 });
}
  2. Include the ContentTemplateArea as in normal content areas.
    3. <asiweb:ContentTemplateArea ID="HomepageContentArea1"
 TemplateAreaName="HomepageContentArea1" HonorContentRecordLayout="true"
 runat="server" />
  3. Also include a required HomePageContent panel or InteriorPageContent panel on the template.
    4. <asp:Panel ID="HomePageContent" runat="server" Visible="false" />
<asp:Panel ID="InteriorPageContent" runat="server" Visible="false" />
  4. Define the content to be displayed with the ContentTemplateArea (see Content Template Areas).

You might also want to include some C# properties and methods in your template. These should be placed in the <script language="C#" runat="server"></script> line at the top of your template. You might want to include the following:

  • CartItemCount (property) – Defines a template used to display a cart count indicator in the auxiliary or footer navigation. Replaces [CartItemCount] in the navigation text (see Modifying dynamic navigation items).
    • /// <summary>
/// Return the count of items in the Cart
/// </summary>
public string CartItemCount
{
get
{
return GetCartItemCount();
}
}
  • OverrideLinkText (property) – Defines text that replaces [OverrideLinkText] in navigation text. It is typically used to display the logged-in user’s name (see Modifying dynamic navigation items).

    For example, instead of displaying the Full Name of the logged-in user, you might want to display only their First Name. To make this change, edit the ContactDetail property to replace all instances of FullName with FirstName. The result should look like this:

    /// <summary>
  /// Logged-in contact
  /// </summary>
  public string OverrideLinkText
  {
        get
        {
            return Asi.Business.Contact.Contact.GetCachedFirstName(AppContext.CurrentIdentity.UserKey, 
AppContext.CurrentContext.StatefulBusinessContainer);
        }
  }

    Note: The GetCachedFirstName method is used, rather than the default GetCachedFullName.

  • IsAnonymous – Used in conjunction with NavigationListControl, this determines who should be allowed to see anonymous-only links.

If you are licensed for iMIS Translation, you can activate the translation drop-down to appear as apart of the template. For more information, see Language translation.

  • PageTasks – Displays buttons to allow users to email the page to a friend, print the current page, or set the "Text Only" mode.
    • <asp:Panel ID="PageTasksPanel" runat="server" CssClass="PageTasksPanel NotPrinted">
    <asp:ContentPlaceHolder ID="TemplatePageTasks" runat="server"></asp:ContentPlaceHolder>
</asp:Panel>

    You can selectively turn off any of these buttons by including one or more of the following statements in the overridden CreateChildControls() method:

    ShowTextOnly = false;
ShowEmailAFriend = false;
ShowPrintThisPage = false;
  • Dynamic Content Items – You can also include dynamic content items in your template. Simply register them and include them as you would any other control.

  • data-height-offset="true" – Add this attribute to any control that adds height to the page. It is used when determining the remaining height on the page available to controls such as the Object Browser. For example:

    <header id="hd" data-height-offset="true">
    ...
    </header>

Themes control the layout, font, and colors of your iMIS sites. The Quick Start Sites come with a set of themes designed for RiSE sites. For examples, see Using out-of-the-box themes.

Creating a copy of a theme also ensures that you do not compromise your ability to access a working backup. Follow these steps to copy a theme, which is easier than creating a theme from scratch.

Note: Themes change and develop with every iMIS update. To avoid losing your changes, be sure to work from a copy of the theme.

  1. Copy an out-of-the-box theme and master page to be unique to your new site:
    1. Locate the theme folder (such as \Austin), which defaults to C:\Program Files (x86)\ASI\iMIS\Net\App_Themes.
    2. Copy, paste, and rename \Austin to your new site name, for example, \ABC.
    3. Locate the master page (such as Cities.master), which defaults to C:\Program Files (x86)\ASI\iMIS\Net\Templates\MasterPages.
    4. Copy, paste, and rename Cities.master to your new site name, for example, ABC.master.
  2. Go to RiSE > Site Builder > Manage websites.
  3. Edit your site to use your new theme files:
    1. Highlight your site (ABC).
    2. (Look and feel tab) Edit the site to point to your new theme files:
      • Theme: Select ABC from the drop-down.
      • Template (master page): Select ABC from the drop-down. You can also select the ABC master page for the following fields:
        • Template (master page) to use for "Print this page"
        • Template (master page) to use for text only
        • Template (master page) to use for pop-ups
    3. Save and Publish.

Themes control many of the aesthetic elements of your website, such as fonts and colors. To create a personalized theme for iMIS, copy an out-of-the-box theme and customize it to fit your organization's needs. If you want greater creative control over the look and feel of your website, you can build a new theme.

When you create a new theme, it must contain the following required elements:

You will save all of your custom theme's required elements to your theme folder located in ~/App_Themes. Then, to use the new theme in a specific website, you must select the theme in the Look and feel definition of the website.

The theme CSS files control the styles displayed within your website. It is easiest to start from a copy of another theme’s CSS files, but you also have the option to build your own. When designing your custom CSS, test thoroughly to confirm you include the selectors required for iMIS to display as you prefer.

To learn more about CSS, visit www.w3schools.com.

The required base style sheet, UltraWave, is dynamically included in any theme based on its ThemeSettings.xml file. To ensure these styles are included in your theme, add a ThemeSetting.xml file to your theme folder with content similar to the following example (replace [ThemeName] with your theme's name).

 

Example: <?xml version="1.0" encoding="utf-8" ?>
<ThemeSettings ThemeID="[ThemeName]" UltrawaveBased="True">
</ThemeSettings>

If your theme is responsive, also include the property Responsive="True" in your theme settings.

 

Example: <?xml version="1.0" encoding="utf-8" ?>
<ThemeSettings ThemeID="[ThemeName]" UltrawaveBased="True" Responsive="True">
</ThemeSettings>

Skin files contain property settings for controls such as buttons, labels, and grids. Each theme must have a skin file that includes several required elements so that these controls render correctly in your website. We recommend that you start with a copy of an iMIS theme’s .skin files and customize as needed (each theme folder within /App_Themes contains skin files you can use for this purpose). If you upgrade, you should compare your theme’s .skin files with those in a theme provided in the upgrade. Be sure to copy over any missing lines.

There are several images required for a theme to display properly, including images for icons, user messages, and other elements. Many of the required images are referenced in the .skin files. It is recommended that you copy an images folder from one of the existing themes into your custom theme folder. You can replace or edit any of these images.

Associating a thumbnail with a custom theme is not required, but you have the option to do so. Once you select your theme in the Advanced section of the Look and feel tab, your thumbnail will appear in the Website theme section. To associate a thumbnail with a theme, do the following:

  1. Take a screenshot of your theme.
  2. Name the image ThemeScreenshotSmall.png.
  3. Upload the image to the App_Theme/[ThemeName]/images folder.

    4. Note: If no thumbnail is provided, a generic thumbnail image is displayed. We recommend resizing the screenshot to 300px by 200px, or 600 px by 400px.

In order to make your custom theme accessible from RiSE, you must save its required elements to the ~/App_Themes folder.

Do the following:

  1. Go to C:\Program Files (x86)\ASI\iMIS\Net\App_Themes.
  2. Add a new theme folder to the App_Themes folder.
  3. Save your custom theme's CSS files, ThemeSettings.xml file, .skin files, and image files to this folder.

To use your new custom theme, you must apply it to a website.

Do the following:

  1. Go to RiSE > Site Builder > Manage websites.
  2. Select a website.
  3. (Look and feel tab) In the Advanced area, select your custom theme from the Theme drop-down.
  4. Save your changes.