Creating blocks

5 February 2018 | 36 views | Tags: Documentation

About blocks

Blocks are more "manual" in Tuskfish than in most mainstream content management systems, in that there is no administrative interface for actually 'positioning' blocks on your site. The reason for this is flexibility - while positioning systems are cool they lock you into a set layout grid where you have a fixed number of columns or statically defined content zones.

By contrast Tuskfish makes no assumptions about your site layout. You can use a radically different design on every page if you want to, or even vary the layout template for a particular page programmatically. The price for this flexibility is that you must retrieve the blocks you want to use and assign them to content zones in the template manually.

This may change in future, I'm still thinking about it. Basically I don't really want Tuskfish to be locked into the same old three-column + header and footer "portal" look that most other CMS have. That's what would happen, if I went down the road of standardised content zones.

Static blocks

Static blocks are just another kind of content object and you create them through the content management form, selecting block as the content type. Static blocks are limited to plain HTML content. Use them when you want to display a piece of fixed content.

You need to retrieve static blocks from the database and assign them to a template with a receiving placeholder in order to display them, just like any other type of content. However, since blocks are (usually) a component of the main template layout, you should assign them to $tfish_template towards the end of the script.

// Retrieve a static block with ID = 3, render it and assign to the block_3 content zone.
$blockObj = TfishBlockHandler::getObject(3);
$tfish_template->block = $blockObj;
$tfish_template->block_3 = $tfish_template->render('block');

In the HTML template file:

// To display the block echo it in the relevant template file:
<div id="block_3">
    <?php echo $block_3; ?>
</div>

For more information see Assigning data to templates and Rendering templates. There is no reason why you can't embed a block in another piece of content (for example in a news story), but you will need to modify the receiving template to accommodate it.

Dynamic blocks

Dynamic blocks must be created programmatically; there are several variants available that ship with Tuskfish including:

  • List: Displays a bullet list of content titles, eg. last 10 news articles.
  • Carousel: Display a rotating slide show of images with titles and links.

To use these blocks you must create a new instance, pass in the relevant configuration parameters and assign it to a template that will be displayed on your page. It's a similar process to loading a static content block except that you must pass in configuration information.

Note that dynamic blocks are not persistent, in that they are not stored in the database. However, they will be captured by the page caching system, and so they don't need to be rebuilt on every page load.

Creating your own dynamic blocks

[Note: I will expand this section when I create more dynamic blocks, but for now this is just an outline of the process].

Creating a new type of dynamic block is a simple matter. For single / casual use you can just:

  • Create a template file and add it to the themes you are using.
  • Load the data you need and assign it to $tfish_template
  • Render your template
  • Assign the block template to the main layout template.

Or, you can formalise your new block by writing a class for it. To do this:

  • Extend the TfishBlock class.
  • Use the constructor to accept any required parameters and set up your block object.
  • Create a template for displaying your block and save it in the template sets that you are using.

Actually using your new block then becomes a case of:

  • Retrieving any content you want to use as an input parameter.
  • Instantiating the block, passing in required configuration parameters.
  • Assigning the block to the template.

Copyright, all rights reserved.

Related

Tuskfish CMS Developer Guide

This guide will give you an overview of the architecture of Tuskfish CMS, how to write code to perform common operations and how to extend the system to suit yourself. The guide accompanies the Tuskfish API documentation. Keep a copy handy as you read this guide. It is best to review links to the API where provided, as not every detail will be discussed in the text. This is the first version of the guide, so it is still a work in progress.