Tuskfish does not have an administrative interface for positioning blocks on your site. The reason for this is flexibility - while positioning systems are convenient they also introduce constraints, in that you typically have to:

• Assign block positions against a matrix of pre-defined standard columns or zones (eg. left, right, centre top, etc) and a pre-defined list of pages or modules.
• Define additional zones for placing blocks, if you want to use non-standard positions. This usually requires modification of your theme or template files to insert placeholders for the new zones.
• Run additional database queries to discover which blocks are registered for use on any given page and zone.

By contrast Tuskfish makes no assumptions about layout. You can use a radically different design on every page if you want to, or even vary the layout for a particular page programmatically, by assigning different themes and templates at runtime.

The price for this flexibility is that creation of zones and positioning of blocks is a more manual process. While you can submit static (but not dynamic) blocks through the admin interface, they are retrieved by the controller script (PHP page) and manually positioned in your theme files. This is probably the most difficult aspect of Tuskfish for a novice webmaster, since it requires some elementary understanding of PHP.

Creating static blocks

Create a static block when you want to display a piece of fixed, plain HTML content on your site. The quick and dirty method is to simply hard code static blocks into the main layout file of your theme. If you have a basic understanding of HTML this is often faster, plus it has the advantage that no database queries are required.

If you want to be able to vary the contents of a static block occasionally, you can create them through the standard content management form, selecting 'block' as the content type. They are just another kind of content object. You have access to the TinyMCE editor to help prepare your block, although it may "improve" your HTML, which can be annoying (TinyMCE will not tolerate block-level links; you have to keep links inline, eg. you can't wrap a link around <p> tags; you have to put it inside or it will start hacking your HTML to pieces).

The default block template simply displays the block title and description. If you would like to have a custom block layout, you may wish to develop your own custom templates for different block types and assign them to the relevant blocks (override the default) at runtime. To assign a custom template to a block (or any content object), just set the value of the template property. The custom template must be present in the active theme directory:

// Just pass in the name of the custom template, do not include the .html extension.
$content->template = 'customTemplate';

Note that blocks do not appear in your site’s content stream, RSS feed or search results.

Displaying a single static block based on its ID

To display a static block you need to:

• Retrieve it from the database programmatically in your controller script (the PHP page you want to display it on), just like any other content object.
• Render the block for display and assign it to the global $tfish_template object.
• Add an output placeholder to the theme’s main layout file, in the position that you want to display the block.

For example, to retrieve a single block and assign it to $tfish_template in a controller script:

// Retrieve a single static block from the database based on its ID (eg. 37).
$blockHandler = $contentFactory->getContentHandler('block');
$blockObj = $blockHandler->getObject(37); // Retrieve block 37.
$tfTemplate->block = $blockObj; // Assign block object to $tfish_template.
$tfTemplate->block_37 = $tfTemplate->render('block'); // Render block.html template.
unset($block); // Clean up in case you want to retrieve more blocks.

Position the block anywhere you like by inserting a placeholder in the main layout file for your template, eg. ‘default.html’ in the default theme:

<!-- Display block 37 -->
<div><?php echo $tfTemplate->block_37; ?></div>

You may care to review the default static block template (block.html) to see how it will display:

// Only display block if it has been set.
<?php if isset(($block)): ?>

// Display the title, if set.
<?php if ($block->title): ?>
    <div class="block-title"><h3><?php echo $block->getTitle(); ?></h3></div>
<?php endif; ?>

// Display the description, if set.
<?php if ($block->description): ?>
    <div class="block-description"><?php echo $block->getDescription(); ?></div>
<?php endif; ?>

<?php endif; ?>

You can modify block.html to display other properties of block 37 (if it has any), as you wish. You could also create your own alternative block templates and assign one of those instead. Just drop them into the directory of the relevant theme.

Displaying multiple static blocks based on criteria

You can retrieve multiple blocks from the database matching certain criteria. For example, perhaps you want to retrieve blocks that have been labelled with a user-supplied tag ID and assign them to a centre-top zone that you have defined in your theme:

// Prepare $criteria for retrieving blocks associated with a tag ID parameter:

$criteria = $tfCriteriaFactory->getCriteria(); // Create a query composer object.
if ($cleanTag) $criteria->setTag(array($clean_tag)); // Set tag ID to filter by.
$criteria->add($tfCriteriaFactory->getItem('online', 1)); // Online blocks only.
$criteria->setOrder('title'); // Sort the blocks alphabetically, by title...
$criteria->setOrdertype('ASC'); // ...from A-Z.

// Retrieve the blocks.
$blockObjects = $centreTopBlocks = array();
$blockHandler = $contentFactory->getContentHandler('block');
$blockObjects = $blockHandler->getObjects($criteria);

<-- Render blocks and add to array -->
foreach ($blockObjects as $key => $block) {
    $centreTopBlocks[] = $tfTemplate->render('block');
    unset($block);
}

// Assign centre-top block zone to template.
$tfTemplate->centreTopBlocks = $centreTopBlocks;

In this example the blocks have been filtered using a tag ID that is supplied as a page parameter, and the results have been sorted alphabetically in ascending order. But you can filter and sort your queries using any property of the blocks and place a limit on how many blocks you want to retrieve or offset the results. For more information about using criteria and constructing queries to retrieve data objects please see the Tuskfish Dev Guide.

Dynamic blocks

Dynamic blocks must be created programmatically; they cannot be submitted via the content entry form as code is not permitted, and they are not stored in the database. Standard dynamic blocks will be added to Tuskfish in due course. Creating your own dynamic blocks is fairly straightforward, although basic knowledge of PHP is required. Please see the Tuskfish Developer Guide for more information.