Customizing UI with the Theme Resource Kit

    If you need to add sophisticated view logic in your header or footer, you can do more ambitious site-wide theming by starting with the resource kit. It includes a set of sample files you can tailor to your needs.

    Note: To make the changes described here, you'll need administrator privileges. You'll need to be either a system admin or a space admin for the root space. Also, If you're looking for a very simple way to customize the UI, check out Making Simple UI Changes. For advanced theme-building, see Advanced Themes Topics.

    How This Works

    You can apply a site-wide theme by uploading the theme files in a ZIP file. Themes you upload this way will be applied globally. You don't need to use the admin console.

     

    If you're just starting out, begin with the resource kit provided. You can get the resource kit when you begin to customize your site's user interface. You get there in the user interface (if you're an administrator) by clicking Your Stuff > Customize Your Site, then following the steps in Steps for Creating Themes With the Resource Kit.

     

    When you upload the theme files, the application unzips them and copies them to your <jiveHome>/themes directory, creating a generated_advanced_skin_preview subdirectory for the files. If you change the theme and upload it again, the new theme will overwrite the previous one (although you'll be told which files will be affected before you apply the theme).

    Note: While it's possible to create themes that map to specific parts of the UI, rather than globally, this isn't the way you'd do it. For information on more advanced theming, see Advanced Themes Topics.

    Steps for Creating Themes With the Resource Kit

    Using the resource kit is an easy way to get started creating a theme. The kit is simply a set of sample files that make up a theme, arranged in the hierarchy that the application expects. Once you get started, you don't need to download the resource kit for future changes. Instead, you can download the theme you created and applied, change it, and re-upload it.

    1. Click Your Stuff > Customize Your Site to go to the Customize your site page. If you haven't customized with a theme before, the first page you'll see will be a page through which you can change color schemes and site logo. You skip past this to get to the resource kit; if you're curious about this page, see Making Simple UI Changes.
    2. screen_resource_global_theme.png.
    3. Click Find out how to create your own theme to go to the page where you can download the resource kit and develop your own theme.
    4. Click Download the Resource Kit and save the ZIP file.
    5. Expand the ZIP file to extract the theme sample files inside.
    6. Edit the source files inside as needed to customize the theme as you like.
    7. Re-compress the sampleTheme directory created when you expanded the ZIP file.
    8. Go back to the Customize your site page to upload the ZIP file with your edited theme sources.
    9. Check out the preview of the theme you created.
    10. Repeat steps 5 though 8 until you get things looking the way you want to.
    11. When you're finished with your theme, click Apply Custom Design to update your site. You'll be prompted to confirm changes to the theme. If everything's okay, click Confirm Changes at the bottom of the screen. (You don't need to restart the server or the application.)

    What the Resource Kit Includes

    The resource kit is a ZIP file containing source files with which you can create a theme to customize your site. As described below, the kit includes the source files for a sample theme. The theme is a very simple one that essentially applies the default site decoration.

     

    DirectoryDescription
    sampleThemeA directory with example source files that make up a very basic theme. You can make small changes or big ones, zip this directory and upload it to add a new site-wide theme.
    sampleTheme/imagesContains the default images to use as examples. These include favicon files and site page headers. You can replace these with your own.
    sampleTheme/stylesA CSS file with styles needed by the FreeMarker templates in this kit. You can add your own styles if you need them.
    sampleTheme/templateYour FreeMarker template (FTL) files will go in this directory. If you use other FTL files, they'll go here, too.
    sampleTheme/template/decorator/defaultContains FTL files that used unless overridden.
    source_artContains Photoshop source files with the community logo, background, and icons. Edit these to create a new images.

    Using the Included FTL Files

    FreeMarker template (FTL) files are bits of the user interface that are assembled at run time. By breaking the UI into smaller pieces, it's easier to manage UI variations (and similarities) from page to page. For example, having an FTL file that contains code for the page header makes it possible to maintain only a single file for the header, rather than copying that code to multiple files.

     

    Each FTL file in the kit has a different role in rendering the page. Each brings something different to the party, in other words. The theme you build will have its own FTL roles. The following table has a description of the each of the files. All of these files are applied globally — that is, on pretty much every page of the site.

     

    FileDescription
    header-css.ftlBrings references to the CSS stylesheets. Uses FreeMarker if/else blocks to include the right set of styles based on the context in which the page is being rendered -- such as whether the site is Jive SBS Employee or Jive SBS Public.
    header-favicon.ftlBrings links to the favicon files.
    header-meta.ftlBrings <meta> tags for the page header.
    page-footer.ftlBrings, well, the page footer. Parameters in the code provide places for the site's name and copyright information.
    page-header.ftlBrings the page header, including a link to the site header logo.

     

    Using the Included Images

    The images included in the resource kit are those used by the application by default. Use them to understanding how the UI is put together by finding references to them in other files.

     

    FileDescription
    favicon.icoLogo image used in the address bar. Linked into the page by header-favicon.ftl. Included for backward compatibility with older browsers.
    favicon.pngLogo image used in the address bar. Linked into the page by header-favicon.ftl.
    jive-hdr-bg1.pngFar right solid part of the header background. Included in the page by CSS rules in theme.css.
    jive-hdr-bg2.pngLeft blended part of the header background. Included in the page by CSS rules in theme.css.
    jive-hdr-logo-cs.pngSite logo that appears in front of the background image. Included in the page by page-header.ftl.

    Getting Started with the Kit

    You should always test your changes on a staging server — that is, a server with the site deployed but not live to everyone else. That way, you can make mistakes without interrupting those who use the site.

     

    If you're unfamiliar with theming and with FreeMarker, you might get started by trying things out on your staging server. For example, imagine you've created a new site header logo. Using the file provided in the resource kit, you could rename the header logo to use your new logo file's name and add a tag line to see what happens.

     

    Here's how that example could work.

     

    Open decorator/default/page-header.ftl, comment out the existing <img> tag and replace it with one that refers to your logo image (here, clarity-logo.png). Be sure to use the FreeMarker comment style (which begins with <#--) so that FreeMarker won't try to render the markup. Also, go ahead and add a tagline: here, "Maybe a little too clear."

     

    <!-- BEGIN header -->
    <div id="jive-global-header">
        <div id="jive-global-header-texture">
         <a href="<@s.url value="/" />">
    <#--     <img src="${themePath}/images/jive-hdr-logo-cs.png" class="ie6png" /> -->
         <img src="${themePath}/images/clarity-logo.png" class="ie6png" />
         </a><p>Maybe a little too clear.</p>
        </div>
    </div>
    <!-- END header -->

     

    Next, open /styles/theme.css and replace the background style rules with a rule that sets the background to a color you want (here, white seems safe enough).

     

    #jive-global-header {
    /*    background: #18420d url(../images/jive-hdr-bg1.png) repeat-x top; */
        background: white;
        border-bottom: 1px #e9e9e9 solid;
        }
    #jive-global-header-texture {
    /*    background: transparent url(../images/jive-hdr-bg2.png) no-repeat; */
        background: white;
        padding: 10px 15px;
        width: 836px;
    }

     

    Save both files. Put your logo image file in the images folder and zip up your theme files. You'll want to zip the directory that contains the images, styles, and template directories. In the case of the sample, that's the sampleTheme directory.

    Go back to the customizing page (where you downloaded the resource kit) and upload the ZIP you just created. The preview should appear in the window after you click Upload.

    screen_theme_upload.png

    When you click Apply Custom Design, you'll be prompted to confirm changes to files. The first time you apply a theme, the confirmation list will include the addition of all the files in the theme you're uploading. As you make incremental changes, the list of files with be shorter, as shown here.

    screen_theme_confirm_changes.png

    You could try something with each of the source files in the kit until you're familiar with how things work.

    Tips

    Here are a few things to keep in mind as you do your theming:

    • Be sure to check out the FreeMarker documentation. Bugs in your FreeMarker code can be very difficult to find and root out. The more you know, the less likely you'll be frustrated by a bug you don't recognize.
    • The directory hierarchy in your theme is important — things will break if you don't follow the correct pattern. What's in the resource kit is a good example, with a root directory that has subdirectories for images, styles, and template. Within the template directory, the hierarchy is also important.
    • When you're testing, be sure to click around the site a bit while the potential theme is applied.

    Going Beyond the Kit

    The resource kit is a starting place for most simple changes. It includes a set of FTL files that are unlikely to break or become stale when you upgrade. This is by design, to provide you with a reasonably stable way to customize with themes. However, you might find that you need to customize other FTL files on which the UI is based. If you do, of course, you run the risk of making changes that could break the application when you upgrade. For example, if a future version changes functionality of a file on which your customized FTLs depend, those FTLs won't work as you expect.

     

    If you discover you need to customize FTLs other than those included in the resource kit, you can add those to your theme before you ZIP it for upload. For more information on advanced customization, see Advanced Themes Topics.