Custom Home Page Overview

Required Skills

This article assumes that the reader has a basic understanding of:

  • HTML
  • CSS
  • JavaScript
  • XML

Overview

FocusOPEN 3.4.2 and above features a home page template engine which allows users to create customisable, redistributable template-based home pages that can be both edited by administrators without technical knowledge and used to develop sophisticated and dynamic home page designs.

Bundled Home Page Templates

FocusOPEN comes with the following home page templates:

  • Standard - HTML text, featured categories and four quick links
  • Library - a gallery style rows of thumbnail images
  • Magazine - HTML, featured image and a series of tiled, clickable images

Administration of Home Page Templates

To change, edit and apply home page templates, you need to log in as a super administrator and navigate to Admin > Content > Manage Homepage.

From the 'Template' dropdown menu, select the template you wish to edit and/or apply.

After selection, you will be presented with a number of form-based elements (or widgets), including HTML text areas, input fields and file fields to upload images etc. See later in this document to learn more about widgets and creating your own home page templates.

The Anatomy of a Home Page Template

Home page templates are brand-specific - that's to say for a template to work across all brands, it must be included within each brand's directory structure. Each template must reside in the 'Homepage' directory within the brand folder:

\WebRoot\Brands\Brand_1\Homepage

Each template comprises a number of files:

markup.html

This file contains the HTML for your homepage. It can also contain JavaScript or links to supporting files such as additional stylesheets or jQuery libraries. The JavaScript to process the widgets and populate the template is also included in this file An example of the code within the 'Magazine' markup.html page is shown below.

<script type="text/javascript">
    // Important - remember to update this homepage type ID when copying this markup to other templates
    // The homepageTypeId is equal to 100 + the zero-based index of the current template in the templates.xml 
    // file, e.g. for the first template it's 100+0=100, for the fourth - 100+3 = 103, etc.
    // This is only needed for templates that use homepage images (widgets 2 and 4 - Thumbnail and 
    // CustomImageFlashTile) - for other types it can be safely deleted
    var homepageTypeId = 100;

    function populateTemplate(json) {

        var imageUrl = "Images/HomepageTile." + homepageId + ".ashx?image=";

        var headerImage = json.data.widgets[0].data;
        $('#WelcomeHeadingImg').attr('src', imageUrl + headerImage.tile_id + "&homepageTypeId=" + homepageTypeId);
        $('#WelcomeHeadingImg').attr('alt', headerImage.Title);

        var mainImage = json.data.widgets[1].data;
        $('#WelcomeMainImg').attr('src', imageUrl + mainImage.tile_id + "&homepageTypeId=" + homepageTypeId);
        $('#WelcomeMainImg').attr('alt', mainImage.Title);

        var url = json.data.widgets[2].data;
        $('.section_image a').attr('href', url.text);

        var mainText = json.data.widgets[3].data;
        $('#MainSectionText').html(mainText.html.Cdata);

        for (i = 1; i < 7; i++) {
            var thumb = json.data.widgets[i + 3].data;
            $('#widget_' + i + ' .section_text').html(thumb.tile_text);
            $('#widget_' + i + ' .section_title').html(thumb.heading);
            var imgId = (i + 6);
            $('#widget_' + i + ' .section_image img').attr('src', imageUrl + imgId + "&homepageTypeId=" + homepageTypeId);
            $('#widget_' + i + ' .section_image a').attr('href', thumb.URL);
        }
    }
</script>

Studying the code, we can see that it uses jQuery to programmatically target and populate the DOM elements within our markup.html file.

markup.css

This file, as the name suggests, is for storing the style declarations that apply to markup.html file (and any other elements that require CSS styles applied).

template.xml

This file contains the widgets that make up a home page template, a full list of which can are listed under 'Template Widgets' below. Depending upon the complexity of the home page, this file can contain any number of XML nodes, each one declaring the widget to be used and any additional configuration variables (including default values).

There are two additional files that are automatically created at runtime by the home page editor:

Template_instance.preview.xml Template_instance.xml

These files are responsible for storing the template preview and the values entered into the home page editor respectively.

Example template.xml File - Magazine

Below is an extract of the 'Magazine' template, showing its component widgets. Note how the widgets directly relate to the elements shown in the admin home page editor (see screenshot).

<template>
  <markup src="markup.html">template markup here</markup>
  <!--<bumper_markup src="bumper.html">bump bump bump bump bump bump bump </bumper_markup>-->
  <instructions><![CDATA[Supply content for each of the sections shown below and click preview to see your home page, then publish to make it live.]]></instructions>
  <widgets>
  
    <widget>
      <name>Welcome Panel Heading Image</name>
      <type_id>2</type_id>
      <instructions>This is usually a welcome text rendered as an image, e.g. "Welcome to the Digital Asset Management System"</instructions>
      <editor_settings>
        <width>200</width>
        <height>50</height>
      </editor_settings>
      <data>
        <tile_type>Image</tile_type>
        <tile_id>5</tile_id>
        <title/>Welcome<title/>
        <url></url>
        <description>enter description here</description>
      </data>
    </widget>
    
    <widget>
      <name>Welcome Panel Main Image</name>
      <type_id>2</type_id>
      <instructions>This is the image for the central area of the welcome panel that will also be a link (if an URL is provided)</instructions>
      <editor_settings>
            <width>300</width>
        <height>240</height>
      </editor_settings>
      <data>
        <tile_type>Image</tile_type>
        <tile_id>6</tile_id>
        <title/>Welcome<title/>
        <url></url>
        <description>enter description here</description>
      </data>
</widget>


...etc

  </widgets>
</template>

Below is a screenshot showing part of the admin interface for the Magazine template.

Declaring Available Templates

Before a home page template can be used, FocusOPEN needs to be told about it. This is done via the 'templates.xml' file which resides in the root of the Homepage folder. This file contains a nested list of all the available templates. If you create your own, it must be added here before you can use it and access its administration interface. Below is an example of the basic templates.xml file.

<?xml version="1.0" encoding="utf-8"?>
<templates>
    <template active="true" bumper_active="true">
        <name>Magazine</name>
        <folder>Magazine</folder>
    </template>
    <template active="true" bumper_active="true">
        <name>Library</name>
        <folder>Library</folder>
    </template>
    <template active="true" bumper_active="true">
        <name>Basic Example</name>
        <folder>Basic_Example</folder>
    </template>
     <template active="true" bumper_active="true">
        <name>Dynamic</name>
        <folder>Dynamic</folder>
    </template>
</templates>

Template Widgets

Below are the various widgets that can be used when creating home page templates. Widgets are constructed using XML, and when combined, can be used to create veruy complex homepage templates.

Custom HTML

This widget allows the admin to generate HTML content via a rich text editor.

<widget>
<name>Main Text</name>
<type_id>1</type_id>
<instructions>Enter some text</instructions>
<editor_settings>
<width>600px</width>
<height>200px</height>
</editor_settings>
<data>
<html><![CDATA[<i>initial</i> content]]></html>
</data>
</widget>

Custom Image/Flash Tile

This widget allows the display of an arbitrary image or Flash movie, with a title and URL.

Sample Definition

<widget>
<name>Test image/flash tile</name>
<type_id>2</type_id>
<instructions>Provide an image or flash for the tile</instructions>
<editor_settings>
<width>100</width>
<height>100</height>
</editor_settings>
<data>
<tile_type>Flash</tile_type>
<tile_id>11</tile_id>
<title>Welcome</title>
<url>http://www.daydream.co.uk</url>
<description>enter description here</description>
</data>
</widget>

Text Field

A building block option to display a simple input text field - useful for displaying basic text-only or numeric values.

Sample Definition

<widget>
<name>Text Field test</name>
<type_id>3</type_id>
<instructions>Enter some text below</instructions>
<editor_settings>
<width>150px</width>
</editor_settings>
<data>
<text>sample text</text>
</data>
</widget>

Thumbnail

The thumbnail is a tile widget – like the image/flash control. It displays an image with additional text fields – it facilitates the right-hand side of the 'Magazine' template.

Sample Definition

<widget>
<name>Thumbnail 1</name>
<type_id>4</type_id>
<instructions>Enter heading, image, link and text for the
thumbnail</instructions>
<editor_settings>
<width>188</width>
<height>90</height>
</editor_settings>
<data>
<tile_id>7</tile_id>
</data>
</widget>

Preview Plugin

The preview plug-in control will allow the administrator to incorporate mark-up from a preview control on the home page for a given asset. These are usually used on the asset detail pop-up page and are abstracted components that allow viewers for different types of assets.

Sample Definition

<widget>
<name>Test preview plugin</name>
<type_id>5</type_id>
<instructions>Enter the asset ID of the asset preview
to display</instructions>
<editor_settings>
</editor_settings>
<data>
<asset_id>1</asset_id>
</data>
</widget>

Asset Thumbnail

The Asset Thumbnail control allows the admin user to choose a thumbnail to display on the home page and also an optional hyperlink and description.

Sample Definition

<widget>
<name>Asset thumbnail test</name>
<type_id>6</type_id>
<instructions>Enter the asset ID of the thumbnail to
display</instructions>
<editor_settings>
</editor_settings>
<data>
<show_popup>false</show_popup>
<url>http://focusopen.net</url>
<description>Asset thumbnail</description>
<asset_id>40</asset_id>
</data>
</widget>

Asset Bitmap

The asset bitmap home page widget is the same as the thumbnail, except the admin user is allowed to specify the asset bitmap group they want to display.

Asset bitmap groups are additional static bitmaps generated in addition to thumbnails and previews. They are not usually displayed in search results and when viewing assets but can be used by preview plug-ins or other custom client-side code in preview plug-ins.

These are defined in the Config/AssetBitmapGroups.config file. By default, FocusOPEN generates 6 sizes, but this can be extended by editing this file and adding an additional size. For example, this definition is for bitmap group 4:

<AssetBitmapGroup>
<Reference>4</Reference>
<MaxWidth>300</MaxWidth>
<MaxHeight>300</MaxHeight>
</AssetBitmapGroup>

The size ranges are:

  • 100 x 100
  • 150 x 150
  • 200 x 200
  • 300 x 300
  • 450 x 450
  • 600 x 600

If you add definitions to this config file, you need to use the batch menu option to regenerate previews for any you wish to use.

Sample Definition

<widget>
<name>Asset bitmap test</name>
<type_id>7</type_id>
<instructions>Choose the required size group and enter the asset ID of
the bitmap to display.</instructions>
<editor_settings>
</editor_settings>
<data>
<show_popup>false</show_popup>
<url>http://focusopen.net</url>
<description>Asset bitmap</description>
<size_group>2</size_group>
</data>
</widget>

Featured Categories

The featured categories control allows the user to select categories they want to appear on the home page.

Sample Definition

<widget>
<name>Featured categories</name>
<type_id>8</type_id>
<instructions>Choose the categories to feature on the home page</instructions>
<editor_settings>
</editor_settings>
<data>
</data>
</widget>

Get Remote URL Content

This option allows the administrator to specify a URL for remote dynamic content that will be inserted into the page or processed client-side as deemed necessary by the template author.

Sample Definition

<widget>
<name>Get remote URL content</name>
<type_id>9</type_id>
<instructions>Enter a URL to retrieve content from</instructions>
<editor_settings>
</editor_settings>
<data>
</data>
</widget>

Anchor-Hyperlink

This allows the template author to specify a URL for the administrator to enter.

Sample Definition

<widget>
<name>Link test</name>
<type_id>10</type_id>
<instructions>Enter a URL and anchor text</instructions>
<editor_settings>
</editor_settings>
<data>
<anchor>link</anchor>
</data>
</widget>

Text Area

A building block option to allow the template author to ask the administrator for longer text content, with no rich formatting.

Sample Definition

<widget>
<name>Text area test</name>
<type_id>11</type_id>
<instructions>Enter your text below</instructions>
<editor_settings>
<width>100%</width>
<height>150px</height>
</editor_settings>
<data>
</data>
</widget>

Asset ID

A widget to allow the user to choose an asset ID. The asset must exist on the system (not deleted or out of range) when initially entered.

Sample Definition

<widget>
<name>AssetID test</name>
<type_id>12</type_id>
<instructions>Enter asset ID below</instructions>
<editor_settings>
</editor_settings>
<data>
<asset_id>1</asset_id>
</data>
</widget>

Calendar

Allows the template author to ask for an arbitrary date.

Sample Definition

<widget>
<name>Calendar test</name>
<type_id>13</type_id>
<instructions>Choose a date below</instructions>
<editor_settings>
</editor_settings>
<data>
</data>
</widget>

Bumper Pages

Bumper pages provide the ability to added a transitional page just before the home page appears. This is useful for displaying introductory text, a temporary notice or a promotional image or message that shows for a short time before proceeding.

Bumper page code is stored by checking the ' Include Bumper Page' checkbox. A textarea will be revealed where you can paste in your HTML code.

The second checkbox tells the system to only show the bumper page once per (browsing) session.

 
custom-homepage-overview/start.txt · Last modified: 2012/06/25 18:09 by admin