Custom promo boxes in SharePoint 2013

In SharePoint 2013, it’s fairly easy to set up a list/CQWP combination that gives users a surprising amount of control over the layout and presentation of promo boxes. For instance, the setup I’m about to describe produces these variations, among others:

promo-example

The user is able to upload the background image, write the headline and text, and specify some layout variations:

  1. Where the text appears in the box (top, left or right);
  2. What color the text is (light or dark);
  3. Whether there is a transparent background behind the text.

What you need

  1. A list of promo items
  2. A custom XSLT template
  3. A Content Query Web Part (CQWP)
  4. Some CSS
  5. An appropriate Image Rendition setting

The list

  1. Title (single line of text): The headline. Should be 4 words or less.
  2. Promo URL (Hyperlink or Picture): The link the promo points to
  3. Promo Text (Multiple lines of text): The readout text for the promo. Should be 10 words or less.
  4. Promo Image (Publishing image): the background image. You’ll need to create this site column before you can add it to the list, following the instructions at Better image-upload experience.
  5. Text location (Choice): Can be anything you want; whatever is chosen is passed as a class to the HTML. This example uses “text-top”, “text-left” and “text-right”.
  6. Text background (Choice): Can be anything you want; whatever is chosen is passed as a class to the HTML. This example uses “white” and “blank”
  7. Text color (Choice): Can be anything you want; whatever is chosen is passed as a class to the HTML. This example uses “light” and “normal”.

The XSLT template

  1. Open the ItemStyle.xsl file (Style Library -> XSLT Style Sheets)
  2. Add the following template somewhere after the default template:
<xsl:template name="HomePagePromo" match="Row[@Style='HomePagePromo']" mode="itemstyle">
    <xsl:variable name="SafeLinkUrl">
        <xsl:call-template name="OuterTemplate.GetSafeLink">
            <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
        </xsl:call-template>
    </xsl:variable>
    <xsl:variable name="SafeImageUrl">
        <xsl:call-template name="OuterTemplate.GetSafeStaticUrl">
            <xsl:with-param name="UrlColumnName" select="'ImageUrl'"/>
        </xsl:call-template>
    </xsl:variable>
    <xsl:variable name="DisplayTitle">
        <xsl:call-template name="OuterTemplate.GetTitle">
            <xsl:with-param name="Title" select="@Title"/>
            <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
        </xsl:call-template>
    </xsl:variable>
    <xsl:variable name="TextLocation">
        <xsl:value-of select="@TextLocation" />
    </xsl:variable>
    <xsl:variable name="TextBackground">
        <xsl:value-of select="@TextBackground" />
    </xsl:variable>
    <xsl:variable name="TextColor">
        <xsl:value-of select="@TextColor" />
    </xsl:variable>

    <div class='media promo {$TextLocation} {$TextBackground} {$TextColor}'>
        <a href="{$SafeLinkUrl}" title="{@LinkToolTip}">
            <img class="image" width="240" height="136" src="{$SafeImageUrl}" alt="{@ImageUrlAltText}" title="{@ImageUrlAltText}" />
            <div>
                <h4><xsl:value-of select="$DisplayTitle"/></h4>
                <p><xsl:value-of select="@Description" disable-output-escaping="yes" /></p>
            </div>
        </a>
    </div>
</xsl:template>

The template defines three custom variables (TextLocation, TextBackground and TextColor”) and adds them as a class to the div that wraps each item (which also carries the classes “media promo”).

Inside that div is an <a> tag containing the promo’s link. We’ll use CSS to make that <a> tag cover the entire div, so the entire div becomes clickable.

Then there’s an <img> tag that takes the item’s “Promo Image” as its source; we’ll use CSS to position it in the background.

Finally there’s a “media-body” div containing the headline and description text.

The CQWP

Add a CQWP and configure it as shown below (unneeded fields aren’t necessarily shown):

home-page-promo-CQWP-settings

The CSS

Most of this is simply conditional styling. Change to suit. The only things that are truly structural are the “position” and “overflow” calls, and making sure heights and widths match up. This CSS produces a promo box that is 242×138 (including a 1px border).

.media.promo {
    min-height: 138px;
    position: relative;
}
.media.promo img {
    border: 1px solid #B3B3B3;
}
.media.promo img, .media.promo .media-body {
    position: absolute;
}
.media.promo a {
    color: #59452A;
    display: block;
    min-height: 138px;
    overflow: hidden;
}
.media.promo.light a {
    color: #FFFFFF;
    text-shadow: 1px 1px 1px #000000;
}
.media.promo h4 {
    font-family: Arial,Helvetica,sans-serif !important;
    font-weight: normal;
    letter-spacing: 1px;
    margin-bottom: 0;
    text-transform: none;
}
.media.promo .media-body {
    font-size: 11px;
    letter-spacing: 1px;
    line-height: 14px;
    margin: 1px 0 0 1px;
    max-width: 220px;
    min-width: 220px;
    padding: 10px;
}
.media.promo .media-body p {
    margin-bottom: 0;
}
.media.promo.text-left .media-body p {
    width: 40%;
}
.media.promo.white .media-body {
    background: none repeat scroll 0 0 rgba(255, 255, 255, 0.8);
}
.media.promo.white.text-left .media-body {
    min-height: 116px;
    width: 82px !important;
}
.media.promo.white.text-left .media-body p {
    width: 100%;
}

Image rendition

To ensure that images are uploaded at the proper size and shape, set an Image Rendition for the promo image, and then instruct your users to choose it when uploading Promo images.

  1. Make sure the site is set up for Image Rendition. Mostly this involves making sure BLOB Caching is enabled.
  2. Go to “Site Settings”
  3. Under “Look and Feel”, click “Image Renditions”
  4. Click “Add New Item”
  5. Name the Rendition something helpful — like “Home Page Promo (240×136)”.
  6. Set the width to 240
  7. Set the height to 136.
  8. Click “Save”.

The rendition will now be available as an option when the user uploads an image.

Categories: App Development and Business Productivity.