Creating custom themes and master pages

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

Do the following to make your new theme or master page available in RiSE:

  1. Add a new theme folder to the App_Themes folder, located by default in C:\Program Files (x86)\ASI\iMIS\Net\App_Themes. Refer to Creating a custom theme for more information about the files you will need to add to this folder, as well as other information about custom themes.
  2. Add the new master page to the MasterPages folder, located by default in C:\Program Files (x86)\ASI\iMIS\Net\Templates\MasterPages. Refer to Creating a custom master page for more information about the required elements you will need in your custom master page.

After you add the theme folder and master page to these locations, you can select both on the Look and feel tab when editing a website in RiSE.

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 except replacing [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="Austin_Responsive" 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 one of our theme’s .skin files and customize it as needed (each theme folder within /App_Themes contains skin files you can use for this purpose). When you upgrade, you should compare your theme’s .skin files with those in a provided theme. 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. We recommend 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 according to your needs.

Associating a thumbnail with a custom theme is not required, but you do have the option. Once you select yout 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 it ThemeScreenshotSmall.png.
  3. Upload it to the App_Theme/[ThemeName]/images folder.

    4. Note: If not thumbnail is provided, a generic thumbnail image will appear. 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.

  1. Navigate 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.

  1. Navigate to RiSE > Site Builder > Manage websites.
  2. Select the website to apply the custom theme.
  3. (Look and feel tab) Select your custom theme as the Theme (colors, fonts, etc.) to use for the site's look and feel.
  4. Save your changes.

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 master page elements that are required for your website to display correctly. To see an example of how to fully implement each of these, search of the relevant IDs (or other provided strings) within one of the sample master pages located in the ~/Templates/MasterPages folder.

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

<%@ 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 master pages 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 go in the page. They 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 master pages:

  • TemplateHead – Inserts iMIS metadata into the page. Include this placeholder within the <head> tags of your master page.
    • <asp:ContentPlaceHolder ID="TemplateHead" runat="server" />
  • SideBarPlaceHolder – Most often displays on the left- or right-hand side of the page and is used to display some controls such as the community navigation control. It also may 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 properly display 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 different navigation controls are available that can be used to display different styles of navigation. 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 master pages, 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 master page 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 hides 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>

    Note: In addition, define the ProgressImage2Load method in your master page’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" />

    Note: 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 box before the user selects the box
    • 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 master page 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 master pages 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 master pages, 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 their 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 master page because they allow you to insert RiSE-built content into your master page 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.

  1. To add one or more Content Template Areas, first declare them in an EnsureContentAreas() method in your master page.
    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. Next, for each content area you want to add, place a ContentTemplateArea control in your master page 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 definition, you should have a defined location for all of your template content (for example, go to Site Builder > Manage websites, select a website, go to Look and feel > Folder containing template content). Create your content within this folder (go to Page Builder > Manage content).
    2. In the Properties tab of the content record, enable This content is part of the site’s template design.
    3. 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.

  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 master page.
    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 may also want to include some C# properties and methods in your master page. These should go in the <script language="C#" runat="server"></script> at the top of your master page. 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 may 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 master page. 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 master page. 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. Example:

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