How to create content blocks (v2)
10 April 2022 475 views | Documentation v2
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.
But since the $viewModel usually holds (or can hold) the data you need to display a block, it's usually easier just to build your block directly into the template.
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.
$block->setTemplate('someTemplate');
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, just like any other content object, using ID as a query parameter.
- Assign it to the viewModel or view for a page (favour the viewModel).
- Include placeholder code to display the block in the template.
You could do this by adding a method within the viewModel to retrieve the block(s) by ID. A generic Trait that provides this functionality is in the works.
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.
Copyright, all rights reserved.