TWiki . Main . BlocksLayoutSystemInstructions

TWiki . Main . BlocksLayoutSystemInstructions

-- DavidHeath - 17 Feb 2004

Introduction

This page outlines the functionality for managing the right hand column under CMS1.5. The approach taken was to replace the frontpage tool with a more flexible 'blocks layout' system. This system can be used for both the right hand column and the main column.

Differences between the frontpage tool and the blocks layout system

frontpage tool	blocks layout system
each block only contains one content item, if you want several articles from the same category, you need to add multiple frontpage 'rows'	each block can contain many or other content objects, depending on the block settings
only article blocks are supported (short or full)	serveral block types are provided (partner, article, text block, job), and new ones are much easier to create for the developer
articles can only be pulled-through by category	articles can be pulled-through by country, category, or any advanced search criteria

Starting off with the new blocks layout tool

The blocks layout tool is accessed from the article module (not the sitemanager module). To access it, click on the layout button on the 'article database' page:

Fig 1: layout button

You will then see the 'layout management' page.

Layout management page

The contents of this pages depends on what layout system is used for the page you are editing. There are several possibilities, depending on the category which you are working on:

if the category does not use any layout system (ie. it does not use the frontpage tool or new layout system or for the Right hand column, it does not have any right hand column container categories), you will be offered the option to create a new layout
if the category currently uses the old frontpage tool for layout, or if there are righthand column items, you will be offered the ability to convert the old layouts
if the category uses the new layout system, you will see the new layout tools

Converting from the frontpage tool

When you first use the layout tool on a category, you will be offered two options:

"No thanks, let me edit the old frontpage"
"Convert frontpage to new blocks system"

See this screenshot for an example.

Option 1 will take you either to:

the frontpage tool, in the case of the main column
or to the category page for the corresponding RHC container category in the case of the right hand column

Option 2 will convert the frontpage to the new blocks layout system, preserving the layout as closely as possible. Please note the following:

you must separately convert the main column and right hand column.
if you want, you may convert just the main, or just the right column, and leave the other one alone (although it's recommended that you convert both)
after conversion the new layouts are "hidden". They can be seen in the layout preview, but do not show up on the live site until they are made visible. This means you can safely try the conversion, without fear of messing up your live site.
whilst a layout is hidden, the old frontpage or right column layout is used, and you can continue to edit that in the old way, until you are ready to make the new layout live.

Special notes on right column conversion:

the new block layout system introduces a new way of generating the 'box' layouts used in the right hand column.
the conversion process attempts to intelligently determine the colour, title and target url used by boxes, however this is not 100% perfect. You should carefully check the appearance of the right hand column after conversion ... you may need to make corrections to the new boxes.

Using the block layout tools

Once you have converted your page, you should have a screen which looks something like this:

example blocklayout page

Each block on the page is shown by a light grey dotted outline, together with its type and id number, and various editing buttons. The editing buttons are shown in figure 2:

Fig 2: block editing buttons

Most of these functions should be fairly self explanatory. However, I'll say a little more about the two most interesting functions:

add new block
edit block

these are the key functions for creating your page layout.

Add new block will take you to a page where you choose the type of the new block.

Edit block will allow to you to the editing page for that particular block. The editing options available depend on the block type.

In order to understand further, you need to go to read about the types of blocks.

Types of blocks

The blocks system has been implemented using a system which allows blocks to behave as specialisations or generalisations of each other. What this means is that there are some block types which are just variations of another block type. This helps to acheive a more uniform behaviour for things which should behave in the same way, whilst allowing other behaviours to vary.

As an example, there is a block type called BlockWithHeading?. Most blocks are specialisations of this type of block, and therefore can do all of the things that a blockwithheading can do (like have a title, target url, colour, etc), as well as the 'specialised' behaviour, such as pulling through articles from a certain category.

The specialisation relationships between the blocks are shown in this diagram: BlockLayoutSystemClassHeirarchy

To help with conversion from the old frontpage tool, here is an explanation of which block types should be used in place of the old frontpage rows:

frontpage row type	block type to use instead
render article	Use TextBlock if your block of text does not contain images. Use SingleArticleBlock if your block does contain images
1 column article	Use ArticleListBlock, set the 'number of articles'
1 short article	Use ArticleListBlock, set the 'number of short articles'
2 column article	Use MultiColumnContainerBlock , combined with two ArticleListBlock elements
render article double	Use MultiColumnContainerBlock , combined with two TextBlock or SingleArticleBlock elements

Here is a description of each block type:

block type	description	use for
BlockWithHeading?	Cannot be used directly, but is a very important block as most blocks are 'specialisations' of this block. The blockwithheading provides: an optional heading (title+target url override) an optional intro paragraph which appears before any block 'contents' a colour scheme, which is only used by boxes in the right hand column. Boxes in the main column adopt the colour scheme of the page	cannot be used directly
ArticleBlock?	another block which cannot be used directly. This provides various controls which are relevant to all blocks containing lists of articles, such as: number of article summaries to show number of 'short' article headlines to show	cannot be used directly
ArticleListBlock	a list of articles from a particular category or topic	use if you just need a simple list of articles from a particular topic or category (replaces frontpage rows: 1 column article, 2 column article, 1 short article)
ArticleCountryBlock?	a list of articles from a particular country or region, similar to ArticleListBlock	use if you want to hilight stories from a particular country or region. There was no equivalent to this in the old frontpage system
ArticleFilterBlock?	a list of articles chosen according to any advanced search criteria	use if ArticleListBlock / ArticleCountryBlock? are not sufficient for your needs.
PartnerFilterBlock?	a list of partners according to advanced search criteria
TextBlock?	an arbitrary block of text.	Use if you need to place some arbitrary text on your page. Cannot include images.
SingleArticleBlock?	a block which shows the summary text of a single article. The summary text can be edited within the block editing page, or you can go to the full article editing page to add article attachments etc.	Use if you need to add images to your block of text
ContainerBlock?	another block class which cannot be used directly. Container blocks can have other blocks added inside them
CategoryContainerBlock?	this block type anchors your layout to a particular category in the system. You cannot create it directly, it is created by the system when you add a page layout
MultiColumnContainerBlock?	this container block divides a column vertically into multiple columns. It can only be used in the main column, not in the right hand column	use if you need to have multiple columns
ContainerWithHeadingBlock?	this is a container with a heading	use if you want to combine multiple blocks under one heading. You should normally turn off the headings on the child blocks, although you may 'nest' boxes inside each other using this block type, but only 1 level deep.

----- Revision r1.2 - 18 Feb 2004 - 12:44 GMT - DavidHeath