Anatomy Of A Content Managed Webpage Login

Contents

  1. Prerequisites
  2. Structure
  3. Web Page Template
  4. Containers
  5. Areas
  6. Webpage Javascript API
  7. Area Formats

This document describes the components that make up a content managed web page within the TOTECS platform. A content managed web page is a web page that can have its content modified by a person, without needing to modify the styling or structure of the web page by writing any programming code.

Prerequisites

  • Knowledge of the TOTECS Administration Centre
  • Knowledge of Content Managed Websites
  • Knowledge of web pages

Structure

Each content managed web page is structured with several components layered on top of each either. The diagram below provides a visual look at how this layering works.
content_managed_webpage_natomy_diagram

The web page is made up of the following components:

  • Web Page Template (always 1 required)
  • Containers (optional)
  • Areas (optional)
  • Area Formats (optional)
  • Format Hooks (optional)

Web Page Template

The web page template is a HTML(Hyper Text Markup Language) file that forms the foundation of the web page. It contains the underlying look and feel of the web page, as well as hooks (also known as placeholders) that dicate where the containers are placed onto the template, which set the areas that can have content modified in.

The same web page template can be assigned to several different web pages, which allow web pages across a content managed web site to have the same consistent look and feel, as well as reducing the work required to create new content managed web pages.

The structure of the web page template is the same of any HTML file, which allows any web designer or developer with HTML skills to create a template and embed any third party functionality such as javascript libraries or Flash.

Template Modes

Templates can be assigned to one of three modes, these are Standard, Secure or Email. The mode dictates where the web pages assigned to the template can be viewed from. A Standard template denotes that it is used for web pages over unsecured web connections (denoted by the HTTP protocol in the browser address). A Secure template denotes that it is used for web pages over secured web connections (denoted by the HTTPS protocol in the browser address). Email templates denotes that it used for web pages assigned to the rich-text part of Emarketing Emails.

Embedding Hooks In A Web Page Template

To embed hooks into a web page template for the containers, you need to use the following format:

<html>
    <head>
        $head_hook$
    </head>
    <body>
        $container_hook$
    </body>
</html>

Hooks are made up of a character sequence surrounded by two dollar symbols. When a web page is rendered to a user these hooks will be replaced by content based on the type of hook that is set. If you wish to place a literal dollar symbol into the template, it must be escaped with the backslash character before the dollar symbol, which would look like \$. This ensures that the web page renderer does not think that you are trying to place a hook after the dollar symbol.

Container hooks within templates are placed within the <body> tags. You can insert an unlimited amount of container hooks into a template. Ensure that each container hook has a unique name,

It is perfectly fine to wrap your hooks around with other HTML elements. This allows you to set parts of a web page that must be displayed to the user. The following example shows how you can add any HTML elements into a template.

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
       <meta charset="UTF-8">
        $head_hook$
        <link rel="stylesheet" type="text/css" href="website_layout.css"/>
        <link rel="stylesheet" type="text/css" href="website_formats.css"/>    </head>
    <body>
        <h1>Shopping Basket</h1>
        <div class="page_summary">$local_shopping_basket_summary$</div>
        <h2>Products</h2>
        <div class="page_content">$local_shopping_basket_products$</div>
    </body>
</html>

Head Hook

Each web page template must have a special hook called head_hook embedded between the <head> tags. This hook gets replaced with any Javascript and CSS (Cascading Style Sheet) resources required to display the page in both Edit mode, or Display mode within TOTECS. If you don't embed the hook then the web page's containers and areas will not be editable, and certain areas will behave unexpectedly.

 

Containers

Containers allow a set of content managed areas to be displayed on a web page in a particular location. A container can have zero to infinite amount of areas created within it. There are two different container types, Local Containers and Global Containers.

Local Containers

Local Containers only hold areas that have been created for a single given web page. They are "local" in the fact that they will contain areas that are available to the web page that they were created within. Local container hooks must be registered against the web page template. Local containers are used when you want admin users creating content in areas that are specific to a single web page.

Global containers

Global containers can hold areas that are displayed on multiple web pages. They are "global" in that the areas that they hold can be displayed across many web pages within a content managed web site. Global container hooks must be registered against the content managed website, and not against the web page template. Global containers are used when you want users being able to see the same areas on multiple web pages, such as a basket summary or list of categories. They can speed up time since you only need to create an area in a global container once, then embed the global containers on all the relevant web page templates that you want it to appear on.

Areas

Areas allow you to set content in one part of a content managed web page. Different types of areas allow different pieces of data to be displayed. There are primarily 2 different kinds of areas, the Free Draw area, and formatted area types.

Free Draw Area

The free draw area is the default area created in containers when a web page is first created. The free draw area allows administrators to embed any kind of text, images or HTML into the area. The free draw forms the foundation of content managed web pages since it allows users to change the content on a web page with the use of an embedded rich-text editor.

Formatted Areas

Unlike the free draw area, there are a range of different formatted area types which will display a set of data, or perform a specific piece of functionality for the user. The content of the area displayed is dependent on formats, which allow certain pieces of data to be embedded into the area in a consistent way. An example of a formatted area is the Category Listing area. It has the ability to display a list of categories, and allow the user the navigate down through a category tree to find the products assign to categories. The area uses a format to display each of the categories the same way, and another format to display each of the products the same way.

There are over 60 different formatted area types that do everything from displaying categories, products, and product deals, through to order submission, enquiry forms, shopping lists, and news/blogs. On the home page of this documentation centre there is a section that lists all of the different areas types which will allow you to learn more on how each area type works.

When you create an area on a content managed web page you get the choice of the type of area that you wish to create, after that if the area chosen is a formatted area then you will need to choose the formats to use for the the area. Additionally each of these formatted areas can contain a number of settings that allows the area to be configured in different ways.

Active State

Areas can be turned on or off at any time by changing the active state of an area. Once an area is turned off it cannot be seen by any users except administrators through the Web Page Editor in the Administration Centre.

Security

Areas can be set to only display for logged in users (private), users not logged in (public), or both. This allows the same web page to be seen by different users in different ways.

Ordering and Moving

Areas can be re-ordered within a container, or be moved from one container to another. A trick to move an area from one web page to another is to move the area from its local container to a global container, then within the other page move it out of the global container and into its new local container.

Popups

Popups can be created against any area in a content managed web page. A popup is a dialog box that appears to the user when they perform an action, such as clicking on a button. The contents inside the popup is decided by assigning a global container to the popup, which will display the associated global areas. Each popup has several options on how to display it, such as width, height, position, dialog title, if it can move, parameters to pass to the areas within the popup. In the formats assigned to a formatted area you can embed  the popup hook into the HTML elements that will call the popup to display.

Note: Because the popup and its hook is tied to the area, the format assigned to the area containing the hook should only be used for the area. If that format is assigned to another area then the popup hook will evaluate out to [INVALID FORM VAR].

Area Events and Overlays

When areas appear on the a content managed web page, each area can fire off different events that cause its own area to redraw itself, or other areas on the web page. An example would be within a Product Detail area, after the user clicks on an add-to-basket button it would cause the Basket Summary areas to update themselves with the new totals of products in the user's basket. Rather than refreshing the whole web page when an event is fired (as was the old way for websites) only the required areas in the web page will redraw themselves by making in-page requests to the server to update their content. This in-page loading makes the web page more responsive, and cuts down on the amount data needing to be downloaded. When an area is reloading itself an overlay will appear over the area to denote that the area is being updated, and stop users from being able to interact with the area until its content has loaded again. You can customise these overlays by applying your own CSS (cascading style sheet) styles to the overlay's HTML structure.

Area Overlay HTML Structure:

<div id="area[areaID]_mask">
    <div class="cms_loadwindow">
        <div class="cms_loadwindow_text">
Overlay Text</div>
    </div>
</div>

Note: the [areaID] is replaced with the actual ID of the area when being rendered on web page. The overlay already has default styles applied to it, so when writing your own CSS styles you will need to use the !important suffix to each styling rule for it to get overloaded.

Adding Your Own Area Reload Javascript Listeners

When an area redraws itself there is an ability to add your own Javascript code that can listen for when an area is about to reload itself, or after it has reloaded itself. This can be handy if a customised action needs to be performed such as re-rendering another part of the page, or calling a popup to display. To have your Javascript listen for area redraws you need to register your listener function when the web page first loads.

Example: Adding a Javascript listener to an area

TOTECS.retail.loader.loadFunction(function(){
    var myFunction = function(type, args, me){
        doSomething();
        TOTECS.retail.fs.removeAreaEventListener(1);
    };

    TOTECS.retail.fs.addAreaEventListener(31, TOTECS.retail.fs.WEBPAGE_AREA_EVENT_TYPES.AFTER_AREA_RELOAD, myFunction, 1, 'args');
});

This code will add a listener to the content managed web page area with the ID 31, after the content managed web page has been fully loaded. When that area is called to be redrawn, after it has been redrawn, the "myfunction" function will be called. In that function it will call the method doSomething(), and then it will remove the event listener so the myFunction is no longer called when webarea 31 is redrawn again.
This code highlights adding area event listeners, that call functions when fired, and then how to remove the listeners when no longer required. Place this code within a javscript file that linked from the head section of a web page template underneath the head hook.

Area Event Javascript Functions

TOTECS.retail.loader.loadFunction(functionToLoad)
Adds a function to be called once a content manage webpage has been fully loaded.
@param functionToLoad {function}          function containing any relevent code

TOTECS.retail.fs.addAreaEventListener(webPageAreaID, eventType, eventListenerFunction, eventID, arguments)
Creates an event listener to a given area or all areas on the web page. The event's listener function is called based when the relevent event type is fired by the area.
@param webPageAreaID {int}                   ID of the web page area to add a listener to, set null to apply to all areas
@param eventType {int}                          ID of the web page area event type
@param eventListenerFunction {function} function to call when the area triggers the given event
@param eventID {string}                          unique identifier to give to the listener
@param arguments {object}                    any object to pass to the event listener function containing any relevant variables
@return boolean                                   true if the listener was added to one or more

TOTECS.retail.fs.removeAreaEventListener(eventID)
Removes one or more area event listeners based on the given event ID.
@param eventID {string}                        ID of the event listener
@param webPageAreaID {int}                 ID of the web page area
@return boolean                                  true if one or more event listeners were removed

TOTECS.retail.fs.showAreaOverlay(webPageAreaID, message)
Displays an overlay within a message on top of an area on the page, based on the given web page area ID
@param webPageAreaID {int}                 ID of the web page area
@param message {string}                    message to display on the overlay

TOTECS.retail.fs.hideAreaOverlay(webPageAreaID)
Hides an overlay that has been placed over the top of an area on the web page
@param webPageAreaID {int}                 ID of the web page area

The event type is dictated by the given object TOTECS.retail.fs.WEBPAGE_AREA_EVENT_TYPES
It contains the following events:
BEFORE_AREA_RELOAD - gets fired before an area is called to be redraw
AFTER_AREA_RELOAD - gets fired after an area has been successfully redraw
BEFORE_PRODUCT_ADD_TO_BASKET - gets fired before a product is being added to basket from within an area
AFTER_PRODUCT_ADD_TO_BASKET - gets fired after a product has successfully been added to basket from within an area
BEFORE_PAGINATOR_RELOAD - gets fired after a user has clicked on a paginator element before the area is reloaded with a new page of data

Webpage Javascript API

For any content managed web page the TOTECS platform supports writing Javscript code that can interact with the Web Page API (Application Programming Interface). This allows highly customisable functionality to be run on a web page to do things such as showing customised popups when webpage areas reload, or when users interact with different elements on a web page. Below is a list functions that are available to call when writing Javascript.

Adding Your Own Area Reload Javascript Listeners

When an area redraws itself there is an ability to add your own Javascript code that can listen for when an area is about to reload itself, or after it has reloaded itself. This can be handy if a customised action needs to be performed such as re-rendering another part of the page, or calling a popup to display. To have your Javascript listen for area redraws you need to register your listener function when the web page first loads.

Example: Adding a Javascript listener to an area

TOTECS.retail.loader.loadFunction(function(){
    var myFunction = function(type, args, me){
        doSomething();
        TOTECS.retail.fs.removeAreaEventListener(1);
    };

    TOTECS.retail.fs.addAreaEventListener(31, TOTECS.retail.fs.WEBPAGE_AREA_EVENT_TYPES.AFTER_AREA_RELOAD, myFunction, 1, 'args');
});

This code will add a listener to the content managed web page area with the ID 31, after the content managed web page has been fully loaded. When that area is called to be redrawn, after it has been redrawn, the "myfunction" function will be called. In that function it will call the method doSomething(), and then it will remove the event listener so the myFunction is no longer called when webarea 31 is redrawn again.
This code highlights adding area event listeners, that call functions when fired, and then how to remove the listeners when no longer required. Place this code within a javscript file that linked from the head section of a web page template underneath the head hook.

Web Page API Javascript Functions

TOTECS.retail.loader.loadFunction(functionToLoad)
Adds a function to be called once a content manage webpage has been fully loaded.

Argument Data Type Description
functionToLoad function function containing any relevent code

 

TOTECS.retail.fs.addAreaEventListener(webPageAreaID, eventType, eventListenerFunction, eventID, arguments)
Creates an event listener to a given area or all areas on the web page. The event's listener function is called based when the relevent event type is fired by the area.

Argument Data Type Description
webPageAreaID  int ID of the web page area to add a listener to, set null to apply to all areas
eventType int ID of the web page area event type
eventListenerFunction function function to call when the area triggers the given event
eventID string unique identifier to give to the listener
arguments object any object to pass to the event listener function when its fired
     
Returns boolean true if the listener was added to one or more areas

 

TOTECS.retail.fs.removeAreaEventListener(eventID)
Removes one or more area event listeners based on the given event ID.

Argument Data Type Description
eventID string ID of the event listener
webPageAreaID int ID of the web page area
     
Returns boolean true if one or more event listeners were removed

 

TOTECS.retail.fs.showAreaOverlay(webPageAreaID, message)
Displays an overlay within a message on top of an area on the page, based on the given web page area ID

Argument Data Type Description
webPageAreaID int ID of the event listener
message string message to display on the overlay

 

TOTECS.retail.fs.hideAreaOverlay(webPageAreaID)
Hides an overlay that has been placed over the top of an area on the web page

Argument Data Type Description
webPageAreaID int ID of the web page area

 

TOTECS.retail.fs.createWebPageAreaPopupDialog(webPageAreaID, webPagePopupID, containerAreaID, title, cssClass, isModal, isMovable, width, height, zindex, positionType, positionPixelX, positionPixelY, positionAlignX, positionAlignY, loadingMessage, dialogArgs)
Creates and shows a pop up dialog displaying areas of a global container within the content managed website, removes any previous popup dialog if it matches the same ID

Argument Data Type Description
webPageAreaID string ID of the web area calling the popup to be drawn, may be set to null if no specific area calls the popup to display
webPagePopupID string Unique ID of the web area pop up
containerAreaID string ID of the global website container to load into the popup
title string title of the popup
cssClass string CSS class to set for the popup
isModal bool if true maintain the popup over all other page elements
isMovable bool if true allow the popup to be moved
width int width of the popup in pixels, set to 0 to ignore setting a fixed width of the dialog
height int height of the popup in pixels, set to 0 to ignore setting a fixed hieght of the dialog
zindex int z-index of the pop up
positionType enum either 'FIXEDCENTER', 'PIXEL' or 'ALIGNMENT', sets the positioning for the popup
positionPixelX int absolute x pixel position of the popup, only used when position type is set to 'PIXEL'
positionPixelY string either 'TOP', 'MIDDLE', 'BOTTOM', sets the y alignement of the dialog, only used when position type is set to 'ALIGNMENT'
positionAlignX string either 'LEFT', 'CENTER', 'RIGHT', sets the x alignement of the dialog, only used when position type is set to 'ALIGNMENT'
positionAlignY string either 'TOP', 'MIDDLE', 'BOTTOM', sets the y alignement of the dialog, only used when position type is set to 'ALIGNMENT'
loadingMessage string message to display when loading the global web page areas within the popup
dialogArgs  string list of arguments to pass on to web page areas drawn within the popup

TOTECS.retail.fs.showWebPageAreaPopupDialog(webPagePopupID)
Shows an existing web page area popup if it has been previously created on the webpage.

Argument Data Type Description
webPagePopupID string ID of the web page Popup ID

TOTECS.retail.fs.updateWebPageAreaPopupDialogClass(webPagePopupID, cssClass)
Updates the CSS class of an existing web page area popup if it has been previously created on the webpage.

Argument Data Type Description
webPagePopupID string ID of the web page Popup ID
cssClass string CSS class to set within the popup

TOTECS.retail.fs.hideWebPageAreaPopupDialog(webPagePopupID, removePopup)
Hides an existing web page area popup if currently displayed, and optionally allows it to be removed.

Argument Data Type Description
webPagePopupID string ID of the web page Popup ID
removePopup bool if true then removes the web page area popup from the web page and all associated in memory objects

The event type is dictated by the given object TOTECS.retail.fs.WEBPAGE_AREA_EVENT_TYPES
It contains the following events:

BEFORE_AREA_RELOAD gets fired before an area is called to be redraw
AFTER_AREA_RELOAD gets fired after an area has been successfully redraw
BEFORE_PRODUCT_ADD_TO_BASKET gets fired before a product is being added to basket from within an area
AFTER_PRODUCT_ADD_TO_BASKET gets fired after a product has successfully been added to basket from within an area
BEFORE_PAGINATOR_RELOAD gets fired after a user has clicked on a paginator element before the area is reloaded with a new page of data
BEFORE_PRODUCT_COMBINATION_CHILD_LOAD gets fired after a user has caused a webpage area showing a combination product to load a selected child product. The event gets called before the child product is displayed within the area.
AFTER_PRODUCT_COMBINATION_CHILD_LOAD gets fired after a user has caused a webpage area showing a combination product to load a selected child product. The event gets called after the child product has been displayed within the area
AFTER_PRODUCT_ADD_TO_SHOPPING_LIST gets fired after a product has successfully been added to shopping list from within an area

Area Formats

All formatted areas on a content managed web page use "formats" to define the structure, styling and content around pieces of data available to the given area. Formats are made up from HTML with hooks imbedded (just like web page templates) that dictate where certain types of data are placed within the area. Formats are used to provide consistency when the same kind of data needs to be repeatably shown, such as a list of products assigned to product category.

There are numerous different types of formats available to areas, and the hooks available, as well as the way the formats are placed in the area is dependent on the type of formatted area being used.

Format Hooks

Within each format are hooks, which are place holders for a single piece of data specific to the format and area. You can find out about the data a hook inserts by clicking on a hook within the Format Editor dialog in the Websites interface of the Administration Centre

Global Formats

A global format is available across all projects within the TOTECS platform. The global formats are made available to the entire TOTECS community and are never deleted or changed (they may become deprecated though). They are useful as a guide to creating your own formats, or being used on content managed websites deployed initially out-of-the-box.

Local Formats

A local format exists only within a single TOTECS project. Typically these formats are customised to one or two content managed websites in the project.