Skip to main content

Best Practice: Intermediate Self-service Branding

This page applies to:MindTouch Responsive

Use these custom CSS best practices to make your site beautifully branded and responsive.

Put CSS in the control panel

There are a couple reasons why your Custom CSS should be in the Control Panel. First reason is that you can't use LESS in page templates. Only LESS entered into the Control Panel's Custom Site CSS will render correctly. Don't miss out on all the new functionality available. The second reason is that the custom header and footer templates are not rendered in mobile view. This means that any CSS you've added to them will not be rendered.

Don't use CSS hacks

The need for CSS hacks has been removed in MindTouch Responsive. There are now several custom classes injected into the <body> tag that will allow you to customize your CSS by browser and platform. For more information about the new <body> classes in MindTouch Responsive please read the our article on custom <body> classes.

Recommended media queries

In MindTouch Responsive the responsive break points have already been calculated for you based on the general sizes of popular phones, tablets, laptops, and desktops. When creating your custom styles, sticking to the pre-existing media queries will make your viewers experience more consistent since all the break points will match up. A full list of the media queries used in MindTouch Responsive can be found here. If you do need to create a new media query, be sure to use a responsive measurement (ex: em's, rem's, %) instead of pixels.

Use responsive measurements instead of pixels

Pixels are fixed units of measure and do not change size in different screen dimensions or when the font size increases. This makes them a poor choice for responsive designs. It is better to use responsive measurements such as em's, %, and rem's that will scale to the screen size no matter the device.

Don't forget about your pseudo classes

A pseudo class is a special state of an element. The most recognizable pseudo classes are the ones used for links such as :visited, :hover, :active, and :focus. There are LESS variables and mixins that will generate these pseudo classes for you in regards to primary, secondary, and tertiary link colors. If you make changes to any link styling in the Control Panel, make sure you also update the styles for the pseudo classes. Forgetting about how a :focus or :hover should look can cause difficulty for users who navigate by keyboard only and those on touch screen devices.

If the user's platform is not touch based, then an additional class name of .no-touch will be added. This class name is responsible for all :hover affects on devices without touch screens and should be prefixed onto all CSS selectors referencing this pseudo class. The .no-touch class is required because of an issue with :hover and iOS. For more information about this technical issue please read the article Solving The Double Tap Issue on iOS Devices.

Custom templates

When implementing a custom header, footer, or login message it is best to remember these guidelines.

Put your scripts in the control panel

Because the custom header and footer are not loaded on mobile devices, custom scripts will need to be added into the Control Panel's Custom HTML so they will work in all devices. Custom HTML can be used to include third party widgets, links to additional CSS files, and unique meta tags. Additional information can be found in our article about custom HTML.

Reusable components

MindTouch comes with a few reusable components such as horizontal navigation, drop-downs, and several container styles. Making use of these components will save you time when creating custom headers, footers, and content.

A horizontal navigation menu is as easy as adding the proper HTML structure and class names. All responsive resizing is calculated in the product CSS.

<nav class="elm-nav my-custom-class">
    <div class="elm-nav-container">
            <li><a href="#">Link one</a></li>
            <li><a href="#">Link two</a></li>
            <li><a href="#">Link three</a></li>
            <li><a href="#">Link four</a></li>

If you wanted to create a new drop down link you would just need to use the correct HTML structure (an <a> followed by a <ul>) and class names (.mt-dropdown-link and .mt-dropdown).

<a class="mt-dropdown-link" href="#" title="Drop-down link">Drop-down link</a>
<ol class="mt-dropdown">
        <a href="#" title="Link one">Link one</a>
        <a href="#" title="Link two">Link two</a>
        <a href="#" title="Link three">Link three</a>

For a full listing of reusable components and how to use them, please read our article on reusable components.

Use on-click instead of hover in drop-down menus

The hover technique for displaying sub-menus in content navigation does not work well on a touch screen or for users with disabilities who use a keyboard to navigate. If you decide to build your own drop-down menus, keep this in mind when you are creating the scripting for it.

Use flexbox for responsive containers in your content

MindTouch Responsive makes use of the CSS3 module Flexbox for much of it's dynamically generated page listings. These containers adapt to the space available to them rather than needing extensive CSS to control how they look at every possible size. Take a look at how the Documentation category page's dynamic listings adjust when you resize the browser window.

If you don't already know how to use Flexbox, try out this interactive tutorial called Flexbox in 5 minutes.

Use approved sign in link

A lot of customers like to create their own header with custom links while hiding the login links from the user navigation. The correct way to create a sign in link is by using the following code sample inside your header template. By using this code for your sign in links, you can be assured that your users will be directed to the correct sign in page whether they use the default login or Single Sign On. This link will also redirect your users back to the page they were currently viewing before they signed in.

var signInUrl = '/@app/login/redirect?return=' .. Uri.Encode(page.uri);
<a href=(signInUrl) title="Sign in">"Sign in"</>

Responsive images

Previous versions of MindTouch were not responsive. The editor used in MindTouch Responsive is used for all supported versions and in so doing, adds inline height and width CSS to <img> tags to help out with formatting. In a responsive skin, this isn't helpful since the images need to resize based on the screen resolution. To make your images truly responsive, you'll need to remove these inline styles manually for images in your content to avoid image distortion.

To remove the inline CSS from images, open the editor and click the View button. Select Source and scroll down until you see an image tag, then look for the style attribute. Delete the entire inline style, then save your changes. You image dimensions will now be controlled by responsive styles.





Structure content

Proper content structuring will allow Synapse to self organize your content, influence search results, and create proper article relationships. When creating your hierarchy, you may start out at the top with a portfolio, category, or guide. The correct nesting structure for Synapse is portfolio, category, guide, then articles. If your content has numerous segmentation and you feel that this structure is not enough, then you can nest portfolios under portfolios for additional levels. It is important that you do not nest categories under categories or guides under guides so Synapse functions correctly.

Another important note about structuring your content is that all pages must have an article type set for them to ensure that they are visible in the Synapse structure. Only portfolios and categories will appear in a portfolio page's sub-page listings and only guides will appear in a category page's sub-page listings. Articles that don't have an article type set, will not appear on guide pages. These restrictions were created to make Synapse self organizing and decrease the page loading times.